Annex D (normative) Compatibility features [depr]

This Clause describes features of the C++ Standard that are specified for compatibility with existing implementations.
These are deprecated features, where deprecated is defined as: Normative for the current edition of this International Standard, but having been identified as a candidate for removal from future revisions.
An implementation may declare library names and entities described in this Clause with the deprecated attribute.

D.1 Arithmetic conversion on enumerations [depr.arith.conv.enum]

The ability to apply the usual arithmetic conversions ([expr.arith.conv]) on operands where one is of enumeration type and the other is of a different enumeration type or a floating-point type is deprecated.
[Note
:
Three-way comparisons ([expr.spaceship]) between such operands are ill-formed.
end note
]
[Example
:
enum E1 { e };
enum E2 { f };
bool b = e <= 3.7;              // deprecated
int k = f - e;                  // deprecated
auto cmp = e <=> f;             // ill-formed
end example
]

D.2 Implicit capture of *this by reference [depr.capture.this]

For compatibility with prior C++ International Standards, a lambda-expression with capture-default = ([expr.prim.lambda.capture]) may implicitly capture *this by reference.
[Example
:
struct X {
  int x;
  void foo(int n) {
    auto f = [=]() { x = n; };          // deprecated: x means this->x, not a copy thereof
    auto g = [=, this]() { x = n; };    // recommended replacement
  }
};
end example
]

D.3 Array comparisons [depr.array.comp]

Equality and relational comparisons ([expr.eq], [expr.rel]) between two operands of array type are deprecated.
[Note
:
Three-way comparisons ([expr.spaceship]) between such operands are ill-formed.
end note
]
[Example
:
int arr1[5];
int arr2[5];
bool same = arr1 == arr2;       // deprecated, same as &arr[0] == &arr[1],
                                // does not compare array contents
auto cmp = arr1 <=> arr2;       // ill-formed
end example
]

D.4 Redeclaration of static constexpr data members [depr.static_constexpr]

For compatibility with prior C++ International Standards, a constexpr static data member may be redundantly redeclared outside the class with no initializer.
This usage is deprecated.
[Example
:
struct A {
  static constexpr int n = 5;  // definition (declaration in C++ 2014)
};

constexpr int A::n;  // redundant declaration (definition in C++ 2014)
end example
]

D.5 Implicit declaration of copy functions [depr.impldec]

The implicit definition of a copy constructor ([class.copy.ctor]) as defaulted is deprecated if the class has a user-declared copy assignment operator or a user-declared destructor ([class.dtor]).
The implicit definition of a copy assignment operator ([class.copy.assign]) as defaulted is deprecated if the class has a user-declared copy constructor or a user-declared destructor.
In a future revision of this International Standard, these implicit definitions could become deleted ([dcl.fct.def]).

D.6 C standard library headers [depr.c.headers]

For compatibility with the C standard library, the C++ standard library provides the C headers shown in Table 136.
Table 136 — C headers
<assert.h>
<inttypes.h>
<signal.h>
<stdio.h>
<wchar.h>
<complex.h>
<iso646.h>
<stdalign.h>
<stdlib.h>
<wctype.h>
<ctype.h>
<limits.h>
<stdarg.h>
<string.h>
<errno.h>
<locale.h>
<stdbool.h>
<tgmath.h>
<fenv.h>
<math.h>
<stddef.h>
<time.h>
<float.h>
<setjmp.h>
<stdint.h>
<uchar.h>

D.6.1 Header <complex.h> synopsis [depr.complex.h.syn]

#include <complex>
The header <complex.h> behaves as if it simply includes the header <complex> ([complex.syn]).
[Note
:
Names introduced by <complex> in namespace std are not placed into the global namespace scope by <complex.h>.
end note
]

D.6.2 Header <iso646.h> synopsis [depr.iso646.h.syn]

The C++ header <iso646.h> is empty.
[Note
:
and, and_­eq, bitand, bitor, compl, not_­eq, not, or, or_­eq, xor, and xor_­eq are keywords in this International Standard ([lex.key]).
end note
]

D.6.3 Header <stdalign.h> synopsis [depr.stdalign.h.syn]

#define __alignas_is_defined 1
The contents of the C++ header <stdalign.h> are the same as the C standard library header <stdalign.h>, with the following changes: The header <stdalign.h> does not define a macro named alignas.
See also: ISO C 7.15

D.6.4 Header <stdbool.h> synopsis [depr.stdbool.h.syn]

