fcppt.math.dim

Description

A class representing dynamic or static n-dimensional dimensions.

Motivation Converting from and to vectors Operators Header files

Motivation

When writing code that deals with geometry, you need a type to denote the size (or extent) of the geometry for each dimension. You also need such a class when writing multi-dimensional containers (like fcppt::container::grid::object).

Conceptually, you could just use fcppt::math::vector::object, and we (the authors of fcppt) have thought about going that way. However, a vector just isn't a dimension type. You have operations you can apply to a vector (like the dot product) that make no sense in the context of a dimension. Conversely, you have operations like "take the area of the dimension" that make no sense for vectors. Also, the lower-dimensional getters for vector (meaning x(),y(),z(),w()) are not mixed with the lower-dimensional getters for dim (meaning w(),h(),d()).

So don't be confused, vector and dim are distinct types, not (strong) typedefs of another. They have a very similar interface (and the same template parameters), but not the same member and free functions.

Converting from and to vectors

To convert a dimension to a vector, use fcppt::math::dim::structure_cast:

typedef
fcppt::math::dim::static_<int,3>::type
dim3;

typedef
fcppt::math::vector::static_<int,3>::type
vector3;

dim3 d(1,2,3);

vector3 v = fcppt::math::dim::structure_cast<vector3>(d);

Conversely, use fcppt::math::vector::structure_cast to convert a vector to a dim:

typedef
fcppt::math::dim::static_<int,3>::type
dim3;

typedef
fcppt::math::vector::static_<int,3>::type
vector3;

vector3 d(1,2,3);

dim3 v = fcppt::math::vector::structure_cast<dim3>(d);

If you include the fcppt/math/vector/dim.hpp header, you get the operators +-*%/ which all have the signature

vector::object<T,N,S> operator(vector::object<T,N,S> left,dim::object<T,N,S>)

This way, you can add a dimension to a vector, for example.

Operators

Including fcppt/math/dim/object_decl.hpp you will get the following operators (S2 defines some other storage type):

• operator+=(dim::object<T,N,S2>)
• operator-=(dim::object<T,N,S2>)
• operator*=(dim::object<T,N,S2>)
• operator/=(dim::object<T,N,S2>)
• operator%=(dim::object<T,N,S2>)
• operator*=(T) (multiply by a scalar)
• operator/=(T) (divide by a scalar)
• operator=(dim::object const &) (regular assignment operator)
• operator=(dim::object<T,N,S2> const &)
• operator[](size_type>)

The arithmetic operators all work component-wise.

Including fcppt/math/dim/comparison.hpp you get all the comparison operators:

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

All of these work component-wise and forward to the value_type's operators. The ordering is lexicographic. This means that you can use a dim with associative containers like std::set,std::map,.... Keep in mind that the equality comparison operators do not use an epsilon so you will get exact floating point comparisons (be sure that you really want that!).

Including fcppt/math/dim/arithmetic.hpp gives you the following operators:

• operator+(dim::object<T,N,S>,dim::object<T,N,S>)
• operator-(dim::object<T,N,S>,dim::object<T,N,S>)
• operator*(dim::object<T,N,S>,dim::object<T,N,S>)
• operator/(dim::object<T,N,S>,dim::object<T,N,S>)
• operator%(dim::object<T,N,S>,dim::object<T,N,S>)
• operator*(T,dim::object<T,N,S>) (scalar multiplication)
• operator/(T,dim::object<T,N,S>) (scalar division)
• Unary minus for dims

The arithmetic operators all work component-wise.

Including fcppt/math/dim/input.hpp gives you an operator>> for reading input from standard streams. Conversely, including fcppt/math/dim/output.hpp gives you an inverse operator<<.

Header files

fcppt::math::dim is spread out across various header files. There's one header per free function. fcppt::math::dim::object itself is split into various headers, too. Here's an exhaustive list:

Header file	Description
object_fwd.hpp	Contains object's declaration. Include this if you pass a dim by reference, for example.
object_decl.hpp	Contains object's definition.
object_impl.hpp	Contains the definition of object's member functions.
object.hpp	Includes object_fwd.hpp, object_decl.hpp and object_impl.hpp
arithmetic.hpp	Contains object's arithmetic operators.
comparison.hpp	Contains object's comparison operators.
input.hpp	Contains an operator>> for the standard input streams (wide and narrow) which expects dims to be input in the format: (v1,v2,v3,...)
output.hpp	Contains an operator<< for the standard input streams (wide and narrow) which outputs dims in the format: (v1,v2,v3,...)

Classes
struct	fcppt::math::dim::dynamic< T >
	Typedef helper for dynamic dimensionsSee the introduction to fcppt::math::vector::object for more information on dynamic vectors (and dimensions) and this class. More...
class	fcppt::math::dim::object< T, N, S >
	A class representing dynamic or static n-dimensional dimensions. More...
struct	fcppt::math::dim::static_< T, N >
	Typedef helper for static dimsSee the introduction to fcppt::math::vector::object for more information on static dims (and on this class). More...

Macros
#define	FCPPT_MATH_DIM_MAX_CTOR_PARAMS   4
	The maximum count of constructor parameters for a dim.

Functions
template<typename T , typename N , typename S >
boost::enable_if < math::is_static_size< N > , typename static_< T, N::value+1 >::type >::type const	fcppt::math::dim::construct (object< T, N, S > const &base, T const &t)
	Constructs a dim with dimension N+1 from a dim with dimension N.
