|
|
|
D.7.4.1
strstream constructors
[depr.strstream.cons]
strstream();
1
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);
2
Effects: Constructs an object of class strstream, initializing the base class with iostream(&sb) and
initializing sb with one of the two constructors:
(2.1)
—
If
(mode & app) == 0, then s shall designate the first element of an array of n elements. The
constructor is strstreambuf(s,n,s).
(2.2)
—
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.7.4.2
strstream destructor
[depr.strstream.dest]
virtual ~strstream();
1
Effects: Destroys an object of class strstream.
D.7.4.3
strstream operations
[depr.strstream.oper]
strstreambuf* rdbuf() const;
1
Returns: &sb.
void freeze(bool freezefl = true);
2
Effects: Calls rdbuf()->freeze(freezefl).
char* str();
3
Returns: rdbuf()->str().
int pcount() const;
4
Returns: rdbuf()->pcount().
D.8
uncaught_exception
[depr.uncaught]
1
The header <exception> has the following addition:
namespace std {
bool uncaught_exception() noexcept;
}
bool uncaught_exception() noexcept;
2
Returns: uncaught_exceptions() > 0.
D.9
Old adaptable function bindings
[depr.func.adaptor.binding]
D.9.1
Weak result types
[depr.weak.result_type]
1
A call wrapper (23.14.2) 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 (17.9.2), then
result_type shall be a synonym for T::result_type;
(1.4)
—
otherwise result_type shall not be defined.
§ D.9.1
1312
D.9.2
Typedefs to support function binders
[depr.func.adaptor.typedefs]
1
To enable old function adaptors to manipulate function objects that take one or two arguments, many of
the function objects in this document 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.
2
The following member names are defined in addition to names specified in
23.14:
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;
};
§ D.9.2
1313
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;
};
§ D.9.2
1314
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;
};
}
3
reference_wrapper<T> has a weak result type (D.9.1). If T is a function type, result_type shall be a
synonym for the return type of T.
4
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 (17.9.2); the type T1
is T::argument_type.
5
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 (17.9.2); the type T1 is T::first_argument_type and the type T2 is
T::second_argument_type.
6
All enabled specializations hash<Key> of hash (23.14.15) provide two nested types, result_type and
argument_type, which shall be synonyms for size_t and Key, respectively.
7
The forwarding call wrapper g returned by a call to bind(f, bound_args...) (23.14.11.3) shall have a
weak result type (D.9.1).
8
The forwarding call wrapper g returned by a call to bind<R>(f, bound_args...) (23.14.11.3) shall have a
nested type result_type defined as a synonym for R.
9
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.
10
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.
11
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.
§ D.9.2
1315
12
The following member names are defined in addition to names specified in Clause
26:
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;
};
}
D.9.3
Negators
[depr.negators]
1
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&);
}
2
Negators not1 and not2 take a unary and a binary predicate, respectively, and return their logical negations
(8.5.2.1).
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;
};
constexpr bool operator()(const typename Predicate::argument_type& x) const;
3
Returns: !pred(x).
template<class Predicate>
constexpr unary_negate<Predicate> not1(const Predicate& pred);
4
Returns: unary_negate<Predicate>(pred).
template<class Predicate>
class binary_negate {
public:
constexpr explicit binary_negate(const Predicate& pred);
constexpr bool operator()(const typename Predicate::first_argument_type& x,
const typename Predicate::second_argument_type& y)
const;
using first_argument_type
= typename Predicate::first_argument_type;
using second_argument_type = typename Predicate::second_argument_type;
using result_type
= bool;
};
§ D.9.3
1316
constexpr bool operator()(const typename Predicate::first_argument_type& x,
const typename Predicate::second_argument_type& y) const;
5
Returns: !pred(x,y).
template<class Predicate>
constexpr binary_negate<Predicate> not2(const Predicate& pred);
6
Returns: binary_negate<Predicate>(pred).
D.10
The default allocator
[depr.default.allocator]
1
The following members and explicit class template specialization are defined in addition to those specified in
23.10.10:
namespace std {
// specialization for void
template<> class allocator<void> {
public:
using value_type
= void;
using pointer
= void*;
using const_pointer = const void*;
// reference-to-void members are impossible.
template<class U> struct rebind { using other
=
allocator<U>;
};
};
template<class T> class allocator {
public:
using size_type
= size_t;
using difference_type = ptrdiff_t;
using pointer
= T*;
using const_pointer
= const T*;
using reference
= T&;
using const_reference = const T&;
template<class U> struct rebind { using other
=
allocator<U>;
};
T* address(T& x) const noexcept;
const T* address(const T& x) const noexcept;
T* allocate(size_t n, const void* hint);
template<class U, class... Args>
void construct(U* p, Args&&... args);
template<class U>
void destroy(U* p);
size_t max_size() const noexcept;
};
}
T* address(T& x) const noexcept;
const T* address(const T& x) const noexcept;
2
Returns: addressof(x).
T* allocate(size_t n, const void* hint);
3
Returns: A pointer to the initial element of an array of storage of
size
n *
sizeof(T), aligned
appropriately for objects of type T. It is implementation-defined whether over-aligned types are
supported (6.6.5).
4
Remarks: The storage is obtained by calling ::operator new(std::size_t) (21.6.2), but it is unspec-
ified when or how often this function is called.
5
Throws: bad_alloc if the storage cannot be obtained.
§ D.10
1317
template<class U, class... Args>
void construct(U* p, Args&&... args);
6
Effects: As if by: ::new((void *)p) U(std::forward<Args>(args)...);
template<class U>
void destroy(U* p);
7
Effects: As if by p->~U().
size_t max_size() const noexcept;
8
Returns: The largest value N for which the call allocate(N,
0) might succeed.
D.11
Raw storage iterator
[depr.storage.iterator]
1
The header <memory> has the following addition:
namespace std {
template<class OutputIterator, class T>
class raw_storage_iterator {
public:
using iterator_category = output_iterator_tag;
using value_type
= void;
using difference_type
= void;
using pointer
= void;
using reference
= void;
explicit raw_storage_iterator(OutputIterator x);
raw_storage_iterator& operator*();
raw_storage_iterator& operator=(const T& element);
raw_storage_iterator& operator=(T&& element);
raw_storage_iterator& operator++();
raw_storage_iterator operator++(int);
OutputIterator base() const;
};
}
2
raw_storage_iterator is provided to enable algorithms to store their results into uninitialized memory.
The template parameter OutputIterator is required to have its operator* return an object for which
operator& is defined and returns a pointer to T, and is also required to satisfy the requirements of an output
iterator (27.2.4).
explicit raw_storage_iterator(OutputIterator x);
3
Effects: Initializes the iterator to point to the same value to which x points.
raw_storage_iterator& operator*();
4
Returns: *this
raw_storage_iterator& operator=(const T& element);
5
Requires: T shall be CopyConstructible.
6
Effects: Constructs a value from element at the location to which the iterator points.
7
Returns: A reference to the iterator.
raw_storage_iterator& operator=(T&& element);
8
Requires: T shall be MoveConstructible.
9
Effects: Constructs a value from std::move(element) at the location to which the iterator points.
10
Returns: A reference to the iterator.
raw_storage_iterator& operator++();
11
Effects: Pre-increment: advances the iterator and returns a reference to the updated iterator.
§ D.11
1318
raw_storage_iterator operator++(int);
12
Effects: Post-increment: advances the iterator and returns the old value of the iterator.
OutputIterator base() const;
13
Returns: An iterator of type OutputIterator that points to the same value as *this points to.
D.12
Temporary buffers
[depr.temporary.buffer]
1
The header <memory> has the following additions:
namespace std {
template<class T>
pair<T*, ptrdiff_t> get_temporary_buffer(ptrdiff_t n) noexcept;
template<class T>
void return_temporary_buffer(T* p);
}
template<class T>
pair<T*, ptrdiff_t> get_temporary_buffer(ptrdiff_t n) noexcept;
2
Effects: Obtains a pointer to uninitialized, contiguous storage for N adjacent objects of type T, for some
non-negative number N . It is implementation-defined whether over-aligned types are supported (6.6.5).
3
Remarks: Calling get_temporary_buffer with a positive number n is a non-binding request to return
storage for n objects of type T. In this case, an implementation is permitted to return instead storage
for a non-negative number N of such objects, where N
!= n (including N
== 0). [ Note: The request
is non-binding to allow latitude for implementation-specific optimizations of its memory management.
— end note ]
4
Returns: If n <= 0 or if no storage could be obtained, returns a pair P such that P.first is a null
pointer value and P.second == 0; otherwise returns a pair P such that P.first refers to the address
of the uninitialized storage and P.second refers to its capacity N (in the units of sizeof(T)).
template<class T> void return_temporary_buffer(T* p);
5
Effects: Deallocates the storage referenced by p.
6
Requires: p shall be a pointer value returned by an earlier call to get_temporary_buffer that has not
been invalidated by an intervening call to return_temporary_buffer(T*).
7
Throws: Nothing.
D.13
Deprecated type traits
[depr.meta.types]
1
The header <type_traits> has the following addition:
namespace std {
template<class T> struct is_literal_type;
template<class T> constexpr bool is_literal_type_v = is_literal_type<T>::value;
template<class> struct result_of;
// not defined
template<class Fn, class... ArgTypes> struct result_of<Fn(ArgTypes...)>;
template<class T> using result_of_t = typename result_of<T>::type;
template<class T> struct is_pod;
template<class T> inline constexpr bool is_pod_v = is_pod<T>::value;
}
2
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_literal_type;
3
Requires: remove_all_extents_t<T> shall be a complete type or cv void.
4
is_literal_type<T> is a UnaryTypeTrait (23.15.1) with a base characteristic of true_type if T is a
literal type (6.7), and false_type otherwise.
§ D.13
1319
template<class Fn, class... ArgTypes> struct result_of<Fn(ArgTypes...)>;
5
Requires: Fn and all types in the parameter pack ArgTypes shall be complete types, cv void, or arrays
of unknown bound.
6
The partial specialization result_of<Fn(ArgTypes...)> is a TransformationTrait (23.15.1) whose
member typedef type is defined if and only if invoke_result<Fn, ArgTypes...>::type (23.14.4) is
defined. If type is defined, it names the same type as invoke_result_t<Fn, ArgTypes...>.
template<class T> struct is_pod;
7
Requires: remove_all_extents_t<T> shall be a complete type or cv void.
8
is_pod<T> is a UnaryTypeTrait (23.15.1) 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.
9
[ Note: It is unspecified whether a closure type (8.4.5.1) is a POD type.
— end note ]
D.14
Deprecated iterator primitives
[depr.iterator.primitives]
D.14.1
Basic iterator
[depr.iterator.basic]
1
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;
};
}
2
The iterator template may be used as a base class to ease the definition of required types for new iterators.
3
[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 ]
4
[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.15
Deprecated shared_ptr observers
[depr.util.smartptr.shared.obs]
1
The following member is defined in addition to those members specified in 23.11.3:
namespace std {
template<class T> class shared_ptr {
public:
bool unique() const noexcept;
};
}
bool unique() const noexcept;
2
Returns: use_count() == 1.
D.16
Deprecated shared_ptr atomic access
[depr.util.smartptr.shared.atomic]
1
The header <memory> has the following additions:
§ D.16
1320
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);
}
2
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.
3
The meaning of the arguments of type memory_order is explained in 32.4.
template<class T> bool atomic_is_lock_free(const shared_ptr<T>* p);
4
Requires: p shall not be null.
5
Returns: true if atomic access to *p is lock-free, false otherwise.
6
Throws: Nothing.
template<class T> shared_ptr<T> atomic_load(const shared_ptr<T>* p);
7
Requires: p shall not be null.
8
Returns: atomic_load_explicit(p, memory_order_seq_cst).
9
Throws: Nothing.
template<class T> shared_ptr<T> atomic_load_explicit(const shared_ptr<T>* p, memory_order mo);
10
Requires: p shall not be null.
11
Requires: mo shall not be memory_order_release or memory_order_acq_rel.
12
Returns: *p.
13
Throws: Nothing.
template<class T> void atomic_store(shared_ptr<T>* p, shared_ptr<T> r);
14
Requires: p shall not be null.
15
Effects: As if by atomic_store_explicit(p, r, memory_order_seq_cst).
16
Throws: Nothing.
§ D.16
1321
template<class T> void atomic_store_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);
17
Requires: p shall not be null.
18
Requires: mo shall not be memory_order_acquire or memory_order_acq_rel.
19
Effects: As if by p->swap(r).
20
Throws: Nothing.
template<class T> shared_ptr<T> atomic_exchange(shared_ptr<T>* p, shared_ptr<T> r);
21
Requires: p shall not be null.
22
Returns: atomic_exchange_explicit(p, r, memory_order_seq_cst).
23
Throws: Nothing.
template<class T>
shared_ptr<T> atomic_exchange_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);
24
Requires: p shall not be null.
25
Effects: As if by p->swap(r).
26
Returns: The previous value of *p.
27
Throws: Nothing.
template<class T>
bool atomic_compare_exchange_weak(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
28
Requires: p shall not be null and v shall not be null.
29
Returns:
atomic_compare_exchange_weak_explicit(p, v, w, memory_order_seq_cst, memory_order_seq_cst)
30
Throws: Nothing.
template<class T>
bool atomic_compare_exchange_strong(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);
31
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);
32
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.
33
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.
34
Returns: true if *p was equivalent to *v, false otherwise.
35
Throws: Nothing.
36
Remarks: Two shared_ptr objects are equivalent if they store the same pointer value and share
ownership. The weak form may fail spuriously. See 32.6.1.
D.17
Deprecated standard code conversion facets
[depr.locale.stdcvt]
1
The header <codecvt> provides code conversion facets for various character encodings.
§ D.17
1322
D.17.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.17.2
Requirements
[depr.locale.stdcvt.req]
1
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.
2
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.
3
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.
4
For the facet codecvt_utf8_utf16:
§ D.17.2
1323
(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.
D.18
Deprecated convenience conversion interfaces
[depr.conversions]
1
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.18.1
Class template wstring_convert
[depr.conversions.string]
1
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);
§ D.18.1
1324
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
};
}
2
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>.
3
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
using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
4
The type shall be a synonym for basic_string<char, char_traits<char>, Byte_alloc>.
size_t converted() const noexcept;
5
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);
6
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.
7
In all cases:
(7.1)
—
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.
(7.2)
—
The number of input elements successfully converted shall be stored in cvtcount.
8
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;
9
The type shall be a synonym for wide_string::traits_type::int_type.
state_type state() const;
10
returns cvtstate.
using state_type = typename Codecvt::state_type;
11
The type shall be a synonym for Codecvt::state_type.
§ D.18.1
1325
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);
12
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.
13
In all cases:
(13.1)
—
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.
(13.2)
—
The number of input elements successfully converted shall be stored in cvtcount.
14
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>;
15
The type shall be a synonym for basic_string<Elem, char_traits<Elem>, Wide_alloc>.
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());
16
Requires: For the first and second constructors, pcvt != nullptr.
17
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();
18
Effects: The destructor shall delete cvtptr.
D.18.2
Class template wbuffer_convert
[depr.conversions.buffer]
1
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 = nullptr,
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;
§ D.18.2
1326
private:
streambuf* bufptr;
// exposition only
Codecvt* cvtptr;
// exposition only
state_type cvtstate;
// exposition only
};
}
2
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>.
3
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
state_type state() const;
4
Returns: cvtstate.
streambuf* rdbuf() const;
5
Returns: bufptr.
streambuf* rdbuf(streambuf* bytebuf);
6
Effects: Stores bytebuf in bufptr.
7
Returns: The previous value of bufptr.
using state_type = typename Codecvt::state_type;
8
The type shall be a synonym for Codecvt::state_type.
explicit wbuffer_convert(
streambuf* bytebuf = nullptr,
Codecvt* pcvt = new Codecvt,
state_type state = state_type());
9
Requires: pcvt != nullptr.
10
Effects: The constructor constructs a stream buffer object, initializes bufptr to bytebuf, initializes
cvtptr to pcvt, and initializes cvtstate to state.
~wbuffer_convert();
11
Effects: The destructor shall delete cvtptr.
§ D.18.2
1327
Bibliography
The following documents are cited informatively in this document.
— ISO/IEC 10967-1:2012, Information technology — Language independent arithmetic — Part 1: Integer
and floating point arithmetic
— ISO 4217:2015, Codes for the representation of currencies
The arithmetic specification described in ISO/IEC 10967-1:2012 is called LIA-1 in this document.
Bibliography
1328
|
|