Annex D (normative) Compatibility features [depr]

The header <ccomplex> behaves as if it simply includes the header <complex> ([complex.syn]).

The contents of the header <cstdalign> are the same as the C standard library header <stdalign.h>, with the following changes: The header <cstdalign> and the header <stdalign.h> shall not define a macro named alignas.

See also: ISO C 7.15.

The contents of the header <cstdbool> are the same as the C standard library header <stdbool.h>, with the following changes: The header <cstdbool> and the header <stdbool.h> shall not define macros named bool, true, or false.

See also: ISO C 7.18.

The header <ctgmath> simply includes the headers <complex> ([complex.syn]) and <cmath> ([cmath.syn]).

[ Note: The overloads provided in C by type-generic macros are already provided in <complex> and <cmath> by “sufficient” additional overloads. — end note ]

The class strstreambuf associates the input sequence, and possibly the output sequence, with an object of some character array type, whose elements store arbitrary values. The array object has several attributes.

[ Note: For the sake of exposition, these are represented as elements of a bitmask type (indicated here as T1) called strstate. The elements are:

• (2.1)

  allocated, set when a dynamic array object has been allocated, and hence should be freed by the destructor for the strstreambuf object;

• (2.2)

  constant, set when the array object has const elements, so the output sequence cannot be written;

• (2.3)

  dynamic, set when the array object is allocated (or reallocated) as necessary to hold a character sequence that can change in length;

• (2.4)

  frozen, set when the program has requested that the array object not be altered, reallocated, or freed.

 — end note ]

[ Note: For the sake of exposition, the maintained data is presented here as:

• (3.1)

  strstate strmode, the attributes of the array object associated with the strstreambuf object;

• (3.2)

  int alsize, the suggested minimum size for a dynamic array object;

• (3.3)

  void* (*palloc)(size_­t), points to the function to call to allocate a dynamic array object;

• (3.4)

  void (*pfree)(void*), points to the function to call to free a dynamic array object.

 — end note ]

Each object of class strstreambuf has a seekable area, delimited by the pointers seeklow and seekhigh. If gnext is a null pointer, the seekable area is undefined. Otherwise, seeklow equals gbeg and seekhigh is either pend, if pend is not a null pointer, or gend.

The class istrstream supports the reading of objects of class strstreambuf. It supplies a strstreambuf object to control the associated array object. For the sake of exposition, the maintained data is presented here as:

• (1.1)

  sb, the strstreambuf object.

The class ostrstream supports the writing of objects of class strstreambuf. It supplies a strstreambuf object to control the associated array object. For the sake of exposition, the maintained data is presented here as:

• (1.1)

  sb, the strstreambuf object.

The class strstream supports reading and writing from objects of class strstreambuf. It supplies a strstreambuf object to control the associated array object. For the sake of exposition, the maintained data is presented here as:

• (1.1)

  sb, the strstreambuf object.

A call wrapper may have a weak result type. If it does, the type of its member type result_­type is based on the type T of the wrapper's target object:

• (1.1)

  if T is a pointer to function type, result_­type shall be a synonym for the return type of T;

• (1.2)

  if T is a pointer to member function, result_­type shall be a synonym for the return type of T;

• (1.3)

  if T is a class type and the qualified-id T​::​result_­type is valid and denotes a type ([temp.deduct]), then result_­type shall be a synonym for T​::​result_­type;

• (1.4)

  otherwise result_­type shall not be defined.

To enable old function adaptors to manipulate function objects that take one or two arguments, many of the function objects in this International Standard correspondingly provide typedef-names argument_­type and result_­type for function objects that take one argument and first_­argument_­type, second_­argument_­type, and result_­type for function objects that take two arguments.

The following member names are defined in addition to names specified in Clause [function.objects]:

namespace std {
  template<class T> struct owner_less<shared_ptr<T>> {
    using result_type          = bool;
    using first_argument_type  = shared_ptr<T>;
    using second_argument_type = shared_ptr<T>;
  };

  template<class T> struct owner_less<weak_ptr<T>> {
    using result_type          = bool;
    using first_argument_type  = weak_ptr<T>;
    using second_argument_type = weak_ptr<T>;
  };

