Description

Math utility classes and functions.

Math Classes

The three array-like classes in fcppt.math are:

Vector and dim are one-dimensional statically sized arrays, while matrix is a two-dimensional statically sized array. Although vector and dim are very similar, they do not provide the same operations. Vectors should be used for points or arrows, while dims should be used for sizes. The three classes follow a common base design which will be explained using vectors.

There are two classes that build on top of vector and dim:

fcppt.math.box and
fcppt.math.sphere.

Declarations

Vector, dim and matrix are statically sized arrays. The declaration of vector uses the template parameters typename T, fcppt::math::size_type N and typename S. Here, T is the element type, N the number of elements and S the storage type. The latter requires further explanation: For a normal vector that owns its elements, S can be std::array<T,N>.

typedef
fcppt::math::vector::object<
        float,
        2,
        std::array<
                float,
                2
        >
>
vector2f;

This is exactly what fcppt::math::vector::static_ does.

typedef
fcppt::math::vector::static_<
        float,
        2
>
vector2f;

If we want a view vector, for example a vector that represents a row of a matrix, we could use S=T* instead.

Initialization

Vector and dim are initialized in the same way: An fcppt::math::vector::object<T,N,S> can be initialized by either:

fcppt::no_init,
N values of type T,
or a value of type S.

        // v1 is not initialized
        vector2f v1(
                fcppt::no_init{}
        );
        v1.x() = 0.1f;
        v1.y() = 0.2f;
        // same as v1
        vector2f const v2(
                0.1f,
                0.2f
        );

Conversions

vector, dim and matrix each have a structure_cast function. Structure casts preserve dimensions but convert the underlying value type. How this is done is specified by a function object.

        fcppt::math::vector::static_<
                int,
                1
        > const i(
                10
        );
        auto const f(
                fcppt::math::vector::structure_cast<
                        fcppt::math::vector::static_<
                                float,
                                1
                        >,
                        fcppt::cast::int_to_float_fun
                >(
                        i
                )
        );

vector and dim have functions push_back, which increases the dimension by one, and narrow_cast, which decreases the dimension.

        fcppt::math::vector::static_<
                int,
                1
        > const small(
                10
        );
        // Convert smaller to bigger. Only works for N and N+1 and we have to
        // specify the additional element.
        fcppt::math::vector::static_<
                int,
                2
        > const bigger(
                fcppt::math::vector::push_back(
                        small,
                        20
                )
        );
        // Convert bigger to smaller
        auto const small_again(
                fcppt::math::vector::narrow_cast<
                        fcppt::math::vector::static_<
                                int,
                                1
                        >
                >(
                        bigger
                )
        );

Comparison

All math classes can be compared using operator==, for example:

        vector2f const x(1.f,2.f);
        vector2f const y(1.f,2.f);
        std::cout << (x == y) << ',' << (x - y == vector2f{0.f,0.f}) << '\n';

operator== uses the underlying comparison operator of the value type, which is error-prone for floats. The componentwise_equal compare using an epsilon:

        vector2f const x(1.f,2.f);
        vector2f const y(1.f,2.f);
        float const epsilon(0.001f);
        std::cout << fcppt::math::vector::componentwise_equal(x,y,epsilon) << '\n';

For vector, dim and matrix, the following comparison operators are defined:

operator==
operator!=
operator<=
operator<
operator>=
operator>

Arithmetic

vector, dim and matrix define different arithmetic operators. See their individual documentations for more information.

It is important to note that all of the free operators support that the value types of their arguments differ. Suppose we can divide meters by seconds to get speed.

// Just for exposition only
struct meter
{
};
struct second
{
};
struct speed
{
};

speed
operator/(
        meter,
        second
)
{
        return
                speed{};
}

This can now be used to divide vectors of meters by vectors of seconds to obtain vectors of speeds.

        typedef
        fcppt::math::vector::static_<
                meter,
                2
        >
        meter2;
        typedef
        fcppt::math::vector::static_<
                second,
                2
        >
        second2;
        typedef
        fcppt::math::vector::static_<
                speed,
                2
        >
        speed2;
        fcppt::optional::object<
                speed2
        > const s{
                meter2(
                        meter{},
                        meter{}
                )
                /
                second2(
                        second{},
                        second{}
                )
        };

Null

vector, dim and box provide null functions that return an object consisting of zeroes.

        auto const n(
                fcppt::math::vector::null<
                        vector2f
                >()
        );