#define __bool_true_false_are_defined 1
The contents of the C++ header <stdbool.h> are the same as the C standard library header <stdbool.h>, with the following changes: The header <stdbool.h> does not define macros named bool, true, or false.
See also: ISO C 7.18

D.6.5 Header <tgmath.h> synopsis [depr.tgmath.h.syn]

#include <cmath>
#include <complex>
The header <tgmath.h> behaves as if it simply includes the headers <cmath> ([cmath.syn]) and <complex> ([complex.syn]).
[Note
:
The overloads provided in C by type-generic macros are already provided in <complex> and <cmath> by “sufficient” additional overloads.
end note
]
[Note
:
Names introduced by <cmath> or <complex> in namespace std are not placed into the global namespace scope by <tgmath.h>.
end note
]

D.6.6 Other C headers [depr.c.headers.other]

Every C header other than <complex.h>, <iso646.h>, <stdalign.h>, <stdbool.h>, and <tgmath.h>, each of which has a name of the form <name.h>, behaves as if each name placed in the standard library namespace by the corresponding <cname> header is placed within the global namespace scope, except for the functions described in [sf.cmath], the declaration of std::byte ([cstddef.syn]), and the functions and function templates described in [support.types.byteops].
It is unspecified whether these names are first declared or defined within namespace scope ([basic.scope.namespace]) of the namespace std and are then injected into the global namespace scope by explicit using-declarations.
[Example
:
The header <cstdlib> assuredly provides its declarations and definitions within the namespace std.
It may also provide these names within the global namespace.
The header <stdlib.h> assuredly provides the same declarations and definitions within the global namespace, much as in the C Standard.
It may also provide these names within the namespace std.
end example
]

D.7 Relational operators [depr.relops]

The header <utility> has the following additions:
namespace std::rel_ops {
  template<class T> bool operator!=(const T&, const T&);
  template<class T> bool operator> (const T&, const T&);
  template<class T> bool operator<=(const T&, const T&);
  template<class T> bool operator>=(const T&, const T&);
}
To avoid redundant definitions of operator!= out of operator== and operators >, <=, and >= out of operator<, the library provides the following:
template<class T> bool operator!=(const T& x, const T& y);
Requires: Type T is Cpp17EqualityComparable (Table 22).
Returns: !(x == y).
template<class T> bool operator>(const T& x, const T& y);
Requires: Type T is Cpp17LessThanComparable (Table 23).
Returns: y < x.
template<class T> bool operator<=(const T& x, const T& y);
Requires: Type T is Cpp17LessThanComparable (Table 23).
Returns: !(y < x).
template<class T> bool operator>=(const T& x, const T& y);
Requires: Type T is Cpp17LessThanComparable (Table 23).
Returns: !(x < y).

D.8 char* streams [depr.str.strstreams]

D.8.1 Header <strstream> synopsis [depr.strstream.syn]

The header <strstream> defines types that associate stream buffers with character array objects and assist reading and writing such objects.
namespace std {
  class strstreambuf;
  class istrstream;
  class ostrstream;
  class strstream;
}

D.8.2 Class strstreambuf [depr.strstreambuf]

namespace std {
  class strstreambuf : public basic_streambuf<char> {
  public:
    strstreambuf() : strstreambuf(0) {}
    explicit strstreambuf(streamsize alsize_arg);
    strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));
    strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = nullptr);
    strstreambuf(const char* gnext_arg, streamsize n);

    strstreambuf(signed char* gnext_arg, streamsize n,
                 signed char* pbeg_arg = nullptr);
    strstreambuf(const signed char* gnext_arg, streamsize n);
    strstreambuf(unsigned char* gnext_arg, streamsize n,
                 unsigned char* pbeg_arg = nullptr);
    strstreambuf(const unsigned char* gnext_arg, streamsize n);

    virtual ~strstreambuf();

    void  freeze(bool freezefl = true);
    char* str();
    int   pcount();

  protected:
    int_type overflow (int_type c = EOF) override;
    int_type pbackfail(int_type c = EOF) override;
    int_type underflow() override;
    pos_type seekoff(off_type off, ios_base::seekdir way,
                     ios_base::openmode which
                      = ios_base::in | ios_base::out) override;
    pos_type seekpos(pos_type sp,
                     ios_base::openmode which
                      = ios_base::in | ios_base::out) override;
    streambuf* setbuf(char* s, streamsize n) override;

  private:
    using strstate = T1;              // exposition only
    static const strstate allocated;  // exposition only
    static const strstate constant;   // exposition only
    static const strstate dynamic;    // exposition only
    static const strstate frozen;     // exposition only
    strstate strmode;                 // exposition only
    streamsize alsize;                // exposition only
    void* (*palloc)(size_t);          // exposition only
    void (*pfree)(void*);             // exposition only
  };
}
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:
  • allocated, set when a dynamic array object has been allocated, and hence should be freed by the destructor for the strstreambuf object;
  • constant, set when the array object has const elements, so the output sequence cannot be written;
  • dynamic, set when the array object is allocated (or reallocated) as necessary to hold a character sequence that can change in length;
  • 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:
  • strstate strmode, the attributes of the array object associated with the strstreambuf object;
  • int alsize, the suggested minimum size for a dynamic array object;
  • void* (*palloc)(size_­t), points to the function to call to allocate a dynamic array object;
  • 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.

