Artifact 1860bc759b2c9ffa0e75bcc18b1a282c360587ec:

Wiki page [IndependentFeatures] by luismachuca 2017-12-24 19:03:51.
D 2017-12-24T19:03:51.212
L IndependentFeatures
P 679f10a86897e81fa625d6e402574f75aa88266c
U luismachuca
W 12963
<h1>Cxxomfort Library Utilities</h1>

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

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

Unlike [Features/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-library-algorithm|Supplementals for <algorithm>]
  *  [#cxxo-library-functional|Supplementals for <functional>]
  *  [#cxxo-library-iterator|Supplementals for <iterator>]
  *  [#cxxo-library-random|Supplementals for <random>]
  *  [#cxxo-library-string|Supplementals for <string>]
  *  [#cxxo.library-tuple|Supplementals for <tuple>]
  *  Foreach Loop Emulation
  *  <code>fixed_vector</code>
  *  Initialization of sequences
  *  Local Function Emulation
  *  Movable <code>pair</code>
  *  Type Identification utilities
  *  Typesafe Enums



<h2>Foreach Loop</h2>

<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>
Sequence<string> mystrings;
// fill mystrings somehow
CXXO_FOREACH /string const& s, mystrings) {
    ....
}
</verbatim>

<h2>Fixed_vector</h2>

<b>[Features/FixedVector|<code>fixed_vector<T></code>]</b> - the oft sought for holy grail of a <code>std::vector</code> whose size is fixed at construction as an invariant.

<h2>Initialization of Sequence Containers</h2>

<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>
typedef vector<string> VS_t;
CXXO_I12N_SEQ (VS_t, mystrings, { "foo", "bar", "baz" } );
// operate on mystrings
cout<< mystrings[1]<< endl;

</verbatim>

<h2>Local Function Emulation</h2>

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

<h2>Type Identification</h2>

  *  <code>std::string <b>typeid_demangle</b> (std::type_info const&)</code>

Given an argument resulting from <em>typeid</em> evaluation, returns the same information as <code>typeid::name()</code>, except this information is demangled if demangling is available.


  *  <code>template <type_name <b>T</b>><br/>std::string <b>type_name</b> ()</code>

Given a template argument type, this returns the same information as the above, except this takes into consideration cv-qualifiers and, in C++11, reference types, that are usually missed by <code>typeid</code>.

<h2>Typesafe Enums</h2>

<b>[Features/typesafe_enum|<code>typesafe_enum<T,S></code>]</b> - 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-library-algorithm"></a>
<h3>Supplemental Algorithms for <algorithm></h3>

As a supplement to the features of C++ Standards available in <code><algorithm></code>, cxxomfort provides a number of algorithms and generics of its own make available from <code><cxxomfort/library/algorithmfn.hpp></code>.

  *  <code>accumulate_separate</code> - accumulates elements over a range, including a selected "separator" element over each iteration.
  *  <code>count_frequencies</code> - counts elements in a range, keeping count of each separate value found in an external indexable range.
  *  <code>count_while</code> - iterates over the elements of a range, keeping a count of iterations.
  *  <code>find_last_if</code> - finds the last element in a range that fulfills a predicate.
  *  <code>transform_inplace</code> - three-argument version of <code>transform</code> that transforms the same range being iterated.
  *  <code>transform_n</code> - the "_n" counterpart to transform as copy_n is to copy.

<a name="cxxo-library-functional"></a>
<h3>Supplemental Utilities for <functional></h3>

As a supplement to the features of C++ Standards available in <code><functional></code>, cxxomfort provides a number of functional apparatuses of its own make available from <code><cxxomfort/library/functionalfn.hpp></code> and <code><cxxomfort/library/operatorit.hpp></code>.

<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 "<code>/=</code>" to its arguments.
  *  <code>modulus_it</code> - applies "<code>%=</code>" to its arguments.


<a name="cxxo-library-iterator"></a>
<h3>Supplemental Utilities for <iterator></h3>

As a supplement to the features of C++ Standards available in <code><iterator></code>, cxxomfort provides a number of algorithms and generics of its own make available from <code><cxxomfort/library/iteratorfn.hpp></code>.

  *  <code>fake_iterator</code> - an iterator that does not "iterate" anywhere, and is just dereferenciable to a given object. Basically a synonym for "constant_iterator".


<a name="cxxo-library-string"></a>
<h3>Supplemental String Utilities</h3>

As a supplement to the features of C++ Standards available in <code><string></code>, cxxomfort provides a number of algorithms and generics of its own make available from <code><cxxomfort/library/stringfn.hpp></code>.

  *  The variadic form of <code>to_string</code> as suggested by [http://open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0117r0.html|p0117r0].
  *  Similes to the PHP functions "implode" and "explode", for joining and splitting strings.


<a name="cxxo-library-tuple"></a>
<h3>Supplemental Tuple Utilities</h3>

As a supplement to the features of C++ Standards available in <code><tuple></code>, cxxomfort provides a number of algorithms and generics of its own make available from <code><cxxomfort/library/tuplefn.hpp></code>.

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



<h3>Supplemental Type Traits</h3>

  *  <code>is_iterator</code> - to recognize an iterator.
  *  <code>is_std_function</code> - to recognize a <code>std::function</code>.
  *  <code>is_pair</code> - to recognize a <code>std::pair</code> (in C++03, also a <code>cxxomfort::pair</code>).
  *  <code>is_tuple</code> - to recognize a <code>std::tuple</code>.


Given a type <em>T</em>, the trait <code>is_iterator</code> inherits from <code>std::true_type</code> if:

  *  there exists a specialization of <code>std::iterator_traits</code> for the given T. 
  *  Alternatively, T is a non-void pointer type.


Given a type <em>T</em>, the trait <code>is_pair</code> inherits from <code>std::true_type</code> if:

  *  T is a <code>std::pair</code>.
  *  (C++03 only) T is a <code>cxxomfort::pair</code>.

Similarly, <code>is_tuple</code> inherits from the true type if:

  *  T is a <code>std::tuple</code>.
  *  Alternatively, in C++03 mode, T is a <code>std::tr1::tuple</code> with up to 10 elements, or more if the compiler supports variadic templates in "emulation" mode.


<h3>Supplemental Utilities</h3>

<h2>Other Features</h2>


The following traits are available in <code>cxxomfort/utilities.hpp</code> as assistance when writing generic / quasi-generic code.


<h4><code>is_any_of</code></h4>

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.



<h4><code>is_sequence</code></h4>

Given a type <em>T</em>, the trait <code>is_sequence</code> inherits from <code>std::true_type</code> if:

  *  T defines both a <code>::const_iterator</code> and a <code>::value_type</code> member types.
  *  Alternatively, T is a native C array of known bounds (ie.: a <code><nowiki>T(&)[N]</nowiki></code> for a known N).


<h4><code>function_arity</code></h4>

Given a type <em>T</em>, the trait <code>function_arity<T></code> inherits from <code>std::integral_constant<size_t, N></code> for N 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>N</code> is equal to the number of function arguments in the signature type.
  *  T is a <code>std::function</code> for a given type signature of the above. In this case, <code>N</code> is equal to the number of function arguments in the signature type.
  *  T is a <code>std::pointer_to_unary_function</code>. In this case, <code>N= 1</code>.
  *  T is a <code>std::pointer_to_binary_function</code>. In this case, <code>N=2</code>.
  *  (<b>Not implemented yet</b>) T is a generator type based off the templates <code>linear_congruential_engine</code>, <code>substract_with_carry_engine</code> or <code>mersenne_twister_engine</code>, or the type <code>random_device</code>. In this case, <code>N=0</code>.

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

If <em>T</em> is none of the above, an instantiation of <code>function_arity</code> results in an error.

<h4><code>result_of_function</code></h4>

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.


<h4><code>integral_of_size</code></h4>

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>

<h4><code>null_device</code></h4>

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 <code>"/dev/null"</code>
  *  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>


Z d7e5f3006e45ef6146f821a94b28fb3a