Input and output

All classes provide an output operator operator<< , some also provide an input operator operator>> .

Modules
	fcppt.math.box
	A class representing axis-aligned rectangles, boxes, hypercubes, ...

	fcppt.math.dim
	A class representing static n-dimensional dimensions.

	fcppt.math.matrix
	A class representing static n times m-dimensional matrices.

	fcppt.math.sphere
	A class representing circles, spheres, ...

	fcppt.math.vector
	A class representing static n-dimensional vectors.

Typedefs
typedef std::make_signed_t< fcppt::math::size_type >	fcppt::math::difference_type
	The difference type used for structure sizes. More...

template<fcppt::math::size_type Start, fcppt::math::size_type End>
using	fcppt::math::int_range = ::brigand::range< fcppt::math::size_type, Start, End >
	A static int range. More...

template<fcppt::math::size_type Count>
using	fcppt::math::int_range_count = fcppt::math::int_range< fcppt::literal< fcppt::math::size_type >(0u), Count >
	A static int range starting at 0. More...

typedef unsigned	fcppt::math::size_type
	The size type used for structure sizes. More...

template<fcppt::math::size_type N>
using	fcppt::math::static_size = std::integral_constant< fcppt::math::size_type, N >
	An mpl integral_c for math::size_type. More...

template<typename Type >
using	fcppt::math::to_array_type = std::array< typename Type::value_type, fcppt::math::detail::storage_size< typename Type::storage_type >::value >
	Returns the array type of an object with static storage. More...

Functions
template<typename T >
fcppt::optional::object< T >	fcppt::math::ceil_div (T const &_dividend, T const &_divisor)
	Calculates dividend / divisor rounded towards infinity. More...

template<typename T >
fcppt::optional::object< T >	fcppt::math::ceil_div_signed (T const &_dividend, T const &_divisor)
	Calculates dividend / divisor rounded towards infinity. More...

template<typename T >
T	fcppt::math::clamp (T const &_value, T const &_vmin, T const &_vmax)
	Clamps a value into a range. More...

template<typename T >
T	fcppt::math::deg_to_rad (T const deg)
	Transforms degrees into radians. More...

template<typename T >
T	fcppt::math::diff (T const &_a, T const &_b)
	Calculates the absolute distance between `a` and `b`. More...

template<typename L , typename R >
fcppt::optional::object<>	fcppt::math::div (L const &_dividend, R const &_divisor)
	Calculates dividend / divisor. More...

template<typename Type >
Type	fcppt::math::from_array (fcppt::math::to_array_type< Type > &&_value)
	Constructs an object with static storage from an array rvalue. More...

template<typename Type >
Type	fcppt::math::from_array (fcppt::math::to_array_type< Type > const &_value)
	Constructs an object with static storage from an array lvalue. More...

template<typename Float , typename Value >
Value	fcppt::math::interpolation::linear (Float const &_f, Value const &_v1, Value const &_v2)
	Interpolates between two values linearly. More...

template<typename Float , typename Value >
Value	fcppt::math::interpolation::perlin_fifth_degree (Float const &_f, Value const &_v1, Value const &_v2)
	Interpolates between two values using perlin fifth degree. More...

template<typename Float , typename Value >
Value	fcppt::math::interpolation::trigonometric (Float const &_f, Value const &_v1, Value const &_v2)
	Interpolates between two values trigonometrically. More...

template<typename Type >
Type	fcppt::math::interval_distance (fcppt::homogenous_pair< Type > _i1, fcppt::homogenous_pair< Type > _i2)
	Calculates the distance of two intervals. More...

template<typename T >
constexpr bool	fcppt::math::is_power_of_2 (T const x) noexcept
	Checks if a number is a power of two. More...

template<typename T >
bool	fcppt::math::is_zero (T const &_value)
	Compares a value against zero. More...

template<typename T >
T	fcppt::math::log2 (T const x)
	Calculates $\log_2(x)$ for unsigned types (using a loop) More...

template<typename T >
fcppt::optional::object< T >	fcppt::math::mod (T const &_dividend, T const &_divisor)
	Wraps the integral modulo operator and the floating point modulo functions. More...

template<typename T >
T	fcppt::math::next_power_of_2 (T const _value)
	Calculates the next power of 2 for an unsigned value. More...

template<typename T >
T	fcppt::math::pi ()
	Returns Pi for type T. More...