D.8.2.1 strstreambuf constructors [depr.strstreambuf.cons]

explicit strstreambuf(streamsize alsize_arg);
Effects: Constructs an object of class strstreambuf, initializing the base class with streambuf().
The postconditions of this function are indicated in Table 137.
Table 137strstreambuf(streamsize) effects
Element
Value
strmode
dynamic
alsize
alsize_­arg
palloc
a null pointer
pfree
a null pointer
strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));
Effects: Constructs an object of class strstreambuf, initializing the base class with streambuf().
The postconditions of this function are indicated in Table 138.
Table 138strstreambuf(void* (*)(size_­t), void (*)(void*)) effects
Element
Value
strmode
dynamic
alsize
an unspecified value
palloc
palloc_­arg
pfree
pfree_­arg
strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = nullptr); strstreambuf(signed char* gnext_arg, streamsize n, signed char* pbeg_arg = nullptr); strstreambuf(unsigned char* gnext_arg, streamsize n, unsigned char* pbeg_arg = nullptr);
Effects: Constructs an object of class strstreambuf, initializing the base class with streambuf().
The postconditions of this function are indicated in Table 139.
Table 139strstreambuf(charT*, streamsize, charT*) effects
Element
Value
strmode
0
alsize
an unspecified value
palloc
a null pointer
pfree
a null pointer
gnext_­arg shall point to the first element of an array object whose number of elements N is determined as follows:
If pbeg_­arg is a null pointer, the function executes:
setg(gnext_arg, gnext_arg, gnext_arg + N);
Otherwise, the function executes:
setg(gnext_arg, gnext_arg, pbeg_arg);
setp(pbeg_arg,  pbeg_arg + N);
strstreambuf(const char* gnext_arg, streamsize n); strstreambuf(const signed char* gnext_arg, streamsize n); strstreambuf(const unsigned char* gnext_arg, streamsize n);
Effects: Behaves the same as strstreambuf((char*)gnext_­arg,n), except that the constructor also sets constant in strmode.
virtual ~strstreambuf();
Effects: Destroys an object of class strstreambuf.
The function frees the dynamically allocated array object only if (strmode & allocated) != 0 and (strmode & frozen) == 0.
([depr.strstreambuf.virtuals] describes how a dynamically allocated array object is freed.)
The function signature strlen(const char*) is declared in <cstring>.
The macro INT_­MAX is defined in <climits>.

D.8.2.2 Member functions [depr.strstreambuf.members]

void freeze(bool freezefl = true);
Effects: If strmode & dynamic is nonzero, alters the freeze status of the dynamic array object as follows:
  • If freezefl is true, the function sets frozen in strmode.
  • Otherwise, it clears frozen in strmode.
char* str();
Effects: Calls freeze(), then returns the beginning pointer for the input sequence, gbeg.
Remarks: The return value can be a null pointer.
int pcount() const;
Effects: If the next pointer for the output sequence, pnext, is a null pointer, returns zero.
Otherwise, returns the current effective length of the array object as the next pointer minus the beginning pointer for the output sequence, pnext - pbeg.

D.8.2.3 strstreambuf overridden virtual functions [depr.strstreambuf.virtuals]

int_type overflow(int_type c = EOF) override;
Effects: Appends the character designated by c to the output sequence, if possible, in one of two ways:
  • If c != EOF and if either the output sequence has a write position available or the function makes a write position available (as described below), assigns c to *pnext++.
    Returns (unsigned char)c.
  • If c == EOF, there is no character to append.
    Returns a value other than EOF.