template<math::size_type N, typename T >
fcppt::math::dim::static_< T, N >::type	fcppt::math::dim::fill (T const &_value)
	Constructs a static dim with all components set to a given value.
template<typename T , typename N , typename S , typename Ch , typename Traits >
boost::disable_if < math::is_dynamic_size< N > , std::basic_istream< Ch, Traits > & >::type	fcppt::math::dim::operator>> (std::basic_istream< Ch, Traits > &s, object< T, N, S > &v)
	Reads a dim from s, expecting it in the format.
template<typename T , typename N , typename S >
bool	fcppt::math::dim::is_quadratic (dim::object< T, N, S > const &r)
	Checks if all elements of the dim are the same.
template<typename Dest , typename T , typename N , typename S >
Dest const	fcppt::math::dim::narrow_cast (object< T, N, S > const &src)
	Shortens a dim to a smaller dimension.
template<typename T , typename N , typename S , typename Ch , typename Traits >
std::basic_ostream< Ch, Traits > &	fcppt::math::dim::operator<< (std::basic_ostream< Ch, Traits > &s, object< T, N, S > const &v)
	Outputs a dim to s, in the format.
template<typename Dest , typename T , typename N , typename S >
Dest const	fcppt::math::dim::structure_cast (object< T, N, S > const &_src)
	Converts a dim into a different dim of the same dimension using static_cast

Macro Definition Documentation

#define FCPPT_MATH_DIM_MAX_CTOR_PARAMS   4

The maximum count of constructor parameters for a dim.

Increasing this will increase compile time but will allow for higher-dimensional variadic constructors.

Function Documentation

template<typename T , typename N , typename S >

boost::enable_if< math::is_static_size< N >, typename static_< T, N::value + 1 >::type>::type const fcppt::math::dim::construct	(	object< T, N, S > const &	base,
		T const &	t
	)

Constructs a dim with dimension N+1 from a dim with dimension N.

Template Parameters

N	Must be a static dimension
T	The dim's value_type
S	The dim's storage type

Parameters

base	The "narrow" dim
t	The element to insert to "widen" _base

The inverse operation is fcppt::math::dim::narrow_cast.

See Also

fcppt::math::dim::narrow_cast

Example:

typedef
fcppt::math::dim::static_<int,2>::type
int2;

typedef
fcppt::math::dim::static_<int,3>::type
int3;

int2 narrow_dim(1,2);
int3 wide_dim =
        fcppt::math::dim::construct(
                narrow_dim,
                3);

// Outputs: 1,2,3
std::cout << wide_dim;

template<math::size_type N, typename T >

fcppt::math::dim::static_< T, N>::type fcppt::math::dim::fill

(

T const &

_value

)

Constructs a static dim with all components set to a given value.

Template Parameters

N	Must be a static dimension
T	The dim's value_type

Parameters

_value

The value to fill the dim with

template<typename T , typename N , typename S >

bool fcppt::math::dim::is_quadratic

(

dim::object< T, N, S > const &

r

)

Checks if all elements of the dim are the same.

Template Parameters

N	The dim's dimension
T	The dim's value_type
S	The dim's storage type

Parameters

r	The dimension to check

template<typename Dest , typename T , typename N , typename S >

Dest const fcppt::math::dim::narrow_cast

(

object< T, N, S > const &

src

)

Shortens a dim to a smaller dimension.

Template Parameters

Dest	Must be a dim with a smaller dimension
N	The dim's dimension
T	The dim's value_type
S	The dim's storage type

Parameters

src	The dim to shorten (narrow)

The inverse operation is fcppt::math::dim::construct.

See Also

fcppt::math::dim::construct

Example:

typedef
fcppt::math::dim::static_<int,2>::type
int2;

typedef
fcppt::math::dim::static_<int,3>::type
int3;

int3 wide_dim(1,2,3);
int2 narrow_dim =
        fcppt::math::dim::narrow_cast<int2>(
                wide_dim);

// Outputs: 1,2
std::cout << narrow_dim;

template<typename T , typename N , typename S , typename Ch , typename Traits >

std::basic_ostream<Ch, Traits>& fcppt::math::dim::operator<<	(	std::basic_ostream< Ch, Traits > &	s,
		object< T, N, S > const &	v
	)

Outputs a dim to s, in the format.

(a_1,a_2,...)

where a_i are the dim's components.

template<typename T , typename N , typename S , typename Ch , typename Traits >

boost::disable_if< math::is_dynamic_size< N >, std::basic_istream<Ch, Traits> &>::type fcppt::math::dim::operator>>	(	std::basic_istream< Ch, Traits > &	s,
		object< T, N, S > &	v
	)

Reads a dim from s, expecting it in the format.

(a_1,a_2,...)

where a_i are the components

template<typename Dest , typename T , typename N , typename S >

Dest const fcppt::math::dim::structure_cast

(

object< T, N, S > const &

_src

)

Converts a dim into a different dim of the same dimension using static_cast

Template Parameters

Dest	The destination dim type (not its value type!)
N	The source dim's dimension
T	The source dim's value_type
S	The source dim's storage type

Parameters

_src	The dim to cast

See the introduction to fcppt::math::vector::object for more information on this function (and dim/vector in general).