<h1>Cxxomfort Library Supplements</h1>

The <code>cxxomfort</code> library offers some specific utilities of its own, not found in C++03 or C++11.

The header is responsible for adding these features, and automatically included when using  <code>#include as well. All the features thus included are defined in namespace <code>cxxomfort</code>.

Unlike [Extras], these features are considered intrinsic to the cxxomfort library: other features are allowed to depend on them, and they do not need to be explicitly included to work.

<b>General index of library utilities</b>:

  *  [#cxxo-sup-algorithm|Supplementals for <algorithm>]
  *  [#cxxo-sup-functional|Supplementals for <functional>]
  *  [#cxxo-sup-iterator|Supplementals for <iterator>]
  *  [#cxxo-sup-numeric|Supplementals for <numeric>]
  *  [#cxxo-sup-random|Supplementals for <random>]
  *  [#cxxo-sup-string|Supplementals for <string>]
  *  [#cxxo-sup-tuple|Supplementals for <tuple>]
  *  [#cxxo-sup-type_traits|Supplementals for <type_traits>]
  *  Array References
  *  [#foreach|Foreach Loop Emulation]
  *  <code>[#fixed_vector]</code>
  *  Initialization of sequences
  *  Local Function Emulation
  *  Sequence-related Utilities
  *  [#type_name|Type Identification utilities]
  *  [#typesafeenum|Typesafe Enums]
  *  <del>Upgraded
  *  <del>Upgraded


<a id="arrayref"></a>
<h2>Array References</h2>
<verbatim>
#include
</verbatim>

The cxxomfort library implements n3334's <tt>array_ref<T></tt> as a Supplement: a reference or view-type for a contiguous sequence of elements. Documentation].

<a id="foreach"></a>
<h2>Foreach Loop</h2>
<verbatim>
#include
</verbatim>

<b>[Features/Foreach|"foreach" Loop emulation]</b>: allows writing C++11-like foreach loops in C++03 via a reworked implementation of the Artima <em>Foreach</em> utility, which also generates native foreach loops in C++11 onwards, thus resulting in zero overhead.

<verbatim>
SomeSequence<string> mystrings;
fill mystrings somehow
CXXO_FOREACH /string const& s, mystrings) {
    do stuff with 's'
}
</verbatim>

<a id="fixed_vector"></a>
<h2>Fixed_vector</h2>
<verbatim>
#include
</verbatim>

- the oft sought for holy grail of a <code>std::vector</code> whose size is fixed at construction as an invariant. Documentation].

<verbatim>
fixed_vector<short> fixed(32);
this vector has exactly 32 elements and can not be resized.
</verbatim>

<a id="i12n"></a>
<h2>Initialization of Sequence Containers</h2>
<verbatim>
#include
</verbatim>

<b>[Features/SequencesInitialization|Initialization of Sequences]</b>: a way to use a syntax similar to C++11's <code>{ , , , }</code> initialization of containers in various kinda of sequence-like containers, even in C++03.

<verbatim>
CXXO_I12N_SEQ (vector<string>, mystrings, { "foo", "bar", "baz" } );
operate on mystrings
cout<< mystrings[1]<< endl; foo
</verbatim>

<a id="localfun"></a>
<h2>Local Function Emulation</h2>
<verbatim>
#include
</verbatim>

<b>[Features/LocalFunction|Using local functions in template calls]</b>: a way to have locally defined functions or functors, which then can be used as arguments for eg.: STL algorithm calls. While one of the big limitations in C++03 is the inability to use <em>local types</em> as arguments to anything templated, this library adds a partial implementation that creates proxy functor objects, where the actual "calling" code resides out of scope, and that produces code near transpartent to C++11 onwards.

<verbatim>
here, X is a tag that identifies the functor type in case one needs to add state or other nontrivial behaviour
CXXO_LOCALFN(X,void(int,int)) (int x0, int x1) {
    std::cout<< '{'<< x0+1<< ','<< x1-1<< '}'<< std::endl;
}
CXXO_LOCALFN_NAME(X,mi_fn);
function<void(int,int)> f_localfn = mi_fn; <-- can only exist in the current scope

CXXO_LOCALFN(Neg_,int(int)) (int x) {
    return -x;
    }
CXXO_LOCALFN_NAME(Neg_,negate);
transform( begin(sequence), end(sequence), begin(sequence), negate );

</verbatim>

<a id="type_name"></a>
<h2>Type Identification</h2>
<verbatim>
#include
</verbatim>

  *  <code>template <typename T><br/>std::string <b>type_name</b> ()</code> (1)
  *  <code>std::string <b>typeid_demangle</b> (std::type_info const&)</code> (2)

Given:

(1) a type T passed as a template argument;
(2) a function argument resulting from <em>typeid</em> evaluation;

these utilities return information from <code>typeid::name()</code>,
except this information is demangled if demangling is available.

<a id="typesafeenum"></a>
<h2>Typesafe Enums</h2>
<verbatim>
#include
</verbatim>

- a typesafe declaration wrapper for enum types, that implements the basic idea behind the <code>enum class...</code> feature of C++11.


<h2>Supplemental Headers</h2>

<a name="cxxo-sup-algorithm"></a>
<h3>Supplementals for <algorithm></h3>
<verbatim>
#include
</verbatim>

Names made available: <tt>copy_leftmost_n, copy_rightmost_n, find_inversion, fix_inversion, valcmp, transform_inplace</tt>, etc.

of the functions and interfaces included in this supplement].

<a name="cxxo-sup-functional"></a>
<h3>Supplementals for <functional></h3>
<verbatim>
#include
</verbatim>

of the functions and interfaces included in this supplement].

<b>Functional supplements to operator wrappers</b> - Just as there exists <code>std::plus</code> to wrap <code>operator+</code>, cxxomfort provides wrappers for the assignment version of those operators.

  *  <code>plus_it</code> - applies "<code>+=</code>" to its arguments.
  *  <code>minus_it</code> - applies "<code>-=</code>" to its arguments.
  *  <code>multiplies_it</code> - applies "<code>*=</code>" to its arguments.
  *  <code>divides_it</code> - applies to its arguments.
  *  <code>modulus_it</code> - applies "<code>%=</code>" to its arguments.
  *  <code>noop</code>, a simple do-nothing function object for completeness.

<b>Other features</b>

  *  <tt>functiontype</tt> - type traits for function signatures such as return type, arity, etc.
  *  <tt>function_ref</tt> from LLVM.
  *  <tt>function_caller</tt> - zero overhead functor for calling a named C function.

<a name="cxxo-sup-iterator"></a>
<h3>Supplementals for <iterator></h3>
<verbatim>
#include
namespace cxxomfort::library::iterator;
</verbatim>

Names made available: <tt>ssize , absdistance , fake_iterator</tt> etc.

of the functions and interfaces included in this supplement].

<a name="cxxo-sup-numeric"></a>
<h3>Supplementals for <numeric></h3>
<verbatim>
#include
namespace cxxomfort::library::numeric;
</verbatim>

This header mostly provides static / compile time alternatives to <tt><numeric></tt>'s constexpr additions such as gcd and lcm, as well as a number of static / compile-time accumulators such as <tt>static_minmax</tt> and <tt>static_sum</tt>.

of the functions and interfaces included in this supplement].

<a name="cxxo-sup-random"></a>
<h3>Supplementals for <random></h3>
<verbatim>
#include
namespace cxxomfort::library::random;
</verbatim>

  *  <tt>MMIX</tt>, <tt>numerical_recipes</tt> named typedefs for std linear engine.
  *  <tt>reseed</tt> and <tt>randint</tt> from Fundamentals V2.
  *  <tt>splitmix64</tt> PRNG.

<a name="cxxo-sup-string"></a>
<h3>Supplementals for <string></h3>
<verbatim>
#include
namespace cxxomfort::library::string;
</verbatim>

of the functions and interfaces included in this supplement].

Features include:

  *  Generic <tt>to_string</tt> from p0117.
  *  Generic <tt>ltrim, rtrim</tt> functions.
  *  <tt>string_cast</tt>.

<a name="cxxo-sup-tuple"></a>
<h3>Supplementals for <tuple></h3>
<verbatim>
#include
</verbatim>

Features include:

  *  <code>is_tuple</code> - type trait to recognize a tuple.
  *  <code>tuple_pop</code> - creates a tuple with the last (rightmost) element removed.
  *  <code>tuple_shift</code> - creates a tuple with the first (leftmost) element removed (C++11 onwards only).
  *  <code>tuple2function_t</code> - creates a function signature type (<code>R(T1,T2,...)</code>) according to a list of tuple arguments (<code>tuple<T1,T2,...></code>).
  *  <code>function2tuple_t</code> - the inverse of the above.

<a name="cxxo-sup-type_traits"></a>
<h3>Supplementals for <type_traits></h3>
<verbatim>
#include
</verbatim>

Type_traits to recognize types, that are either implemented here or pulled from other cxxomfort facilities into the header:

<verbatim>
is_std_array --> std::array<T,N>
is_std_byte --> std::byte
is_std_function --> std::function<Signature>
is_iterator --> Any type that specializes std::iterator_traits
is_pair --> std::pair<A,B>
is_tuple --> std::tuple<...>
is_sequence --> Any type that provides a begin() and end()
is_enumeration_like --> enum { ... } or any type that implements typesafe_enum<...>

</verbatim>

<a name="cxxo-sup-utility"></a>
<h3>Supplementals for <utility></h3>
<verbatim>
#include
</verbatim>

of the functions and interfaces included in this supplement].


<h2>Other Features</h2>


The following traits are available in as assistance when writing generic / quasi-generic code.


Given a type <em>T</em> and a list of types <em>A1, A2, …, A9</em>, the trait <code>is_any_of<T, A1, A2, …, A9></code> inherits from <code>std::true_type</code> if:

  *  T is an exact <u>cv-qualified match</u> for any of the types A1, A2, …, A9.

In both C++03 and C++11, this trait can take up to 10 candidate types.


Given a type <em>T</em>, the trait <code>result_of_function<T></code> defines the member type <code>::type</code>, as a type to-be-determined below, if:

  *  T is a type signature of a function type eg.: <code>T = R(A1,A2, …)</code>. In this case, <code>type: R</code>.
  *  T is a pointer type to the above eg.: <code>T = R(*)(A1,A2,…)</code>. In this case, <code>type</code> is defined as in the above.
  *  (<b>Not implemented yet</b>) T is <code>std::random_device</code>. In this case, <code>type: unsigned int</code>.


In C++03 mode, this trait can recognize function types up to 10 arguments.


Given a compile-time integer <em>N</em>, with <code>N≥0</code>, this trait defines the member type <code>::type</code>, as a type to-be-determined-below, if:

  *  There exists a native signed integral type <em>I</em> such that <code>sizeof(I)==N</code>. In this case, <code>type: I</code>.

If there is no integral type for the given value of <em>N</em>, instantiation of this template results in an error.

<h3>Utility Functions</h3>


This trait defines the static member variable <code>const char* value</code> as the literal string corresponding to the "null device" recognized by the OS in the current compiler.

  *  Under POSIX, this is
  *  Under Microsoft Windows, this is <code>"NUL"</code>.
  *  Under other systems this is left a null-string.

----

<b>C++ [Features]</b> -- <b>[Cxxomfort|Back to the beginning]</b>