Returns EOF to indicate failure.
Remarks: The function can alter the number of write positions available as a result of any call.
To make a write position available, the function reallocates (or initially allocates) an array object with a sufficient number of elements n to hold the current array object (if any), plus at least one additional write position.
How many additional write positions are made available is otherwise unspecified.
333 If palloc is not a null pointer, the function calls (*palloc)(n) to allocate the new dynamic array object.
Otherwise, it evaluates the expression new charT[n].
In either case, if the allocation fails, the function returns EOF.
Otherwise, it sets allocated in strmode.
To free a previously existing dynamic array object whose first element address is p: If pfree is not a null pointer, the function calls (*pfree)(p).
Otherwise, it evaluates the expression delete[]p.
If (strmode & dynamic) == 0, or if (strmode & frozen) != 0, the function cannot extend the array (reallocate it with greater length) to make a write position available.
int_type pbackfail(int_type c = EOF) override;
Puts back the character designated by c to the input sequence, if possible, in one of three ways:
  • If c != EOF, if the input sequence has a putback position available, and if (char)c == gnext[-1], assigns gnext - 1 to gnext.
    Returns c.
  • If c != EOF, if the input sequence has a putback position available, and if strmode & constant is zero, assigns c to *--gnext.
    Returns c.
  • If c == EOF and if the input sequence has a putback position available, assigns gnext - 1 to gnext.
    Returns a value other than EOF.
Returns EOF to indicate failure.
Remarks: If the function can succeed in more than one of these ways, it is unspecified which way is chosen.
The function can alter the number of putback positions available as a result of any call.
int_type underflow() override;
Effects: Reads a character from the input sequence, if possible, without moving the stream position past it, as follows:
  • If the input sequence has a read position available, the function signals success by returning (unsigned char)*gnext.
  • Otherwise, if the current write next pointer pnext is not a null pointer and is greater than the current read end pointer gend, makes a read position available by assigning to gend a value greater than gnext and no greater than pnext.
    Returns (unsigned char)*gnext.
Returns EOF to indicate failure.
Remarks: The function can alter the number of read positions available as a result of any call.
pos_type seekoff(off_type off, seekdir way, openmode which = in | out) override;
Effects: Alters the stream position within one of the controlled sequences, if possible, as indicated in Table 140.
Table 140seekoff positioning
Conditions
Result
(which & ios::in) != 0
positions the input sequence
(which & ios::out) != 0
positions the output sequence
(which & (ios::in |
ios::out)) == (ios::in |
ios::out)) and
way == either
ios::beg or
ios::end
positions both the input and the output sequences
Otherwise
the positioning operation fails.
For a sequence to be positioned, if its next pointer is a null pointer, the positioning operation fails.
Otherwise, the function determines newoff as indicated in Table 141.
Table 141newoff values
Condition
newoff Value
way == ios::beg
0
way == ios::cur
the next pointer minus the beginning pointer (xnext - xbeg).
way == ios::end
seekhigh minus the beginning pointer (seekhigh - xbeg).
If (newoff + off) < (seeklow - xbeg) or (seekhigh - xbeg) < (newoff + off), the positioning operation fails.
Otherwise, the function assigns xbeg + newoff + off to the next pointer xnext.
Returns: pos_­type(newoff), constructed from the resultant offset newoff (of type off_­type), that stores the resultant stream position, if possible.
If the positioning operation fails, or if the constructed object cannot represent the resultant stream position, the return value is pos_­type(off_­type(-1)).
pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override;
Effects: Alters the stream position within one of the controlled sequences, if possible, to correspond to the stream position stored in sp (as described below).
  • If (which & ios::in) != 0, positions the input sequence.
  • If (which & ios::out) != 0, positions the output sequence.
  • If the function positions neither sequence, the positioning operation fails.
For a sequence to be positioned, if its next pointer is a null pointer, the positioning operation fails.
Otherwise, the function determines newoff from sp.offset():
  • If newoff is an invalid stream position, has a negative value, or has a value greater than (seekhigh - seeklow), the positioning operation fails
  • Otherwise, the function adds newoff to the beginning pointer xbeg and stores the result in the next pointer xnext.
Returns: pos_­type(newoff), constructed from the resultant offset newoff (of type off_­type), that stores the resultant stream position, if possible.
If the positioning operation fails, or if the constructed object cannot represent the resultant stream position, the return value is pos_­type(off_­type(-1)).
streambuf<char>* setbuf(char* s, streamsize n) override;
Effects: Implementation defined, except that setbuf(0, 0) has no effect.
An implementation should consider alsize in making this decision.

D.8.3 Class istrstream [depr.istrstream]

namespace std {
  class istrstream : public basic_istream<char> {
  public:
    explicit istrstream(const char* s);
    explicit istrstream(char* s);
    istrstream(const char* s, streamsize n);
    istrstream(char* s, streamsize n);
    virtual ~istrstream();

