Artifact 9f6f07f3214bf3fa670b4c3702fa463bb036fa0b3bc3f2c9d882db9356726e66:

Wiki page [Features] by luismachuca 2018-12-21 21:52:01.
D 2018-12-21T21:52:01.702
L Features
P 2108334e374f83583c38bf01ff64553360187541c447e84ca06de0019ab625d6
U luismachuca
W 24490
The <b>cxxomfort</b> library adds various features that provide C++03, C++11 with partial support for features from later standards. For example, you can get some C++11 features in C++03, or C++14 features in C++11 (and sometimes even in C++03!). 

The featureset described here is automatically included when using <code>#include <cxxomfort/cxxomfort.hpp></code>, but you can get a more granular control of features by including specific headers.

<h2>Base Features</h2>

This is the base feature set that is always included automatically when you use this library. Most of it involves backporting to C++03 some features from C++11. In order to explicitly have access to these features, include the base header:

<verbatim>
#include <cxxomfort/base.hpp>
</verbatim>

  *  [#cxxo-nullptr|<tt>nullptr</tt>] aka null pointer literal.
  *  [#cxxo-static_assert|<tt>static_assert</tt>], compile-time assertions.
  *  [#cxxo-iterator|Iterator Helpers] such as global begin, end.
  *  [Features/explicit_cast|<tt>explicit_cast</tt>] / explicit operator conversion backports.
  *  [Features/MetaprogrammingHelpers|Metaprogramming Helpers] such as enable_if.
  *  [Features/rvref|Rvalue references, move and forward] emulation.
  *  [Features/integrals|Extended integral types], aka uint16_t etc.

<h2>Standard Features</h2>

This is the "normal" feature set, which basically consists of backporting or integrating features from selected C++ headers. In order to access these one can explicitly invoke cxxomfort.hpp, or any of the more specific headers with the backports wanted.

<verbatim>
#include <cxxomfort/cxxomfort.hpp>
</verbatim>

  *  [Features/SequencesInitialization|Initialization of Sequences and Containers]
  *  [#cxxo-algorithm|Features from <algorithm>]: new copy, sort, shuffle algorithms.
  *  [#cxxo-cstddef|Features from <cstddef>]: <tt>nullptr_t</tt>, <tt>byte</tt>, etc.
  *  [#cxxo-cstddint|Features from <cstdint>]: typedefs for integral types.
  *  [#cxxo-cstddint|Features from <cuchar>]: interfaces for character types.
  *  [#cxxo-forward_list|Features from <forward_list>], as in specifically <tt>std::forward_list</tt>.
  *  [#cxxo-functional|Features from <functional>], such as transparent functors.
  *  [#cxxo-limits|Features from <limits>], in particular constants for min/max.
  *  [#cxxo-memory|Features from <memory>], such as <tt>alignof</tt> and very especially "<tt>[#cxxo-unique_ptr|unique_ptr]</tt>" for dynamic management of objects.
  *  [#cxxo-numeric|Features from <numeric>]: that is, for the most part, <em>iota</em>.
  *  [#cxxo-random|Features from <random>]: C++03 renames of the C++11 random utilities.
  *  [#cxxo-string|Features from <string>], in particular <tt>to_string</tt>.
  *  [#cxxo-string_view|Features from <string_view>], that is basic_string_view and related interfaces, from C++17.
  *  [#cxxo-system_error|Features from <system_error>], such as the generic_error and system_error wrappers.
  *  [#cxxo-tuple|Features from <tuple>], in particular tuple get by type, and tuple "apply".
  *  [#cxxo-typeindex|Features from <typeindex>], such as <tt>type_index</tt>.
  *  [#cxxo-type_traits|Features from <type traits>] such as triviality and noexcept traits, <code>is_..._constructible</code>, <code>enable_if/conditional</code>, and <code>decay</code>.
  *  [#cxxo-utility|Features from <utility>], such as declval and exchange, and <tt>integer_sequence</tt> for C++11.

<h3>Cxxomfort Library Features</h3>
The library also adds some of [Supplements|its own assortment of features] specific to cxxomfort - as in, not part of C++ revisions or proposals.

<h2>Details </h2>

This library adds the features in a special namespace, <code>::cxxomfort</code>. To improve portability, then the features that are present in namespace <code>::std</code> in the new standard are added there via a <code>using</code> directive.

The library also implements some of the new [Features/Keywords|keywords added in C++11], in particular <code>static_assert</code>.

<h2>Details of Base Features</h2>

Here follows a listing of features.

<h3><a name="base-nullptr"></a>Null pointer literal</h3>

Implemented by <code>base.hpp</code>.

C++11 defines a "null pointer literal" as a special keyword that can be used to explicitly indicate a null pointer and its type. This allows code relying on null pointers to implement null-specific features such as function overloads, as well as avoid ambiguities due to null-to-integral promotion. In C++11, this literal is named `nullptr`  and is [http://en.cppreference.com/w/cpp/language/nullptr|documented here], including usage examples. 

This library implements the null pointer literal in C++03 in the way recommended by the Standard (see also [http://en.wikibooks.org/wiki/More_C++_Idioms/nullptr#Solution_and_Sample_Code|Meyer's implementation]).

When enabled, the macro <code>CXXOMFORT_USING_nullptr</code> is defined.

<b>Known limitations:</b>

  *  Requires the inclusion of a header to be used.
  *  Does not implement any operators beyond implicit conversion.

<hr/>
<h3><a name="base-static_assert"></a>Static Assert</h3>

Implements: n1604, [http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html|n1720].<br/>

Implemented by <code>base.hpp</code>.

C++11 adds the capability to perform assertions at compile time via a special keyword. This allows code to test for prerequisites at compile-time and deliver better error messages.

The compile-time assertion feature in C++11 is [http://en.cppreference.com/w/cpp/language/static_assert|documented here], including usage samples.

The <code>static_assert</code> keyword is implemented here as a pseudo-keyword using a macro with the same syntax; however, being a macro, it has some limitations.

(Starting in <code>version 0.42</code>) The extra pseudokeyword <code>static_assert0</code>.
 
When enabled, the macro <code>CXXOMFORT_USING_static_assert</code> is defined.

<b>Known limitations:</b>

  *  Can not take arguments containing comas - for those, wrapping parentheses, a typedef or an enum declaration are required (and recommended even in C++11 mode, as they make code clearer).
  *  The compiler won't be able to display the actual error message string, although it will at least point to its location (which, when using an IDE, should amount to the same effect).

<hr/>
<h3>Metaprogramming Helpers</h3>

Implementation of metaprogramming helpers such as identity, enable_if, etc.

See [Features/MetaprogrammingHelpers]. (To be documented)

<hr/>
<h3><a name="base-iterator"></a>Iterator Access Functions</h3>

Implemented by <code>iterator.hpp</code>. See also: https://en.cppreference.com/w/cpp/iterator .

The following interfaces are backported from C++11:

  *  <code>std::begin</code> and <code>std::end</code> -- generically find the begin and end iterators for a container-like expression.
  *  <code>std::next</code> and <code>std::prev</code> -- generically advance an iterator in forward or backward direction.

The following interfaces are backported from C++14

  *  <code>std::cbegin</code> -- generically return const_iterator with the same semantics as begin's.
  *  <code>std::cend</code> -- generically return const_iterator with the same semantics as end's.

Each of the <nowiki>[c][begin,end]</nowiki> functions is overloaded to take container-like objects that define iterator types and C-like arrays, as well as <code>std::valarray</code>, which is container-like but does not define iterator types.

The following interfaces are backported from C++17 (but they have a wider meaning and support):

  *  <code>size::size</code> -- generically return container size.

<hr/>

<h2>Details of Standard Features</h2>


<h3><a name="cxxo-algorithm"></a>Features from <algorithm></h3>

To enable these features, <code>#include</code> the cxxomfort/algorithms.hpp header (yes, the plural is part of the name). Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

The library includes some C++11, C++14 and C++17 algorithms backported to previous standard versions:

  *  The <code>uninitialized_copy_n</code> function.
  *  The "copy_if", "copy_n" and "partition_copy" algorithms. ([http://en.cppreference.com/w/cpp/algorithm/copy|External Documentation])
  *  The "[http://en.cppreference.com/w/cpp/algorithm/minmax|minmax]" and "[http://en.cppreference.com/w/cpp/algorithm/minmax_element|minmax_element]" algorithms. (External links)
  *  The "all_of", "any_of", "none_of" algorithms. ([http://en.cppreference.com/w/cpp/algorithm/all_any_none_of|External documentation])
  *  The "is_sorted" algorithm.
  *  The "is_permutation" algorithm.
  *  The new C++14 overloads for <code>equal</code> algorithm, specific to different-sized sequences.
  *  The new C++17 <code>clamp</code> algorithm. ([http://en.cppreference.com/w/cpp/algorithm/clamp|External Documentation])
  *  The "for_each_n" algorithm from C++17: https://en.cppreference.com/w/cpp/algorithm/for_each_n

Example usage:

<verbatim>
// external
struct is_odd_t { 
    int operator() (int) const {...} 
} is_odd:

// usage
vector<int> t, u;
...
copy_if (begin(t), end(t), back_inserter(u), is_odd);
assert (all_of(begin(u), end(u), is_odd);
u.sort();
assert (is_sorted(begin(u), end(u));
</verbatim>

  *  (TOBEDONE) The "shuffle" and "random_shuffle" algorithms.


<hr/>
<h3><a name="cxxo-cstddef"></a>Features from <cstddef></a></h3>

To enable these features, <code>#include</code> the cxxomfort/cstddef.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

As a convenience for portability, the [Transparent Headers|<cstddef>] header is also provided separately.

This enables access to a number of features from C++ that are declared in the <code><cstddef></code> header:

  *  <code>nullptr_t</code> from C++11 (see nullptr above).
  *  <code>std::max_align_t</code> from C++11.
  *  <code>std::byte</code> from C++17 (see [http://en.cppreference.com/w/cpp/types/byte|std::byte at cppreference] and [Features/std::byte] for more information).

<hr/>
<h3><a name="cxxo-cstdint"></a>Features from <cstdint></a></h3>

To enable these features, <code>#include</code> the cxxomfort/cstdint.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

As a convenience for portability, the [Transparent Headers|<cstdint>] header is also provided separately.

This enables access to a number of features from C++11 onwards, specifically the typedefs for integral types such as <code>uint16_t, int64_t</code>, etc.

<hr/>
<h3><a name="cxxo-cuchar"></a>Features from <cuchar></a></h3>

To enable these features, <code>#include</code> the cxxomfort/cuchar.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

This gives access, in C++03 mode, to the "character types" close airquotes <code>char16_t, char32_t</code>. This is limited to the types themselves, as there would be no practical way of embedding characters or character strings of these types in a C++03 source file without assistance from the lexer.


<hr/>
<h3><a name="cxxo-forward_list"></a>Features from <forward_list></h3>

To enable these features, <code>#include</code> the cxxomfort/forward_list.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

As a convenience for portability, the [Transparent Headers|<forward_list>] header is also provided separately.

This header adds barebones, mostly usable support for the "forward_list" sequence container in C++03. A <code>forward_list<T></code> behaves much like a <code>std::list</code>, except elements are only singly linked - thus, traversal is only possible in one direction, from begin to end.

<b>Header Synopsis</b>:

(pending)

The implementation is fairly incomplete as of yet, and it has some differences from the standard's provided one as I found it to be faulty.

  *  <code>push_back</code> and <code>emplace_back</code> members are provided.
  *  <code>size</code> member is provided.
  *  <code>insert</code> member taking a <u>iterator range</u> is provided.
  *  <code>before_begin</code> is not provided as of yet.
  *  <code>remove,remove_if</code> are unimplemented as of yet.
  *  <code>erase_after</code> is unimplemented as of yet.
  *  <code>unique</code> is unimplemented as of yet.
  *  <code>reverse,resize</code> are unimplemented as of yet.

The [Transparent Headers|transparent header] <code><forward_list></code> is also provided so that code can be written in a forwards-compatible manner using a standard #include directive. See the page for details.


<hr/>
<h3><a name="cxxo-functional"></a>Features from <functional></a></h3>

To enable these features, <code>#include</code> the cxxomfort/functional.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

The library includes some C++14 backported to previous standard versions:

  *  [Features/TransparentFunctors|Type-transparent functors] such as improved "bit_and" and "plus" (from [http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm|n3421]), aka: their <code><void></code> specializations.

The library also provides the following functionality for incomplete TR1 implementations:

  *  The standard family of <code>bit_and</code>, <code>bir_or</code> and <code>bit_xor</code> functors.


Example usage:

<verbatim>
// Generically "join" a sequence using the % operator, if so defined
class SumType;
struct Sum {
    template <typename SequenceType>
    SumType operator() (SequenceType const& ss) const {
        return accumulate (begin(vi), end(vi), modulus<void>() );
    }
};

SumType s;
vector<int> vi;
...; // add content to vi somehow
s= Sum()(vi); // <-- call does not need to be made aware of the type of vi's elements
vector<TypeWithModulus> vt;
...; // add content to vt somehow
s= Sum()(vt); // <-- call does not need to be made aware of the type of vt's elements

</verbatim>

<hr/>
<h3><a name="cxxo-iterator"></a>Features from <iterator></a></h3>

To enable these features, <code>#include</code> the cxxomfort/iterator.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

The header simply redirects to the base.hpp headers, as the iterator-related features form part of the base cxxomfort package. See [[#base-iterator|Iterator Helpers]] for more details.

  *  Nonmember "begin", "end" (already part of cxxomfort's base featureset).
  *  Nonmember "cbegin", "cend" from C++14.
  *  Nonmember "data", "size" and "empty" from C++17.


<hr/>
<h3><a name="cxxo-limits"></a>Features from <limits></a></h3>

To enable these features, <code>#include</code> the cxxomfort/limits.hpp header, which is not aggregated automatically.

The library includes a special template <code>integral_limits</code> that extends <code>std::numeric_limits</code> for integral types by adding const min, max members rather than functions, so that the values can be accessed generically from C++03.

For a given integral type <em>integral</em>, the type <code>cxxomfort::integral_limits<<em>integral</em>></code> inherits from <code>std::numeric_limits<integral></code>, and adds the following member values:

<verbatim>
template <typename integral> class integral_limits {
    // members from std::numeric_limits<integral>
    static const integral const_min = INTGRL_MIN; // implementation-defined
    static const integral const_max = INTGRL_MAX; // implementation-defined
    template <ushort> digits_base {
        uint value;
    };
};
</verbatim>

For example, <code>integral_limits<unsigned short>::const_min</code> is equal to <code>USHRT_MIN</code> (which should be zero).

The <code>const_min,const_max</code> member variable has the same value as what is returned by the <code>min(),max()</code> member functions.

The <code>digits_base</code> member template, instantiated with an integer value, defines <code>value</code> as a member with the number of digits the type takes in the given base, similar to <code>digits,digits10</code>.

<hr/>
<h3><a name="cxxo-memory"></a>Features from <memory></a></h3>

To enable these features, <code>#include</code> the cxxomfort/memory.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

The library includes some features that are available via the <code><memory></code> header for the management of pointers and memory:

  *  <code>addressof</code> from C++11.
  *  A "<code>alignof(T)</code>" macro that uses compiler specific to backport <code>alignof</code> keyword (in C++03 compilers, usually something like <code>__alignof</code>).
  *  A "<code>alignas</code>" macro that uses compiler specifics to backport <code>alignas</code> keyword.
  *  A partial implementation of C++11's <code>aligned_storage</code>, depending on the two above features.
  *  A barebones implementation of <code>pointer_traits</code> and of <code>allocator_traits</code> to ease uniform API usage when writing eg.: containers.
  *  A backport of <code>unique_ptr</code> for C++03, explained in its own section below.
  *  <code>make_unique</code> from C++14.

The library implements <code>alignof(type)</code> by calling a compiler-specific feature, usually something like <code>__alignof(type)</code>. For <code>alignas(size)</code>, only implemented in GCC for the moment, <code>__attribute__</code>s are used.

The implementation of <code>aligned_storage</code> is made compiler specific and either takes advantage of a compiler-defined intrinsic (in the case of GCC, MSVC) or aligns objects to the alignment of at most the largest known alignable native member (such as <code>long double</code> or a member function pointer).

<hr/>
<h3><a name="cxxo-unique_ptr"></a><code>unique_ptr</code> "Unique" Smart Pointer</h3>

Implemented by <code>unique_ptr.hpp</code>.

When using C++03 mode, this library implements the "unique_ptr" emulation created by Howard Hinnant. Once made available, the macro <code>CXXOMFORT_USING_unique_ptr</code> is defined.

[http://en.cppreference.com/w/cpp/memory/unique_ptr|Documentation on unique_ptr] (external link). It is recommended to check this documentation as it provides both example usage and the rationale for usage cases.


<hr/>
<h3><a name="cxxo-numeric"></a>Features from <numeric></a></h3>

To enable these features, <code>#include</code> the cxxomfort/numeric.hpp header.

The following interfaces from more advanced C++ versions are backported to previous versions:

  *  <code>iota</code> from C++11.

The following interfaces are also added:

  *  A complimentary <code>iota_n</code> for symmetry with copy_n, for_each_n, etc.


<hr/>
<h3><a name="cxxo-random"></a>Features from <random></a></h3>

To enable these features, <code>#include</code> the cxxomfort/random.hpp header. Or just include cxxomfort/cxxomfort.hpp and it will be added automatically.

As a convenience for portability, the [Transparent Headers|<random>] header is also provided separately.

This enables access to a number of features from later C++11 additions in C++03:

  *  Renames of the random utilities in <code><tr1/random></code> that changed name in C++11 onward, for example <code>std::tr1::uniform_int_distribution</code> for <code>std::tr1::uniform_int</code>.


<hr/>
<h3><a name="cxxo-string"></a>Features from <string></a></h3>

To enable these features, <code>#include</code> the cxxomfort/string.hpp header, which is not aggregated automatically.

The following interfaces from C++11 are defined and backported to C++03 by this header:

  *  The <code>to_string</code> function template, which allows constructing a string from eg.: a native type, such as a <code>long</code> numerical expression.
  *  <code>strto(u)ll</code> in versions of MSVC where it's not available under that name.

Example code:

<verbatim>
    time_t tt= time(0);
    struct tm tx;
    localtime_r(&tt,&tx);
    using namespace cxxomfort::string; // brings variadic to_string in
    string s= to_string(tx.tm_hour, ':', setw(2), setfill('0'), tx.tm_min);
    cout<< s<< endl;
</verbatim>

<hr/>
<h3><a name="cxxo-string_view"></a>Features from <string_view></a></h3>

To enable these features, <code>#include</code> the cxxomfort/string_view.hpp header, or just cxxomfort.hpp as usual.

The following interfaces from C++17 are defined and backported to C++03 and later by this header:

  *  <code>basic_string_view</code>, <code>string_view</code> and related typedefs.


<hr/>
<h3><a name="cxxo-system_error"></a>Features from <system_error></a></h3>

To enable these features, <code>#include</code> the cxxomfort/system_error.hpp header, which is not aggregated automatically.

The following interfaces from C++11 are defined and backported to C++03 by this header:

  *  The <code>error_category</code> facility and the assistant functions generic_error_category() and system_error_category().
  *  The <code>error_code</code> facility and the assistant functions such as <code>make_error_code</code>.
  *  The <code>errc</code> scoped enumeration.

On its own the header also provides the assist type <code>cxxomfort::errc</code> and assist function <code>to_errc</code>.

<hr/>
<h3><a name="cxxo-tuple"></a>Features from <tuple></a></h3>

To enable these features, <code>#include</code> the cxxomfort/tuple.hpp header, which is not aggregated automatically.

The following interfaces from more advanced C++ versions are backported here:

  *  <code>get<Type>(tuple)</code> - get a tuple's element by type (see: for an example).
  *  <code>apply(function,tuple)</code> - apply a functioid to all elements of a tuple (see: [http://en.cppreference.com/w/cpp/utility/apply|cppreference documentation]).
  *  <code>make_from_tuple<T></code> from C++17 - create an object using a tuple as constructor arguments (see:[http://en.cppreference.com/w/cpp/utility/make_from_tuple|cppreference documentation]).

<hr/>
<h3><a name="cxxo-type_traits"></a>Features from <type_traits></a></h3>

Various interfaces from C++'s <code><type_traits></code> header are ported here to previous versions:

  *  <code>is_lvalue_reference</code> and <code>is_rvalue_reference</code> mapped from C++11 to C++03.
  *  <code>is_null_pointer</code> from C++14 to previous Standards.
  *  triviality traits (is_trivially_xxxx) for C++03.
  *  <code>void_t</code>, <code>make_void</code> from C++17 to previous Standards.
  *  <code>type_identity</code> from C++17. [https://en.cppreference.com/w/cpp/types/type_identity|ref].
  *  <code>bool_constant</code> from C++17. [https://en.cppreference.com/w/cpp/types/bool_constant|ref].
  *  <code>endian</code> for endianness detection, from C++17. https://en.cppreference.com/w/cpp/types/endian|ref].
  *  Others.

<hr/>
<h3><a name="cxxo-utility"></a>Features from <utility></a></h3>

The following interfaces are brought in from their C++ versions to previous standards:

  *  <code>declval</code> to provide pseudovariables in unevaluated contexts, from C++11.
  *  <code>exchange</code> for pushing-in new values for variables, from C++14.
  *  <code>as_const</code> helper for const_casts, from C++17.

In C++03 mode, <code>declval</code> returns lvalue-references.

<b>For C++03 only</b>:

  *  A <code>pair03</code> class that implements std::pair with move capability.

The interface of this class is exact mirror to that of <code>std::pair</code> except for lacking tuple piecewise construction, but it supports movable types and is itself move-constructible and movable.

<verbatim>
template <typename TA, TB> 
class pair03 {
    pair03 ();
    pair03 (pair03 const&);
    pair03 (rvref<pair03> &); // move-emulation constructor
    template <typename TX, typename TY>
    pair03 (pair03<TX,TY> const&);
    
    TA first;
    TB second;
     
    // various operators...
};
</verbatim>

<b>For C++11 only</b>:

  *  An implementation of <code>integer_sequence</code> and <code>index_sequence</code>.


<hr/>

  *  [BehaviourMacros]
  *  [Supplements]
  *  [Features/Extras]
  *  [Cxxomfort|Back to the beginning]


Z 3357b404cc0d77eeb6b45b37914fed85