The integer_t class template. More...

Public Types
typedef base_divide_t < integer_t<...> >	divide_t
Public Member Functions
Constructors & Destructors

	integer_t ()
	Creates a new integer with an initial value of zero.
	integer_t (const integer_t<...> &b, bool force_thread_safety=false)
	Creates a copy of an existing integer.
	integer_t (BOOST_XINT_RV_REF(type) b)
template<typename charT >
	integer_t (const charT *str, std::size_t base=10)
template<typename charT >
	integer_t (const charT str, const charT &endptr, std::size_t base=10)
	Parse an integer from a string representation.
template<typename charT , typename traitsT , typename allocT >
	integer_t (const std::basic_string< charT, traitsT, allocT > &str, std::size_t base=10)
	Create an integer from a string representation.
	integer_t (const xint::binary_t b, bitsize_t bits=0)
	Converts a portable binary representation of a number into an integer.
template<other >
	integer_t (const integer_t< other > &other, bool force_thread_safety=false)
template<typename Type >
	integer_t (const Type n, typename boost::enable_if< boost::is_integral< Type > >::type *=0)
Mathematical and Bitwise Operators
These operate exactly like their counterparts for the built-in integer types.
integer_t<...> &	operator= (BOOST_XINT_COPY_ASSIGN_REF(type) c)
integer_t<...> &	operator= (BOOST_XINT_RV_REF(type) c)
template<typename Type >
integer_t<...> &	operator= (const Type n)
	operator safe_bool_type () const
bool	operator! () const
integer_t<...>	operator- () const
	Return the additive inverse of an integer.
integer_t<...> &	operator+ ()
const integer_t<...> &	operator+ () const
integer_t<...>	operator~ () const
	The Bitwise Ones Complement (i.e. bitwise NOT) operator.
integer_t<...> &	operator+= (const integer_t<...> b)
integer_t<...> &	operator-= (const integer_t<...> b)
integer_t<...> &	operator*= (const integer_t<...> b)
integer_t<...> &	operator/= (const integer_t<...> b)
integer_t<...> &	operator%= (const integer_t<...> b)
integer_t<...> &	operator++ ()
integer_t<...> &	operator-- ()
integer_t<...>	operator++ (int)
integer_t<...>	operator-- (int)
integer_t<...> &	operator&= (const integer_t<...> n)
integer_t<...> &	operator\|= (const integer_t<...> n)
integer_t<...> &	operator^= (const integer_t<...> n)
integer_t<...>	operator<< (bitsize_t shift) const
	Left-shift an integer by a specified number of bits.
integer_t<...>	operator>> (bitsize_t shift) const
	Right-shift an integer by a specified number of bits.
integer_t<...> &	operator<<= (bitsize_t shift)
integer_t<...> &	operator>>= (bitsize_t shift)
Miscellaneous Functions

bool	is_odd () const
	Tests the lowest bit of `*this` to determine oddness.
bool	is_even () const
	Tests the lowest bit of `*this` to determine evenness.
int	sign (bool signed_zero=false) const
	Tests the sign of `*this`.
std::size_t	hex_digits () const
	Tells you roughly how large `*this` is.
bool	is_nan () const
	Tests whether the object is a Not-a-Number.
Static Public Member Functions
Static Member Functions
These are functions that return an integer_t, but don't take one as a parameter. To use them as free functions, you would have to specify the return type anyway, so they're static member functions of the type instead.
static integer_t<...>	pow2 (std::size_t exponent)
	Calculate the value of 2^e
static integer_t<...>	factorial (std::size_t n)
	Calculate the value of `n!`
static integer_t<...>	nan ()
	Returns a Not-a-Number value, for types that support it.
template<class Type >
static integer_t<...>	random_by_size (Type &gen, bitsize_t size_in_bits, bool high_bit_on=false, bool low_bit_on=false, bool can_be_negative=false)
	Generates a random integer with specific attributes.
template<class Type >
static integer_t<...>	random_prime (Type &gen, bitsize_t size_in_bits, callback_t callback=no_callback)
	Generate a randomly-generated prime number of a particular bit-size.

Detailed Description

template<...>
class boost::xint::integer_t<>

The integer_t class template.

