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>.

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

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

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

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.

  using meter2 = fcppt::math::vector::static_<meter, 2>;
 
  using second2 = fcppt::math::vector::static_<second, 2>;
 
  using speed2 = fcppt::math::vector::static_<speed, 2>;
 
  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>> .

Topics
	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
template<typename Type , Type Dividend, Type Divisor>
using	fcppt::math::ceil_div_static
	Calculates a division of integral contants rounded towards infinity.

using	fcppt::math::difference_type = std::make_signed_t<fcppt::math::size_type>
	The difference type used for structure sizes.

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

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.

using	fcppt::math::size_type = unsigned
	The size type used for structure sizes.

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.

template<typename Type >
using	fcppt::math::to_array_type
	Returns the array type of an object with static storage.

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

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

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

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

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

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

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.

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.

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<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<typename Float , typename Value >
Value	fcppt::math::interpolation::trigonometric (Float const &_f, Value const &_v1, Value const &_v2)
	Interpolates between two values trigonometrically.

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

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

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

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

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.

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

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

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

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.

Typedef Documentation

◆ ceil_div_static

template<typename Type , Type Dividend, Type Divisor>

using fcppt::math::ceil_div_static

Initial value:

typename fcppt::math::detail::ceil_div_static<Type, Dividend, Divisor>::type

Calculates a division of integral contants rounded towards infinity.

Calculates Dividend / Divisor rounded towards infinity. For example, 5 / 3 would result in 2. The result type is a std::integral_constant<Type,V>, where V is the calculated value.

Template Parameters

Type	Must be an unsigned integral type
Dividend	The dividend
Divisor	The divisor

◆ difference_type

using fcppt::math::difference_type = std::make_signed_t<fcppt::math::size_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

Initial value:

fcppt::mpl::list::interval<fcppt::math::size_constant<Start>, fcppt::math::size_constant<End>>

A static int range.

◆ int_range_count

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.

◆ size_type

using fcppt::math::size_type = unsigned

The size type used for structure sizes.

◆ static_size

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.

◆ to_array_type

template<typename Type >

using fcppt::math::to_array_type

Initial value:

 fcppt::array::object<
    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 >

fcppt::optional::object< T > fcppt::math::clamp	(	T const &	_value,
		T const &	_vmin,
		T const &	_vmax )

Clamps a value into a range.

◆ 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_DETAIL_BINARY_TYPE(L,/, R)> 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::tuple::object< Type, Type >	_i1,
		fcppt::tuple::object< Type, 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 >
requires (std::is_unsigned_v<T>)

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

constexprnoexcept

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.

If _value is a power of two, then _value is returned. Otherwise, the least power of two that is greater than _value is returned.

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

◆ power_of_2()

template<typename Result , typename Exponent >
requires (std::is_unsigned_v<Exponent>)

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

constexpr

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

Description

Math Classes

Declarations

Initialization

Conversions

Comparison

Arithmetic

Null

Input and output

Topics

Typedefs

Functions

Typedef Documentation

◆ ceil_div_static

◆ 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()

◆ power_of_2()

◆ rad_to_deg()

◆ to_array()

◆ trigonometric()