nerdcruft
/
libcruft-util
1
0
Fork 0
Code Issues Releases Activity

build: add doxygen comments for various headers

This commit is contained in:
Danny Robson 2018-12-26 15:10:21 +11:00
parent d16069b750
commit becd1e24e3
7 changed files with 186 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
adapter.hpp
View File

@ -3,21 +3,25 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
* Copyright 2015 Danny Robson <danny@nerdcruft.net>
* Copyright 2015-2018 Danny Robson <danny@nerdcruft.net>
*/
#ifndef __UTIL_ADAPTER_HPP
#define __UTIL_ADAPTER_HPP
#include <array>
#include <cstddef>
#include <iterator>
namespace cruft::adapter {
namespace container {
// reverse a container for range-based-for
/// Creates a reversed proxy for a referenced container.
///
/// The target container must remain an l-value.
///
/// It is the caller's job to ensure the targeted container remains
/// valid for the duration of the proxy's lifetime.
template <typename T>
struct reverse {
class reverse {
public:
explicit reverse (T &_target):
m_target (_target)
{ ; }
@ -36,114 +40,81 @@ namespace cruft::adapter {
};
//---------------------------------------------------------------------
template <typename Container>
auto
make_reverse (Container &c)
{
return reverse<Container> { c };
};
reverse (Container&) -> reverse<Container>;
// adapt a container's range methods to return indices rather than iterators
///////////////////////////////////////////////////////////////////////
/// Adapter's a container to return indices of the container's data
/// rather than the values themselves.
///
/// The targeted container must be an l-value.
///
/// It is the caller's job to ensure the targeted container remains
/// valid for the duration of the proxy's lifetime.
template <typename T>
struct indices {
class indices {
public:
using typename T::size_type;
explicit indices (T &_target):
m_target (_target)
{ ; }
size_type begin (void) { return 0; }
size_type end (void) { return m_target.size (); }
size_type begin (void)& { return 0; }
size_type end (void)& { return m_target.size (); }
private:
T m_target;
T &m_target;
};
}
namespace iterator {
// adapt an iterator to return the n-th tuple element of the
// underlying iterator::value_type
template <size_t I, typename It>
///////////////////////////////////////////////////////////////////////
/// Adapt's an iterator to return the n-th element of the tuple that
/// corresponds to the underlying iterator::value_type when
/// dereferenced.
template <size_t I, typename IteratorT>
struct scalar : public std::iterator<
typename std::iterator_traits<It>::iterator_category,
typename std::iterator_traits<IteratorT>::iterator_category,
typename std::tuple_element<
I,
typename std::iterator_traits<
It
IteratorT
>::value_type
>::type,
typename std::iterator_traits<It>::difference_type
typename std::iterator_traits<IteratorT>::difference_type
> {
public:
using reference = typename std::iterator_traits<scalar<I,It>>::reference;
using value_type = typename std::iterator_traits<scalar<I,It>>::value_type;
using inner_type = typename std::iterator_traits<IteratorT>::value_type;
explicit scalar (It _inner):
using value_type = decltype (std::get<I> (std::declval<inner_type>));
using reference = value_type&;
explicit scalar (IteratorT _inner):
m_inner (_inner)
{ ; }
const reference operator* (void) const
const reference operator* (void) const&
{ return std::get<I> (*m_inner); }
reference operator* (void)
reference operator* (void)&
{ return std::get<I> (*m_inner); }
bool operator== (scalar<I,It> rhs) { return m_inner == rhs.m_inner; }
bool operator!= (scalar<I,It> rhs) { return m_inner != rhs.m_inner; }
bool operator== (scalar<I,IteratorT> rhs) { return m_inner == rhs.m_inner; }
bool operator!= (scalar<I,IteratorT> rhs) { return m_inner != rhs.m_inner; }
scalar<I,It>& operator++ (void)
scalar<I,IteratorT>& operator++ (void)
{ ++m_inner; return *this; }
private:
It m_inner;
IteratorT m_inner;
};
//template <
// typename It,
// size_t S,
// typename T
//>
//struct explode : public std::enable_if<
// std::is_same<
// typename std::iterator_traits<It>::value_type,
// std::array<T,S>
// >::value,
// typename std::iterator<
// typename std::iterator_traits<It>::iterator_category,
// typename std::tuple_element<
// typename std::iterator_traits<It>::value_type
// >::type,
// typename std::iterator_traits<It>::difference_type
// >::type
//> {
//public:
// explode (It _inner):
// m_inner (_inner),
// m_sequence (0)
// { ; }
// const reference operator* (void) const
// { return (*m_inner)[m_seqence]; }
// reference operator* (void)
// { return (*m_inner)[m_seqence]; }
// bool operator== (explode rhs) { return m_inner == rhs.m_inner && m_sequence == rhs.m_sequence; }
// bool operator!= (explode rhs) { return !(*this == rhs); }
// explode<It>& operator++ (void)
// {
// if (++m_sequence >= S)
// ++m_inner;
// }
//private:
// It m_inner;
// size_t m_sequence;
//};
}
}
#endif

37
annotation.hpp
View File

@ -3,12 +3,30 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
* Copyright 2011 Danny Robson <danny@nerdcruft.net>
* Copyright 2011-2018 Danny Robson <danny@nerdcruft.net>
*/
#ifndef __UTIL_ANNOTATION_HPP
#define __UTIL_ANNOTATION_HPP
#pragma once
#include <type_traits>
///////////////////////////////////////////////////////////////////////////////
/// Forwards the supplied `value` and annotates the result as likely to be the
/// value `typical`.
///
/// Must be an integral type.
template <typename T, typename = std::enable_if_t<std::is_integral_v<T>>>
constexpr inline
T
expect (T val, T typical)
{
return __builtin_expect (val, typical);
}
/// Coerces the argument into a bool and annotates the result as likely to be
/// true.
template <typename T>
constexpr inline
bool
@ -16,19 +34,10 @@ likely (T &&t)
{ return __builtin_expect (!!t, true); }
/// Coerces the argument into a bool and annotates the result as likely to be
/// false.
template <typename T>
constexpr inline
bool
unlikely (T &&t)
{ return __builtin_expect (!!t, false); }
constexpr inline
long
expect (long val, long typical)
{
return __builtin_expect (val, typical);
}
#endif

52
ascii.hpp
View File

@ -6,8 +6,7 @@
* Copyright 2016-2018 Danny Robson <danny@nerdcruft.net>
*/
#ifndef CRUFT_UTIL_ASCII_HPP
#define CRUFT_UTIL_ASCII_HPP
#pragma once
#include "annotation.hpp"
@ -16,6 +15,7 @@
namespace cruft::ascii {
///////////////////////////////////////////////////////////////////////////
/// Returns true if the supplied character is an ASCII digit.
constexpr inline
bool
is_digit (char c) noexcept
@ -23,7 +23,10 @@ namespace cruft::ascii {
return c >= '0' && c <= '9';
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Converts an ASCII character into a corresponding integer.
///
/// Specifically does not convert multiple characters.
constexpr inline
uint8_t
to_integer (char c)
@ -34,7 +37,9 @@ namespace cruft::ascii {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns true if the supplied character is an upper case letter in the
/// "C" locale.
constexpr inline
bool
is_upper (char c) noexcept
@ -43,7 +48,9 @@ namespace cruft::ascii {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns true if the supplied character is a lower case letter in the
/// "C" locale.
constexpr inline
bool
is_lower (char c) noexcept
@ -52,7 +59,9 @@ namespace cruft::ascii {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns true if the supplied character is an alphabetical character in
/// the "C" locale.
constexpr inline
bool
is_alpha (char c) noexcept
@ -61,7 +70,8 @@ namespace cruft::ascii {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns true if the supplied ASCII character is a hexadecimal digit.
constexpr inline
bool
is_hex (const char c) noexcept
@ -76,7 +86,11 @@ namespace cruft::ascii {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Converts a supplied ASCII character from a hexadecimal digit into a
/// corresponding integer.
///
/// Explicitly does not cover any multi-character case.
constexpr inline
uint8_t
from_hex (char c)
@ -89,24 +103,35 @@ namespace cruft::ascii {
///////////////////////////////////////////////////////////////////////////
/// Converts a lower case ASCII character into an upper case character.
///
/// The results are undefined if the character isn't a lowercase
/// alphabetical character in the "C" locale.
constexpr inline
char
to_upper (char c) noexcept
{
CHECK (is_lower (c));
return c - 'a' + 'A';
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Converts an upper case ASCII character into a lower case character.
///
/// The results are undefined if the character isn't an uppercase
/// alphabetical character in the "C" locale.
constexpr inline
char
to_lower (char c) noexcept
{
CHECK (is_upper (c));
return c - 'A' + 'a';
}
///////////////////////////////////////////////////////////////////////////
/// Returns true if the supplied ASCII character is whitespace.
constexpr inline
bool
is_space (char c)
@ -131,7 +156,9 @@ namespace cruft::ascii {
#include "debug.hpp"
#include <vector>
/// convert an ascii string of hex digits into a vector of uint8
/// Converts a string of ASCII hex digits into a vector of u08 values.
///
/// The supplied string must have a length that is a multiple of 2.
std::vector<std::uint8_t>
inline
operator"" _hex2u8 (const char *str, size_t len)
@ -146,6 +173,9 @@ operator"" _hex2u8 (const char *str, size_t len)
///////////////////////////////////////////////////////////////////////////////
/// Converts a string of ASCII hex digits into an array of u08 values.
///
/// The supplied string must have a length that is a multiple of 2.
template <typename CharT, CharT ...StrV>
constexpr auto
operator"" _hex2array (void)
@ -161,5 +191,3 @@ operator"" _hex2array (void)
return res;
}
#endif

27
bitwise.hpp
View File

@ -6,8 +6,7 @@
* Copyright 2011-2018 Danny Robson <danny@nerdcruft.net>
*/
#ifndef CRUFT_UTIL_BITWISE_HPP
#define CRUFT_UTIL_BITWISE_HPP
#pragma once
#include "types/bits.hpp"
#include "debug.hpp"
@ -128,6 +127,22 @@ namespace cruft {
}
/// A convenience wrapper that provides access to a range of bits in an
/// underlying integral value.
///
/// This class is most useful as part of a union where each has differing
/// offsets and sizes that cover the underlying type.
///
/// A conversion operator is supplied for accessing the bit value.
///
/// ValueT must support bit shifting and bitwise operators (primarily
/// bitwise and).
///
/// \tparam ValueT the underlying integral type
/// \tparam OffsetV the index of the first bit of the range (where 0 is
/// most significant)
/// \tparam SizeV the number of bits in the range. Must be strictly
/// positive.
template <
typename ValueT,
size_t OffsetV,
@ -137,8 +152,10 @@ namespace cruft {
public:
static_assert (SizeV > 0);
static_assert (OffsetV + SizeV <= sizeof (ValueT) * 8);
static_assert (sizeof (ValueT) == sizeof (bitfield));
decltype(auto) operator+ () const { return +value; }
decltype(auto)
operator+ () const { return +value; }
operator auto() const
{
@ -157,6 +174,4 @@ namespace cruft {
{
return os << +ValueT(val);
}
};
#endif
}

26
cast.hpp
View File

@ -62,10 +62,13 @@ namespace cruft::cast {
///////////////////////////////////////////////////////////////////////////
// cast to a smaller type of the same signedness and realness and assert
// that both values are still equal.
//
// checks will be compiled out if NDEBUG is defined.
/// Cast to a smaller type of the same signedness and realness and assert
/// that both values are still equal.
///
/// Any runtime checks will be compiled out if NDEBUG is defined.
///
/// Identity casts are allowed so as to simplify the use of this routine
/// in template code.
template <
typename NarrowT,
typename WideT,
@ -94,9 +97,10 @@ namespace cruft::cast {
///////////////////////////////////////////////////////////////////////////
// cast between types checking that equality holds with the result
//
// checks will be compiled out if NDEBUG is defined.
/// Cast between types checking that exact equality holds if the result is
/// casted back to the original type.
///
/// Runtime checks will be compiled out if NDEBUG is defined.
template <typename DstT, typename SrcT>
constexpr DstT
lossless (const SrcT &src)
@ -131,7 +135,7 @@ namespace cruft::cast {
///////////////////////////////////////////////////////////////////////////
/// assert if the value is not a pointer to a subclass of T, else return
/// Assert if the value is not a pointer to a subclass of T, else return
/// the converted value. Note: this is only a debug-time check and is
/// compiled out in optimised builds.
template <
@ -160,8 +164,10 @@ namespace cruft::cast {
///////////////////////////////////////////////////////////////////////////
/// cast a pointer from one type to another, asserting that the required
/// Cast a pointer from one type to another, asserting that the required
/// alignment of the destination type has been satisfied.
///
/// Runtime checks will be compiled out if NDEBUG is defined.
template <
typename DstT,
typename SrcT,
@ -179,7 +185,7 @@ namespace cruft::cast {
///////////////////////////////////////////////////////////////////////////
/// cast from SrcT to DstT and damn any consequences.
/// Cast from SrcT to DstT and damn any consequences; just make it compile.
template <typename DstT, typename SrcT>
DstT ffs (SrcT src)
{

6
cpuid_x86.hpp
View File

@ -6,14 +6,14 @@
* Copyright 2018 Danny Robson <danny@nerdcruft.net>
*/
#ifndef CRUFT_UTIL_CPUID_X86_HPP
#define CRUFT_UTIL_CPUID_X86_HPP
#pragma once
#include "cpuid.hpp"
#include <array>
namespace cruft::cpu {
/// Queries x86 CPU features using the CPUID instruction.
struct x86 {
x86 ();
@ -44,5 +44,3 @@ namespace cruft::cpu {
std::ostream&
operator<< (std::ostream&, const cruft::cpu::x86&);
};
#endif

51
quaternion.hpp
View File

@ -19,32 +19,44 @@
namespace cruft {
// quaternion's are _just_ different enough to other coord types that we
// special case as a distinct POD type and provide many of the same
// functions as distinct declarations.
//
// issues include:
// * strictly 4 dimensions
// * scalar operations sometimes don't make sense on the w component
// * objects must be normalised to make sense
/// Represents a quaternion value.
///
/// Quaternion's are _just_ different enough to other coord types that we
/// special case as a distinct POD type and provide many of the same
/// functions as distinct declarations.
///
/// Considerations include:
/// * strictly 4 dimensions
/// * scalar operations sometimes don't make sense on the w component
/// * objects must be normalised to make sense
template <typename T>
struct quaternion {
T w, x, y, z;
static constexpr std::size_t size (void) { return 4; }
/// Construct a quaternion that represents a rotation of `radians`
/// around the unit-vector `axis`.
static quaternion angle_axis (T radians, vector<3,T> axis);
/// Construct a quaternion that represents a sequence of euler angle
/// rotations in radians. Equivalent to the concatentation of x, y,
/// and then z rotations.
static quaternion from_euler (vector<3,T>);
/// build a quaternion that represents the rotation from a to b
/// Constructs a quaternion that represents the rotation of a unit
/// vector `a` to the unit vector `b`.
static quaternion from_to (vector<3,T> a, vector<3,T> b);
/// build a quaternion that represents the rotation needed to look at
/// a direction with a given up direction
/// Constructs a quaternion that represents the rotation needed to
/// look along the unit vector `fwd` with the unit vector `up`
/// denoting the upward direction.
static quaternion look (vector<3,T> fwd, vector<3,T> up);
/// Converts a rotation quaternion into an equivalent matrix form.
matrix4<T> as_matrix (void) const;
/// Constructs a identity rotation quaternion.
static constexpr
quaternion<T>
identity (void)
@ -62,12 +74,15 @@ namespace cruft {
///////////////////////////////////////////////////////////////////////////
/// Returns the result of rotating the unit vector `dir` using the
/// quaternion `q`.
template <typename T>
vector3<T>
rotate (vector3<T>, quaternion<T>);
rotate (vector3<T> dir, quaternion<T> q);
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns the result of rotating the unit vector `v` by the quaternion `q`.
template <typename T>
vector3<T>
operator* (quaternion<T> const q, vector3<T> const v)
@ -77,6 +92,7 @@ namespace cruft {
///////////////////////////////////////////////////////////////////////////
/// Returns the square of the L2 norm of the quaternion `q`.
template <typename T>
constexpr
T
@ -89,7 +105,8 @@ namespace cruft {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns the L2 norm of the quaternion `q`.
template <typename T>
constexpr
T
@ -99,7 +116,8 @@ namespace cruft {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns true if the quaternion has a unit L2 norm.
template <typename T>
constexpr
bool
@ -109,7 +127,8 @@ namespace cruft {
}
//-------------------------------------------------------------------------
///------------------------------------------------------------------------
/// Returns the normalised form of quaternion `q`.
template <typename T>
constexpr
quaternion<T>