This class implements the standard aribitrary-length integer type.

There are only a few member functions, primarily operators. Most of the functionality is implemented using standalone functions.

You can specify several template parameters for the type. Most of these parameters must be specified via helper classes defined in the boost::xint::options namespace. See the list and descriptions there.

Here are some examples of how to specify an integer type:


    namespace xopts = boost::xint::options;
    typedef boost::xint::integer_t<xopts::fixedlength<512>, xopts::secure,
        xopts::negative_modulus> secure_uint512;
    typedef boost::xint::integer_t<my_allocator<boost::xint::detail::digit_t>,
        xopts::copy_on_write> my_integer;

Note that the basic integer and nothrow_integer types are already typedef'd for you.

Definition at line 50 of file integer.hpp.

Member Typedef Documentation

template<... >

typedef base_divide_t<integer_t<...> > boost::xint::integer_t<>::divide_t

Definition at line 147 of file integer.hpp.

Constructor & Destructor Documentation

template<... >

boost::xint::integer_t<>::integer_t ( )

Creates a new integer with an initial value of zero.

Definition at line 224 of file integer.hpp.

template<... >

boost::xint::integer_t<>::integer_t	(	const integer_t<...> &	b,
		bool	force_thread_safety = `false`
	)

Creates a copy of an existing integer.

Parameters:

`[in]`	b	An existing integer.
`[in]`	force_thread_safety	If the `threadsafe` template parameter is `false`, you can use this to make a thread-safe copy anyway. See this page for a full treatment of the matter.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 239 of file integer.hpp.

template<... >

boost::xint::integer_t<>::integer_t ( BOOST_XINT_RV_REF(type) b ) [inline]

Definition at line 61 of file integer.hpp.

template<... >

template<typename charT >

boost::xint::integer_t<>::integer_t	(	const charT *	str,
		std::size_t	base = `10`
	)			`[explicit]`

Create an integer from a string representation.

Complexity: O(n²)

Parameters:

`[in]`	str	A string representation of a number.
`[in]`	base	The base that the string representation of the number is in. This can be any number between 2 and 36 (inclusive). It can also be the constant xint::autobase, in which case the function will follow the standard C/C++ rules for interpreting a numeric constant: any number with a zero as the first digit is assumed to be base-8; any number with a leading zero-x or zero-X (such as 0x1f) is base-16, and anything else is base-10.

Exceptions:

	exceptions::invalid_base	if the base parameter is not between 2 and 36 (inclusive) or the constant xint::autobase.
	exceptions::invalid_digit	if the string contains any digit that cannot be part of a number in the specified base, or if there are no valid digits.

Remarks:: This is the most common way to initialize literal values that are too large to fit into a native integral type.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 261 of file integer.hpp.

template<... >

template<typename charT >

boost::xint::integer_t<>::integer_t	(	const charT *	str,
		const charT *&	endptr,
		std::size_t	base = `10`
	)

Parse an integer from a string representation.

Complexity: O(n²)

Parameters:

`[in]`	str	A string representation of a number.
`[out]`	endptr	When the function returns, this will contain a pointer to the first character after the parsed integer.
`[in]`	base	The base that the string representation of the number is in. This can be any number between 2 and 36 (inclusive). It can also be the constant xint::autobase, in which case the function will follow the standard C/C++ rules for interpreting a numeric constant: any number with a zero as the first digit is assumed to be base-8; any number with a leading zero-x or zero-X (such as 0x1f) is base-16, and anything else is base-10.

Exceptions:

	exceptions::invalid_base	if the base parameter is not between 2 and 36 (inclusive) or the constant xint::autobase.
	exceptions::invalid_digit	if there are no valid digits before the first invalid character.

Remarks:: This function is based on the strtol function from the standard library. Like strtol, it first discards any leading whitespace characters, then takes as many characters as are valid for the given base and interprets them as an integer. Then a pointer to the first character following the integer is stored in the object pointed by endptr.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 310 of file integer.hpp.

template<... >

template<typename charT , typename traitsT , typename allocT >

boost::xint::integer_t<>::integer_t	(	const std::basic_string< charT, traitsT, allocT > &	str,
		std::size_t	base = `10`
	)			`[explicit]`