    strstreambuf* rdbuf() const;
    char* str();
  private:
    strstreambuf sb;  // exposition only
  };
}
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:
  • sb, the strstreambuf object.

D.8.3.1 istrstream constructors [depr.istrstream.cons]

explicit istrstream(const char* s); explicit istrstream(char* s);
Effects: Constructs an object of class istrstream, initializing the base class with istream(&sb) and initializing sb with strstreambuf(s,0).
s shall designate the first element of an ntbs.
istrstream(const char* s, streamsize n); istrstream(char* s, streamsize n);
Effects: Constructs an object of class istrstream, initializing the base class with istream(&sb) and initializing sb with strstreambuf(s,n).
s shall designate the first element of an array whose length is n elements, and n shall be greater than zero.

D.8.3.2 Member functions [depr.istrstream.members]

strstreambuf* rdbuf() const;
Returns: const_­cast<strstreambuf*>(&sb).
char* str();
Returns: rdbuf()->str().

D.8.4 Class ostrstream [depr.ostrstream]

namespace std {
  class ostrstream : public basic_ostream<char> {
  public:
    ostrstream();
    ostrstream(char* s, int n, ios_base::openmode mode = ios_base::out);
    virtual ~ostrstream();

    strstreambuf* rdbuf() const;
    void freeze(bool freezefl = true);
    char* str();
    int pcount() const;
  private:
    strstreambuf sb;  // exposition only
  };
}
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:
  • sb, the strstreambuf object.

D.8.4.1 ostrstream constructors [depr.ostrstream.cons]

ostrstream();
Effects: Constructs an object of class ostrstream, initializing the base class with ostream(&sb) and initializing sb with strstreambuf().
ostrstream(char* s, int n, ios_base::openmode mode = ios_base::out);
Effects: Constructs an object of class ostrstream, initializing the base class with ostream(&sb), and initializing sb with one of two constructors:
  • If (mode & app) == 0, then s shall designate the first element of an array of n elements.
    The constructor is strstreambuf(s, n, s).
  • If (mode & app) != 0, then s shall designate the first element of an array of n elements that contains an ntbs whose first element is designated by s.
    The constructor is strstreambuf(s, n, s + std::strlen(s)).334
The function signature strlen(const char*) is declared in <cstring>.

D.8.4.2 Member functions [depr.ostrstream.members]

strstreambuf* rdbuf() const;
Returns: (strstreambuf*)&sb.
void freeze(bool freezefl = true);
Effects: Calls rdbuf()->freeze(freezefl).
char* str();
Returns: rdbuf()->str().
int pcount() const;
Returns: rdbuf()->pcount().

D.8.5 Class strstream [depr.strstream]

namespace std {
  class strstream
    : public basic_iostream<char> {
  public:
    // types
    using char_type = char;
    using int_type  = char_traits<char>::int_type;
    using pos_type  = char_traits<char>::pos_type;
    using off_type  = char_traits<char>::off_type;

    // constructors/destructor
    strstream();
    strstream(char* s, int n,
              ios_base::openmode mode = ios_base::in|ios_base::out);
    virtual ~strstream();

    // members
    strstreambuf* rdbuf() const;
    void freeze(bool freezefl = true);
    int pcount() const;
    char* str();

  private:
    strstreambuf sb;  // exposition only
  };
}
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:
  • sb, the strstreambuf object.

D.8.5.1 strstream constructors [depr.strstream.cons]

strstream();
Effects: Constructs an object of class strstream, initializing the base class with iostream(&sb).
strstream(char* s, int n, ios_base::openmode mode = ios_base::in|ios_base::out);
Effects: Constructs an object of class strstream, initializing the base class with iostream(&sb) and initializing sb with one of the two constructors:
  • If (mode & app) == 0, then s shall designate the first element of an array of n elements.
    The constructor is strstreambuf(s,n,s).
  • If (mode & app) != 0, then s shall designate the first element of an array of n elements that contains an ntbs whose first element is designated by s.
    The constructor is strstreambuf(s,n,s + std::strlen(s)).

D.8.5.2 strstream destructor [depr.strstream.dest]

virtual ~strstream();
Effects: Destroys an object of class strstream.

D.8.5.3 strstream operations [depr.strstream.oper]

strstreambuf* rdbuf() const;
Returns: &sb.
void freeze(bool freezefl = true);
Effects: Calls rdbuf()->freeze(freezefl).
char* str();
Returns: rdbuf()->str().
int pcount() const;
Returns: rdbuf()->pcount().