template<typename Result , typename Exponent >
constexpr Result	fcppt::math::power_of_2 (Exponent const _exponent)
	Calculates two to the power of n. More...

template<typename T >
T	fcppt::math::rad_to_deg (T const rad)
	Transforms radians into degrees. More...

template<typename Type >
fcppt::math::to_array_type< Type >	fcppt::math::to_array (Type const &_value)
	Returns the array of an object with static storage. More...

template<typename T >
T	fcppt::math::twopi ()
	Returns two Pi for type T. More...

Typedef Documentation

◆ difference_type

typedef std::make_signed_t< fcppt::math::size_type> fcppt::math::difference_type

The difference type used for structure sizes.

◆ int_range

template<fcppt::math::size_type Start, fcppt::math::size_type End>

using fcppt::math::int_range = typedef ::brigand::range< fcppt::math::size_type, Start, End >

A static int range.

◆ int_range_count

template<fcppt::math::size_type Count>

using fcppt::math::int_range_count = typedef fcppt::math::int_range< fcppt::literal< fcppt::math::size_type >( 0u ), Count >

A static int range starting at 0.

◆ size_type

typedef unsigned fcppt::math::size_type

The size type used for structure sizes.

◆ static_size

template<fcppt::math::size_type N>

using fcppt::math::static_size = typedef std::integral_constant< fcppt::math::size_type, N >

An mpl integral_c for math::size_type.

◆ to_array_type

template<typename Type >

using fcppt::math::to_array_type = typedef std::array< typename Type::value_type, fcppt::math::detail::storage_size< typename Type::storage_type >::value >

Returns the array type of an object with static storage.

Function Documentation

◆ ceil_div()

template<typename T >

fcppt::optional::object< T> fcppt::math::ceil_div	(	T const &	_dividend,
		T const &	_divisor
	)

Calculates dividend / divisor rounded towards infinity.

In case divisor is 0, nothing is returned. Otherwise, returns (dividend / divisor) if dividend can be divided by divisor, and (dividend / divisor) + 1 if dividend can not be divided by divisor.

Template Parameters

T	An unsigned type.

◆ ceil_div_signed()

template<typename T >

fcppt::optional::object< T> fcppt::math::ceil_div_signed	(	T const &	_dividend,
		T const &	_divisor
	)

Calculates dividend / divisor rounded towards infinity.

The same as fcppt::math::ceil_div, except in case where dividend is negative, dividend / divisor is returned.

Template Parameters

T	A signed type

◆ clamp()

template<typename T >

T fcppt::math::clamp	(	T const &	_value,
		T const &	_vmin,
		T const &	_vmax
	)

Clamps a value into a range.

Precondition: _vmin <= _vmax

◆ deg_to_rad()

template<typename T >

T fcppt::math::deg_to_rad ( T const deg )

inline

Transforms degrees into radians.

Template Parameters

T	A floating point type

◆ diff()

template<typename T >

T fcppt::math::diff	(	T const &	_a,
		T const &	_b
	)

inline

Calculates the absolute distance between a and b.

Template Parameters

T	A numeric type

For unsigned types, this returns:

$\min(a - b, b - a)$

For other types, abs(a-b) is returned.

◆ div()

template<typename L , typename R >

fcppt::optional::object<> fcppt::math::div	(	L const &	_dividend,
		R const &	_divisor
	)

Calculates dividend / divisor.

In case divisor is 0, nothing is returned.

Template Parameters

R	Any type that works with fcppt::math::is_zero.

◆ from_array() [1/2]

template<typename Type >

Type fcppt::math::from_array ( fcppt::math::to_array_type< Type > && _value )

inline

Constructs an object with static storage from an array rvalue.

◆ from_array() [2/2]

template<typename Type >

Type fcppt::math::from_array ( fcppt::math::to_array_type< Type > const & _value )

inline

Constructs an object with static storage from an array lvalue.

◆ interval_distance()

template<typename Type >

Type fcppt::math::interval_distance	(	fcppt::homogenous_pair< Type >	_i1,
		fcppt::homogenous_pair< Type >	_i2
	)

Calculates the distance of two intervals.

Returns the distance (as defined below) of the intervals _i1 and _i2.

Distance can be zero if the intervals touch, or negative if they overlap. If they only partially overlap, the distance is negative the common length where they overlap. If one completely contains the other, the "outer" interval is split in two parts by the "inner" one. In this case, the (again negative) length of the shorter part is returned. Therefore the distance is zero if the inner interval touches the outer one.

