2.10.0
Freundlich's C++ toolkit
Modules | Typedefs | Functions
fcppt.math

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:

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
float,
2,
float,
2
>
>
vector2f;

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

typedef
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:

// v1 is not initialized
vector2f v1(
);
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.

int,
1
> const i(
10
);
auto const f(
float,
1
>,
>(
i
)
);

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

int,
1
> const small(
10
);
// Convert smaller to bigger. Only works for N and N+1 and we have to
// specify the additional element.
int,
2
> const bigger(
small,
20
)
);
// Convert bigger to smaller
auto const small_again(
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);

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

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
meter,
second
)
{
return
speed{};
}

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

typedef
meter,
2
>
meter2;
typedef
second,
2
>
second2;
typedef
speed,
2
>
speed2;
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(
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_typefcppt::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 >
fcppt::math::clamp (T const &_value, T const &_vmin, T const &_vmax)
 Clamps a value into a range. More...
 
template<typename T >
fcppt::math::deg_to_rad (T const deg)
 Transforms degrees into radians. More...
 
template<typename 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 >
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 >
fcppt::math::next_power_of_2 (T const _value)
 Calculates the next power of 2 for an unsigned value. More...
 
template<typename 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 >
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 >
fcppt::math::twopi ()
 Returns two Pi for type T. More...
 

Typedef Documentation

◆ 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
TAn 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
TA 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
TA 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
TA 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
RAny 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
TypeMust 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
TMust 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
FloatMust be a floating point type
ValueMust 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
TMust 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
TA 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
TAn 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
FloatMust be a floating point type
ValueMust support scalar multiplication with Float and addition

◆ pi()

template<typename T >
T fcppt::math::pi ( )
inline

Returns Pi for type T.

Template Parameters
TMust 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
ExponentMust be an unsigned type.
ResultMust 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
TA 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
FloatMust be a floating point type
ValueMust support scalar multiplication with Float and addition

◆ twopi()

template<typename T >
T fcppt::math::twopi ( )
inline

Returns two Pi for type T.

Template Parameters
TMust be a floating point type