D.9 Deprecated type traits [depr.meta.types]

The header <type_­traits> has the following addition:
namespace std {
  template<class T> struct is_pod;
  template<class T> inline constexpr bool is_pod_v = is_pod<T>::value;
}
The behavior of a program that adds specializations for any of the templates defined in this subclause is undefined, unless explicitly permitted by the specification of the corresponding template.
template<class T> struct is_pod;
Requires: remove_­all_­extents_­t<T> shall be a complete type or cv void.
is_­pod<T> is a Cpp17UnaryTypeTrait ([meta.rqmts]) with a base characteristic of true_­type if T is a POD type, and false_­type otherwise.
A POD class is a class that is both a trivial class and a standard-layout class, and has no non-static data members of type non-POD class (or array thereof).
A POD type is a scalar type, a POD class, an array of such a type, or a cv-qualified version of one of these types.
[Note
:
It is unspecified whether a closure type ([expr.prim.lambda.closure]) is a POD type.
end note
]

D.10 Deprecated iterator primitives [depr.iterator.primitives]

D.10.1 Basic iterator [depr.iterator.basic]

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
]

D.11 Deprecated shared_­ptr atomic access [depr.util.smartptr.shared.atomic]

The header <memory> has the following additions:
namespace std {
  template<class T>
    bool atomic_is_lock_free(const shared_ptr<T>* p);

  template<class T>
    shared_ptr<T> atomic_load(const shared_ptr<T>* p);
  template<class T>
    shared_ptr<T> atomic_load_explicit(const shared_ptr<T>* p, memory_order mo);