Create an integer from a string representation.

Complexity: O(n²)

Parameters:

`[in]`	str	A string representation of a number.
`[in]`	base	The base that the string representation of the number is in. This can be any number between 2 and 36 (inclusive). It can also be the constant xint::autobase, in which case the function will follow the standard C/C++ rules for interpreting a numeric constant: any number with a zero as the first digit is assumed to be base-8; any number with a leading zero-x or zero-X (such as 0x1f) is base-16, and anything else is base-10.

Exceptions:

	exceptions::invalid_base	if the base parameter is not between 2 and 36 (inclusive) or the constant xint::autobase.
	exceptions::invalid_digit	if the string contains any digit that cannot be part of a number in the specified base, or if there are no valid digits.

Remarks:: This is the most common way to initialize literal values that are too large to fit into a native integral type.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 361 of file integer.hpp.

template<... >

boost::xint::integer_t<>::integer_t	(	const xint::binary_t	b,
		bitsize_t	bits = `0`
	)			`[explicit]`

Converts a portable binary representation of a number into an integer.

Complexity: O(n)

Parameters:

`[in]`	b	An `xint::binary_t` containing the bytes to convert, lowest byte first.
`[in]`	bits	The number of bits packed into each character (for portability with systems that might not have characters with the same number of bits), or zero (the default) to assume the number of bits in the current system's unsigned character type.

Exceptions:

exceptions::invalid_argument if bits is greater than the number of bits in an unsigned character.

Returns:: An integer representing the bytes.

See also:: xint::to_binary

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 402 of file integer.hpp.

template<... >

template<other >

boost::xint::integer_t<>::integer_t	(	const integer_t< other > &	b,
		bool	force_thread_safety = `false`
	)			`[explicit]`

Constructs a new integer object from an existing integer object.

Converts any existing integer_t object to this type.

Parameters:

`[in]`	b	An existing integer.
`[in]`	force_thread_safety	If the `threadsafe` template parameter is `false`, you can use this to make a thread-safe copy anyway. See this page for a full treatment of the matter.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 429 of file integer.hpp.

template<... >

template<typename Type >

boost::xint::integer_t<>::integer_t	(	const Type	n,
		typename boost::enable_if< boost::is_integral< Type > >::type *	= `0`
	)

Constructs a new integer object with the value of the built-in integer type passed to it.

Parameters:

[in] n The value for the new object.

Template Parameters:

Type The type of n.

You can ignore the enable_if parameter, it's there only to tell the compiler what types the function applies to.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 469 of file integer.hpp.

Member Function Documentation

template<... >

integer_t<...> boost::xint::integer_t<>::factorial ( std::size_t n ) [static]

Calculate the value of n!

Complexity: O(n³)

Parameters:

[in] n The value to operate on.

Returns:: n factorial, defined as 1*2*3*...*n

Warning:: Factorials get ridiculously huge, even with fairly small values of n. This function, when used on an unlimited-size integer and with a large parameter, is the easiest way to exhaust the system's memory.

Definition at line 1074 of file integer.hpp.

template<... >

size_t boost::xint::integer_t<>::hex_digits ( ) const

Tells you roughly how large *this is.

Complexity: O(1)

Returns:: The number of hexadecimal digits that would be required to encode this. The nothrow version returns zero instead of throwing.

Definition at line 1012 of file integer.hpp.

template<... >

bool boost::xint::integer_t<>::is_even ( ) const

Tests the lowest bit of *this to determine evenness.

Complexity: O(1)

Returns:: true if *this is even, otherwise false. The nothrow version returns false instead of throwing.

Definition at line 954 of file integer.hpp.

template<... >

bool boost::xint::integer_t<>::is_nan ( ) const

Tests whether the object is a Not-a-Number.

Complexity: O(1)

Returns:: true if *this is a Not-a-Number value, otherwise false.

See also:: The Not-a-Number Value

Note:: This will always return false on any type where the nothrow template parameter is false.

template<... >

bool boost::xint::integer_t<>::is_odd ( ) const

Tests the lowest bit of *this to determine oddness.

Complexity: O(1)

Returns:: true if *this is odd, otherwise false. The nothrow version returns false instead of throwing.