Template Parameters

Type	Must support `<` and `-`

◆ is_power_of_2()

template<typename T >

constexpr bool fcppt::math::is_power_of_2 ( T const x )

inlinenoexcept

Checks if a number is a power of two.

Template Parameters

T	Must be an unsigned integral type

If you need to check whether a signed integral type is a power of two, convert it to its unsigned counterpart before checking.

◆ is_zero()

template<typename T >

bool fcppt::math::is_zero ( T const & _value )

inline

Compares a value against zero.

Uses fcppt::literal to create a zero constant and uses operator== for comparison.

This function is special because it also allows comparison of floating-point values against zero, which would otherwise trigger a warning.

◆ linear()

template<typename Float , typename Value >

Value fcppt::math::interpolation::linear	(	Float const &	_f,
		Value const &	_v1,
		Value const &	_v2
	)

Interpolates between two values linearly.

Template Parameters

Float	Must be a floating point type
Value	Must support scalar multiplication with Float and addition

◆ log2()

template<typename T >

T fcppt::math::log2 ( T const x )

inline

Calculates $\log_2(x)$ for unsigned types (using a loop)

Template Parameters

T	Must be an unsigned integral type

Warning: Behaviour is undefined if x is 0.

◆ mod()

template<typename T >

fcppt::optional::object< T> fcppt::math::mod	(	T const &	_dividend,
		T const &	_divisor
	)

inline

Wraps the integral modulo operator and the floating point modulo functions.

It uses std::fmod for floating point types. Otherwise % is used. Returns nothing if _divisor is zero.

Template Parameters

T	A floating-point type or an unsigned type.

◆ next_power_of_2()

template<typename T >

T fcppt::math::next_power_of_2 ( T const _value )

Calculates the next power of 2 for an unsigned value.

Template Parameters

T	An unsigned type

◆ perlin_fifth_degree()

template<typename Float , typename Value >

Value fcppt::math::interpolation::perlin_fifth_degree	(	Float const &	_f,
		Value const &	_v1,
		Value const &	_v2
	)

Interpolates between two values using perlin fifth degree.

Template Parameters

Float	Must be a floating point type
Value	Must support scalar multiplication with Float and addition

◆ pi()

template<typename T >

T fcppt::math::pi ( )

inline

Returns Pi for type T.

Template Parameters

T	Must be a floating point type

◆ power_of_2()

template<typename Result , typename Exponent >

constexpr Result fcppt::math::power_of_2 ( Exponent const _exponent )

inline

Calculates two to the power of n.

Returns 2 ^ _exponent.

Template Parameters

Exponent	Must be an unsigned type.
Result	Must be a type constructible with fcppt::literal.

◆ rad_to_deg()

template<typename T >

T fcppt::math::rad_to_deg ( T const rad )

inline

Transforms radians into degrees.

Template Parameters

T	A floating point type

◆ to_array()

template<typename Type >

fcppt::math::to_array_type< Type> fcppt::math::to_array ( Type const & _value )

inline

Returns the array of an object with static storage.

◆ trigonometric()

template<typename Float , typename Value >

Value fcppt::math::interpolation::trigonometric	(	Float const &	_f,
		Value const &	_v1,
		Value const &	_v2
	)

Interpolates between two values trigonometrically.

Template Parameters

Float	Must be a floating point type
Value	Must support scalar multiplication with Float and addition

◆ twopi()

template<typename T >

T fcppt::math::twopi ( )

inline

Returns two Pi for type T.

Template Parameters

T	Must be a floating point type

	3.0.0
Freundlich's C++ toolkit

Description

Math Classes

Declarations

Initialization

Conversions

Comparison

Arithmetic

Null

Input and output

Modules

Typedefs

Functions

Typedef Documentation

◆ difference_type

◆ int_range

◆ int_range_count

◆ size_type

◆ static_size

◆ to_array_type

Function Documentation

◆ ceil_div()

◆ ceil_div_signed()

◆ clamp()

◆ deg_to_rad()

◆ diff()

◆ div()

◆ from_array() [1/2]

◆ from_array() [2/2]

◆ interval_distance()

◆ is_power_of_2()

◆ is_zero()

◆ linear()

◆ log2()

◆ mod()

◆ next_power_of_2()

◆ perlin_fifth_degree()

◆ pi()

◆ power_of_2()

◆ rad_to_deg()

◆ to_array()

◆ trigonometric()

◆ twopi()