  template<class T>
    void atomic_store(shared_ptr<T>* p, shared_ptr<T> r);
  template<class T>
    void atomic_store_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);

  template<class T>
    shared_ptr<T> atomic_exchange(shared_ptr<T>* p, shared_ptr<T> r);
  template<class T>
    shared_ptr<T> atomic_exchange_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);

  template<class T>
    bool atomic_compare_exchange_weak(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
  template<class T>
    bool atomic_compare_exchange_strong(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
  template<class T>
    bool atomic_compare_exchange_weak_explicit(
      shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w,
      memory_order success, memory_order failure);
  template<class T>
    bool atomic_compare_exchange_strong_explicit(
      shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w,
      memory_order success, memory_order failure);
}
Concurrent access to a shared_­ptr object from multiple threads does not introduce a data race if the access is done exclusively via the functions in this subclause and the instance is passed as their first argument.
The meaning of the arguments of type memory_­order is explained in [atomics.order].
template<class T> bool atomic_is_lock_free(const shared_ptr<T>* p);
Requires: p shall not be null.
Returns: true if atomic access to *p is lock-free, false otherwise.
Throws: Nothing.
template<class T> shared_ptr<T> atomic_load(const shared_ptr<T>* p);
Requires: p shall not be null.
Returns: atomic_­load_­explicit(p, memory_­order_­seq_­cst).
Throws: Nothing.
template<class T> shared_ptr<T> atomic_load_explicit(const shared_ptr<T>* p, memory_order mo);
Requires: p shall not be null.
Requires: mo shall not be memory_­order_­release or memory_­order_­acq_­rel.
Returns: *p.
Throws: Nothing.
template<class T> void atomic_store(shared_ptr<T>* p, shared_ptr<T> r);
Requires: p shall not be null.
Effects: As if by atomic_­store_­explicit(p, r, memory_­order_­seq_­cst).
Throws: Nothing.
template<class T> void atomic_store_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);
Requires: p shall not be null.
Requires: mo shall not be memory_­order_­acquire or memory_­order_­acq_­rel.
Effects: As if by p->swap(r).
Throws: Nothing.
template<class T> shared_ptr<T> atomic_exchange(shared_ptr<T>* p, shared_ptr<T> r);
Requires: p shall not be null.
Returns: atomic_­exchange_­explicit(p, r, memory_­order_­seq_­cst).
Throws: Nothing.
template<class T> shared_ptr<T> atomic_exchange_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);
Requires: p shall not be null.
Effects: As if by p->swap(r).
Returns: The previous value of *p.
Throws: Nothing.
template<class T> bool atomic_compare_exchange_weak(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
Requires: p shall not be null and v shall not be null.
Returns:
atomic_compare_exchange_weak_explicit(p, v, w, memory_order_seq_cst, memory_order_seq_cst)
Throws: Nothing.
template<class T> bool atomic_compare_exchange_strong(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
Returns:
atomic_compare_exchange_strong_explicit(p, v, w, memory_order_seq_cst, memory_order_seq_cst)
template<class T> bool atomic_compare_exchange_weak_explicit( shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w, memory_order success, memory_order failure); template<class T> bool atomic_compare_exchange_strong_explicit( shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w, memory_order success, memory_order failure);
Requires: p shall not be null and v shall not be null.
The failure argument shall not be memory_­order_­release nor memory_­order_­acq_­rel.
Effects: If *p is equivalent to *v, assigns w to *p and has synchronization semantics corresponding to the value of success, otherwise assigns *p to *v and has synchronization semantics corresponding to the value of failure.
Returns: true if *p was equivalent to *v, false otherwise.
Throws: Nothing.
Remarks: Two shared_­ptr objects are equivalent if they store the same pointer value and share ownership.
The weak form may fail spuriously.

D.12 Deprecated basic_­string capacity [depr.string.capacity]

The following member is declared in addition to those members specified in [string.capacity]:
namespace std {
  template<class charT, class traits = char_traits<charT>,
           class Allocator = allocator<charT>>
  class basic_string {
  public:
    void reserve();
  };
}
void reserve();
Effects: After this call, capacity() has an unspecified value greater than or equal to size().
[Note
:
This is a non-binding shrink to fit request.
end note
]

D.13 Deprecated standard code conversion facets [depr.locale.stdcvt]

The header <codecvt> provides code conversion facets for various character encodings.

D.13.1 Header <codecvt> synopsis [depr.codecvt.syn]

namespace std {
  enum codecvt_mode {
    consume_header = 4,
    generate_header = 2,
    little_endian = 1
  };

  template<class Elem, unsigned long Maxcode = 0x10ffff, codecvt_mode Mode = (codecvt_mode)0>
    class codecvt_utf8 : public codecvt<Elem, char, mbstate_t> {
    public:
      explicit codecvt_utf8(size_t refs = 0);
      ~codecvt_utf8();
    };

  template<class Elem, unsigned long Maxcode = 0x10ffff, codecvt_mode Mode = (codecvt_mode)0>
    class codecvt_utf16 : public codecvt<Elem, char, mbstate_t> {
    public:
      explicit codecvt_utf16(size_t refs = 0);
      ~codecvt_utf16();
    };

  template<class Elem, unsigned long Maxcode = 0x10ffff, codecvt_mode Mode = (codecvt_mode)0>
    class codecvt_utf8_utf16 : public codecvt<Elem, char, mbstate_t> {
    public:
      explicit codecvt_utf8_utf16(size_t refs = 0);
      ~codecvt_utf8_utf16();
    };
}

D.13.2 Requirements [depr.locale.stdcvt.req]

For each of the three code conversion facets codecvt_­utf8, codecvt_­utf16, and codecvt_­utf8_­utf16:
  • Elem is the wide-character type, such as wchar_­t, char16_­t, or char32_­t.
  • Maxcode is the largest wide-character code that the facet will read or write without reporting a conversion error.
  • 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.
  • 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.
  • 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:
  • The facet shall convert between UTF-8 multibyte sequences and UCS-2 or UTF-32 (depending on the size of Elem) within the program.
  • Endianness shall not affect how multibyte sequences are read or written.
  • The multibyte sequences may be written as either a text or a binary file.
For the facet codecvt_­utf16:
  • The facet shall convert between UTF-16 multibyte sequences and UCS-2 or UTF-32 (depending on the size of Elem) within the program.
  • Multibyte sequences shall be read or written according to the Mode flag, as set out above.
  • 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:
  • The facet shall convert between UTF-8 multibyte sequences and UTF-16 (one or two 16-bit codes) within the program.
  • Endianness shall not affect how multibyte sequences are read or written.
  • The multibyte sequences may be written as either a text or a binary file.
The encoding forms UTF-8, UTF-16, and UTF-32 are specified in ISO/IEC 10646.
The encoding form UCS-2 is specified in ISO/IEC 10646-1:1993.

D.14 Deprecated convenience conversion interfaces [depr.conversions]

The header <locale> has the following additions:
namespace std {
  template<class Codecvt, class Elem = wchar_t,
           class Wide_alloc = allocator<Elem>,
           class Byte_alloc = allocator<char>>
    class wstring_convert;

  template<class Codecvt, class Elem = wchar_t,
           class Tr = char_traits<Elem>>
    class wbuffer_convert;
}

D.14.1 Class template wstring_­convert [depr.conversions.string]

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;

      wstring_convert() : wstring_convert(new Codecvt) {}
      explicit wstring_convert(Codecvt* pcvt);
      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:
  • byte_­err_­string — a byte string to display on errors
  • wide_­err_­string — a wide string to display on errors
  • cvtptr — a pointer to the allocated conversion object (which is freed when the wstring_­convert object is destroyed)
  • cvtstate — a conversion state object
  • cvtcount — a conversion count
using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
The type shall be a synonym for basic_­string<char, char_­traits<char>, Byte_­alloc>.
size_t converted() const noexcept;
Returns: cvtcount.
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);
Effects: The first member function shall convert the single-element sequence byte to a wide string.
The second member function shall convert the null-terminated sequence beginning at ptr to a wide string.
The third member function shall convert the sequence stored in str to a wide string.
The fourth member function shall convert the sequence defined by the range [first, last) to a wide string.
In all cases:
  • If the cvtstate object was not constructed with an explicit value, it shall be set to its default value (the initial conversion state) before the conversion begins.
    Otherwise it shall be left unchanged.
  • The number of input elements successfully converted shall be stored in cvtcount.
Returns: If no conversion error occurs, the member function shall return the converted wide string.
Otherwise, if the object was constructed with a wide-error string, the member function shall return the wide-error string.
Otherwise, the member function throws an object of class range_­error.
using int_type = typename wide_string::traits_type::int_type;
The type shall be a synonym for wide_­string::traits_­type::int_­type.
state_type state() const;
returns cvtstate.
using state_type = typename Codecvt::state_type;
The type shall be a synonym for Codecvt::state_­type.
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);
Effects: The first member function shall convert the single-element sequence wchar to a byte string.
The second member function shall convert the null-terminated sequence beginning at wptr to a byte string.
The third member function shall convert the sequence stored in wstr to a byte string.
The fourth member function shall convert the sequence defined by the range [first, last) to a byte string.
In all cases:
  • If the cvtstate object was not constructed with an explicit value, it shall be set to its default value (the initial conversion state) before the conversion begins.
    Otherwise it shall be left unchanged.
  • The number of input elements successfully converted shall be stored in cvtcount.