Definition at line 937 of file integer.hpp.

template<... >

integer_t<...> boost::xint::integer_t<>::nan ( ) [static]

Returns a Not-a-Number value, for types that support it.

Complexity: O(1)

Returns:: A Not-a-Number value of the specified type.

Note:: This function only exists on types with the nothrow template parameter.

See also:: The Not-a-Number Value

template<... >

boost::xint::integer_t<>::operator safe_bool_type ( ) const [inline]

Definition at line 96 of file integer.hpp.

template<... >

bool boost::xint::integer_t<>::operator! ( ) const [inline]

Definition at line 98 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator%= ( const integer_t<...> b )

See also:: operator%(integer_t, integer_t)

Definition at line 651 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator&= ( const integer_t<...> n )

See also:: operator&(integer_t, integer_t)

Definition at line 771 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator*= ( const integer_t<...> b )

See also:: operator*(integer_t, integer_t)

Definition at line 607 of file integer.hpp.

template<... >

const integer_t<...>& boost::xint::integer_t<>::operator+ ( ) const [inline]

Definition at line 101 of file integer.hpp.

template<... >

integer_t<...>& boost::xint::integer_t<>::operator+ ( ) [inline]

Definition at line 100 of file integer.hpp.

template<... >

integer_t<...> boost::xint::integer_t<>::operator++ ( int )

Postincrement operator

Complexity: O(n)

This is not recommended. It must make a copy before incrementing the *this object, making it noticeably less efficient than the preincrement operator.

Definition at line 725 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator++ ( )

Preincrement operator

Complexity: amortized O(1)

Definition at line 676 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator+= ( const integer_t<...> b )

See also:: operator+(integer_t, integer_t)

Definition at line 561 of file integer.hpp.

template<... >

integer_t<...> boost::xint::integer_t<>::operator- ( ) const

Return the additive inverse of an integer.

Complexity: O(1)

Returns:: *this with the sign reversed.

Definition at line 538 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator-- ( )

Predecrement operator

Complexity: amortized O(1)

Definition at line 698 of file integer.hpp.

template<... >

integer_t<...> boost::xint::integer_t<>::operator-- ( int )

Postdecrement operator

Complexity: O(n)

This is not recommended. It must make a copy before decrementing the *this object, making it noticeably less efficient than the predecrement operator.

Definition at line 750 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator-= ( const integer_t<...> b )

See also:: operator-(integer_t, integer_t)

Definition at line 583 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator/= ( const integer_t<...> b )

See also:: operator/(integer_t, integer_t)

Definition at line 629 of file integer.hpp.

template<... >

integer_t<...> boost::xint::integer_t<>::operator<< ( bitsize_t shift ) const

Left-shift an integer by a specified number of bits.

Complexity: O(n)

Parameters:

[in] shift The number of bits to left-shift the number.

Returns:: The bit-shifted integer.

Definition at line 845 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator<<= ( bitsize_t shift )

See also:: operator<<(integer_t, integer_t)

Definition at line 892 of file integer.hpp.

template<... >

integer_t<...>& boost::xint::integer_t<>::operator= ( BOOST_XINT_RV_REF(type) c ) [inline]

Definition at line 91 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator= ( BOOST_XINT_COPY_ASSIGN_REF(type) c )

Definition at line 491 of file integer.hpp.

template<... >

template<typename Type >

integer_t<...>& boost::xint::integer_t<>::operator= ( const Type n ) [inline]

Definition at line 93 of file integer.hpp.

template<... >

integer_t<...> boost::xint::integer_t<>::operator>> ( bitsize_t shift ) const

Right-shift an integer by a specified number of bits.

Complexity: O(n)

Parameters:

[in] shift The number of bits to right-shift the number.

Returns:: The bit-shifted integer.

Definition at line 872 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator>>= ( bitsize_t shift )

See also:: operator>>(integer_t, integer_t)

Definition at line 912 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator^= ( const integer_t<...> n )

See also:: operator^(integer_t, integer_t)

Definition at line 815 of file integer.hpp.

template<... >

integer_t<...> & boost::xint::integer_t<>::operator|= ( const integer_t<...> n )