  template <class T> class reference_wrapper {
  public :
    using result_type          = see below; // not always defined
    using argument_type        = see below; // not always defined
    using first_argument_type  = see below; // not always defined
    using second_argument_type = see below; // not always defined
  };

  template <class T> struct plus {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct minus {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct multiplies {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct divides {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct modulus {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct negate {
    using argument_type = T;
    using result_type   = T;
  };

  template <class T> struct equal_to {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct not_equal_to {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct greater {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct less {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct greater_equal {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct less_equal {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct logical_and {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct logical_or {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = bool;
  };

  template <class T> struct logical_not {
    using argument_type = T;
    using result_type   = bool;
  };

  template <class T> struct bit_and {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct bit_or {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct bit_xor {
    using first_argument_type  = T;
    using second_argument_type = T;
    using result_type          = T;
  };

  template <class T> struct bit_not {
    using argument_type = T;
    using result_type   = T;
  };

  template<class R, class T1>
  class function<R(T1)> {
  public:
    using argument_type = T1;
  };

  template<class R, class T1, class T2>
  class function<R(T1, T2)> {
  public:
    using first_argument_type  = T1;
    using second_argument_type = T2;
  };
}

reference_­wrapper<T> has a weak result type. If T is a function type, result_­type shall be a synonym for the return type of T.

The template specialization reference_­wrapper<T> shall define a nested type named argument_­type as a synonym for T1 only if the type T is any of the following:

• (4.1)

  a function type or a pointer to function type taking one argument of type T1

• (4.2)

  a pointer to member function R T0​::​f() cv (where cv represents the member function's cv-qualifiers); the type T1 is cv T0*

• (4.3)

  a class type where the qualified-id T​::​argument_­type is valid and denotes a type ([temp.deduct]); the type T1 is T​::​argument_­type.

The template instantiation reference_­wrapper<T> shall define two nested types named first_­argument_­type and second_­argument_­type as synonyms for T1 and T2, respectively, only if the type T is any of the following:

• (5.1)

  a function type or a pointer to function type taking two arguments of types T1 and T2

• (5.2)

  a pointer to member function R T0​::​f(T2) cv (where cv represents the member function's cv-qualifiers); the type T1 is cv T0*

• (5.3)

  a class type where the qualified-ids T​::​first_­argument_­type and T​::​second_­argument_­type are both valid and both denote types ([temp.deduct]); the type T1 is T​::​first_­argument_­type and the type T2 is T​::​second_­argument_­type.

All enabled specializations hash<Key> of hash ([unord.hash]) provide two nested types, result_­type and argument_­type, which shall be synonyms for size_­t and Key, respectively.

The forwarding call wrapper g returned by a call to bind(f, bound_­args...) ([func.bind.bind]) shall have a weak result type.

The forwarding call wrapper g returned by a call to bind<R>(f, bound_­args...) ([func.bind.bind]) shall have a nested type result_­type defined as a synonym for R.

The simple call wrapper returned from a call to mem_­fn(pm) shall have a nested type result_­type that is a synonym for the return type of pm when pm is a pointer to member function.

The simple call wrapper returned from a call to mem_­fn(pm) shall define two nested types named argument_­type and result_­type as synonyms for cv T* and Ret, respectively, when pm is a pointer to member function with cv-qualifier cv and taking no arguments, where Ret is pm's return type.

The simple call wrapper returned from a call to mem_­fn(pm) shall define three nested types named first_­argument_­type, second_­argument_­type, and result_­type as synonyms for cv T*, T1, and Ret, respectively, when pm is a pointer to member function with cv-qualifier cv and taking one argument of type T1, where Ret is pm's return type.

The following member names are defined in addition to names specified in Clause [containers]:

namespace std {
  template <class Key, class T, class Compare, class Allocator>
  class map<Key, T, Compare, Allocator>::value_compare {
  public:
    using result_type          = bool;
    using first_argument_type  = value_type;
    using second_argument_type = value_type;
  };

  template <class Key, class T, class Compare, class Allocator>
  class multimap<Key, T, Compare, Allocator>::value_compare {
  public:
    using result_type          = bool;
    using first_argument_type  = value_type;
    using second_argument_type = value_type;
  };
}

The header <functional> has the following additions:

namespace std {
  template <class Predicate> class unary_negate;
  template <class Predicate>
    constexpr unary_negate<Predicate> not1(const Predicate&);
  template <class Predicate> class binary_negate;
  template <class Predicate>
    constexpr binary_negate<Predicate> not2(const Predicate&);
}

Negators not1 and not2 take a unary and a binary predicate, respectively, and return their logical negations ([expr.unary.op]).

template <class Predicate>
class unary_negate {
public:
  constexpr explicit unary_negate(const Predicate& pred);
  constexpr bool operator()(const typename Predicate::argument_type& x) const;
  using argument_type = typename Predicate::argument_type;
  using result_type   = bool;
};

The header <iterator> has the following addition:

namespace std {
  template<class Category, class T, class Distance = ptrdiff_t,
    class Pointer = T*, class Reference = T&>
  struct iterator {
    using iterator_category = Category;
    using value_type        = T;
    using difference_type   = Distance;
    using pointer           = Pointer;
    using reference         = Reference;
  };
}

The iterator template may be used as a base class to ease the definition of required types for new iterators.

[ Note: If the new iterator type is a class template, then these aliases will not be visible from within the iterator class's template definition, but only to callers of that class. — end note ]

[ Example: If a C++ program wants to define a bidirectional iterator for some data structure containing double and such that it works on a large memory model of the implementation, it can do so with:

class MyIterator :
  public iterator<bidirectional_iterator_tag, double, long, T*, T&> {
  // code implementing ++, etc.
};

 — end example ]

For each of the three code conversion facets codecvt_­utf8, codecvt_­utf16, and codecvt_­utf8_­utf16:

• (1.1)

  Elem is the wide-character type, such as wchar_­t, char16_­t, or char32_­t.

• (1.2)

  Maxcode is the largest wide-character code that the facet will read or write without reporting a conversion error.

• (1.3)

  If (Mode & consume_­header), the facet shall consume an initial header sequence, if present, when reading a multibyte sequence to determine the endianness of the subsequent multibyte sequence to be read.

• (1.4)

  If (Mode & generate_­header), the facet shall generate an initial header sequence when writing a multibyte sequence to advertise the endianness of the subsequent multibyte sequence to be written.

• (1.5)

  If (Mode & little_­endian), the facet shall generate a multibyte sequence in little-endian order, as opposed to the default big-endian order.

For the facet codecvt_­utf8:

• (2.1)

  The facet shall convert between UTF-8 multibyte sequences and UCS2 or UCS4 (depending on the size of Elem) within the program.

• (2.2)

  Endianness shall not affect how multibyte sequences are read or written.

• (2.3)

  The multibyte sequences may be written as either a text or a binary file.

For the facet codecvt_­utf16:

• (3.1)

  The facet shall convert between UTF-16 multibyte sequences and UCS2 or UCS4 (depending on the size of Elem) within the program.

• (3.2)

  Multibyte sequences shall be read or written according to the Mode flag, as set out above.

• (3.3)

  The multibyte sequences may be written only as a binary file. Attempting to write to a text file produces undefined behavior.

For the facet codecvt_­utf8_­utf16:

• (4.1)

  The facet shall convert between UTF-8 multibyte sequences and UTF-16 (one or two 16-bit codes) within the program.

• (4.2)

  Endianness shall not affect how multibyte sequences are read or written.

• (4.3)

  The multibyte sequences may be written as either a text or a binary file.

See also: ISO/IEC 10646-1:1993.

Class template wstring_­convert performs conversions between a wide string and a byte string. It lets you specify a code conversion facet (like class template codecvt) to perform the conversions, without affecting any streams or locales. [ Example: If you want to use the code conversion facet codecvt_­utf8 to output to cout a UTF-8 multibyte sequence corresponding to a wide string, but you don't want to alter the locale for cout, you can write something like:

wstring_convert<std::codecvt_utf8<wchar_t>> myconv;
std::string mbstring = myconv.to_bytes(L"Hello\n");
std::cout << mbstring;

 — end example ]

namespace std {
  template <class Codecvt, class Elem = wchar_t,
            class Wide_alloc = allocator<Elem>,
            class Byte_alloc = allocator<char>>
    class wstring_convert {
    public:
      using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
      using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
      using state_type  = typename Codecvt::state_type;
      using int_type    = typename wide_string::traits_type::int_type;

      explicit wstring_convert(Codecvt* pcvt = new Codecvt);
      wstring_convert(Codecvt* pcvt, state_type state);
      explicit wstring_convert(const byte_string& byte_err,
                               const wide_string& wide_err = wide_string());
      ~wstring_convert();

      wstring_convert(const wstring_convert&) = delete;
      wstring_convert& operator=(const wstring_convert&) = delete;

      wide_string from_bytes(char byte);
      wide_string from_bytes(const char* ptr);
      wide_string from_bytes(const byte_string& str);
      wide_string from_bytes(const char* first, const char* last);

      byte_string to_bytes(Elem wchar);
      byte_string to_bytes(const Elem* wptr);
      byte_string to_bytes(const wide_string& wstr);
      byte_string to_bytes(const Elem* first, const Elem* last);

      size_t converted() const noexcept;
      state_type state() const;

    private:
      byte_string byte_err_string;  // exposition only
      wide_string wide_err_string;  // exposition only
      Codecvt* cvtptr;              // exposition only
      state_type cvtstate;          // exposition only
      size_t cvtcount;              // exposition only
    };
}

The class template describes an object that controls conversions between wide string objects of class basic_­string<Elem, char_­traits<Elem>, Wide_­alloc> and byte string objects of class basic_­string<char, char_­traits<char>, Byte_­alloc>. The class template defines the types wide_­string and byte_­string as synonyms for these two types. Conversion between a sequence of Elem values (stored in a wide_­string object) and multibyte sequences (stored in a byte_­string object) is performed by an object of class Codecvt, which meets the requirements of the standard code-conversion facet codecvt<Elem, char, mbstate_­t>.

An object of this class template stores:

• (3.1)

  byte_­err_­string — a byte string to display on errors

• (3.2)

  wide_­err_­string — a wide string to display on errors

• (3.3)

  cvtptr — a pointer to the allocated conversion object (which is freed when the wstring_­convert object is destroyed)

• (3.4)

  cvtstate — a conversion state object

• (3.5)

  cvtcount — a conversion count

Class template wbuffer_­convert looks like a wide stream buffer, but performs all its I/O through an underlying byte stream buffer that you specify when you construct it. Like class template wstring_­convert, it lets you specify a code conversion facet to perform the conversions, without affecting any streams or locales.

namespace std {
  template <class Codecvt, class Elem = wchar_t, class Tr = char_traits<Elem>>
    class wbuffer_convert : public basic_streambuf<Elem, Tr> {
    public:
      using state_type = typename Codecvt::state_type;

      explicit wbuffer_convert(streambuf* bytebuf = 0,
                               Codecvt* pcvt = new Codecvt,
                               state_type state = state_type());

      ~wbuffer_convert();

      wbuffer_convert(const wbuffer_convert&) = delete;
      wbuffer_convert& operator=(const wbuffer_convert&) = delete;

      streambuf* rdbuf() const;
      streambuf* rdbuf(streambuf* bytebuf);

      state_type state() const;

    private:
      streambuf* bufptr;            // exposition only
      Codecvt* cvtptr;              // exposition only
      state_type cvtstate;          // exposition only
  };
}

The class template describes a stream buffer that controls the transmission of elements of type Elem, whose character traits are described by the class Tr, to and from a byte stream buffer of type streambuf. Conversion between a sequence of Elem values and multibyte sequences is performed by an object of class Codecvt, which shall meet the requirements of the standard code-conversion facet codecvt<Elem, char, mbstate_­t>.

An object of this class template stores:

• (3.1)

  bufptr — a pointer to its underlying byte stream buffer

• (3.2)

  cvtptr — a pointer to the allocated conversion object (which is freed when the wbuffer_­convert object is destroyed)

• (3.3)

  cvtstate — a conversion state object