Returns: If no conversion error occurs, the member function shall return the converted byte string.
Otherwise, if the object was constructed with a byte-error string, the member function shall return the byte-error string.
Otherwise, the member function shall throw an object of class range_­error.
using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
The type shall be a synonym for basic_­string<Elem, char_­traits<Elem>, Wide_­alloc>.
explicit wstring_convert(Codecvt* pcvt); wstring_convert(Codecvt* pcvt, state_type state); explicit wstring_convert(const byte_string& byte_err, const wide_string& wide_err = wide_string());
Requires: For the first and second constructors, pcvt != nullptr.
Effects: The first constructor shall store pcvt in cvtptr and default values in cvtstate, byte_­err_­string, and wide_­err_­string.
The second constructor shall store pcvt in cvtptr, state in cvtstate, and default values in byte_­err_­string and wide_­err_­string; moreover the stored state shall be retained between calls to from_­bytes and to_­bytes.
The third constructor shall store new Codecvt in cvtptr, state_­type() in cvtstate, byte_­err in byte_­err_­string, and wide_­err in wide_­err_­string.
~wstring_convert();
Effects: The destructor shall delete cvtptr.

D.14.2 Class template wbuffer_­convert [depr.conversions.buffer]

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;

      wbuffer_convert() : wbuffer_convert(nullptr) {}
      explicit wbuffer_convert(streambuf* bytebuf,
                               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 satisfy the requirements of the standard code-conversion facet codecvt<Elem, char, mbstate_­t>.
An object of this class template stores:
  • bufptr — a pointer to its underlying byte stream buffer
  • cvtptr — a pointer to the allocated conversion object (which is freed when the wbuffer_­convert object is destroyed)
  • cvtstate — a conversion state object
state_type state() const;
Returns: cvtstate.
streambuf* rdbuf() const;
Returns: bufptr.
streambuf* rdbuf(streambuf* bytebuf);
Effects: Stores bytebuf in bufptr.
Returns: The previous value of bufptr.
using state_type = typename Codecvt::state_type;
The type shall be a synonym for Codecvt::state_­type.
explicit wbuffer_convert( streambuf* bytebuf, Codecvt* pcvt = new Codecvt, state_type state = state_type());
Requires: pcvt != nullptr.
Effects: The constructor constructs a stream buffer object, initializes bufptr to bytebuf, initializes cvtptr to pcvt, and initializes cvtstate to state.
~wbuffer_convert();
Effects: The destructor shall delete cvtptr.