See also:: operator|(integer_t, integer_t)

Definition at line 793 of file integer.hpp.

template<... >

integer_t<...> boost::xint::integer_t<>::operator~ ( ) const

The Bitwise Ones Complement (i.e. bitwise NOT) operator.

Complexity: O(n)

Note:: This operator is only available with fixed-size integers. The result from a proper implementation for variable-sized integers would be an infinitely long number.

: Also note that, although this changes the bit-pattern the same way as with the built-in types, the value will not be the same for signed numbers, because this library does not store negative numbers in twos complement format. In other words, if n is a built-in signed type and m is a signed integer_t with the same value, then ~n != ~m.

template<... >

integer_t<...> boost::xint::integer_t<>::pow2 ( std::size_t exponent ) [static]

Calculate the value of 2^e

Complexity: O(1)

Parameters:

[in] exponent The exponent to operate on.

Returns:: 2 to the power of exponent.

Remarks:: This is a convenience function, to help with self-documenting code. It is also more efficient than using bit-shifting or the pow function to get the same result.

Definition at line 1039 of file integer.hpp.

template<... >

template<class Type >

integer_t<...> boost::xint::integer_t<>::random_by_size	(	Type &	gen,
		bitsize_t	size_in_bits,
		bool	high_bit_on = `false`,
		bool	low_bit_on = `false`,
		bool	can_be_negative = `false`
	)			`[static]`

Generates a random integer with specific attributes.

Complexity: O(n)

Parameters:

`[in]`	gen	The random number generator to use. This can be boost::xint::default_random_generator, boost::xint::strong_random_generator, or any other class that supplies the member functions required by the Boost.Random random number generators.
`[in]`	size_in_bits	The maximum number of bits that you want the returned number to have.
`[in]`	high_bit_on	If `true`, the returned number will have exactly the requested size. If `false`, the upper bits may be zero, resulting in a number that is slightly smaller than requested.
`[in]`	low_bit_on	If `true`, the returned number will always be odd. If `false`, it has an equal chance of being odd or even.
`[in]`	can_be_negative	If `true`, the returned value has an equal chance of being positive or negative. If `false`, it will always be positive. Note that on unsigned types, this parameter is ignored; the result will always be positive regardless of it.

Returns:: A random integer with the requested attributes.

See also:: The XInt Random Number System

Definition at line 1134 of file integer.hpp.

template<... >

template<class Type >

integer_t<...> boost::xint::integer_t<>::random_prime	(	Type &	gen,
		bitsize_t	size_in_bits,
		callback_t	callback = `no_callback`
	)			`[static]`

Generate a randomly-generated prime number of a particular bit-size.

Complexity: Varies

Parameters:

`[in]`	gen	The random number generator to use. This can be boost::xint::default_random_generator, boost::xint::strong_random_generator, or any other class that supplies the member functions required by the Boost.Random random number generators.
`[in]`	size_in_bits	The number of bits that you want the returned value to have.
`[in]`	callback	An optional function that will be called regularly during the operation. If it returns `false`, the function will immediately return.

Returns:: A randomly-generated prime integer with the specified number of bits, or zero if the provided callback function cancelled the operation.

Exceptions:

exceptions::invalid_argument if size_in_bits is less than two.

Note:: This function uses xint::is_prime. See the description of it for details of its limitations.

: See the Random Number Functions page for details on how to get cryptographically-secure random numbers.

See also:: Generating Prime Numbers

Definition at line 1181 of file integer.hpp.

template<... >

int boost::xint::integer_t<>::sign ( bool signed_zero = false ) const

Tests the sign of *this.

Complexity: O(1)

Parameters:

[in] signed_zero If false (the default value), returns zero if *this is zero. If true, returns 1 or -1 on a zero *this as well. Primarily used to identify a negative zero.

Returns:: -1 if *this is negative, 0 if it's zero, or 1 if it's greater than zero. The nothrow version returns zero instead of throwing.

Definition at line 991 of file integer.hpp.

The documentation for this class was generated from the following file:

integer.hpp

boost::xint::integer_t<> Class Template Reference

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

template<...> class boost::xint::integer_t<>

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<...>
class boost::xint::integer_t<>