20 Library introduction [library]

20.4 Method of description (Informative) [description]

20.4.2 Other conventions [conventions]

1
#
This subclause describes several editorial conventions used to describe the contents of the C++ standard library.
These conventions are for describing implementation-defined types ([type.descriptions]), and member functions ([functions.within.classes]).

20.4.2.1 Type descriptions [type.descriptions]

20.4.2.1.1 General [type.descriptions.general]

1
#
The Requirements subclauses may describe names that are used to specify constraints on template arguments.160
These names are used in library Clauses to describe the types that may be supplied as arguments by a C++ program when instantiating template components from the library.
2
#
Certain types defined in Clause [input.output] are used to describe implementation-defined types.
They are based on other types, but with added constraints.
160)
Examples from [utility.requirements] include: EqualityComparable, LessThanComparable, CopyConstructible.
Examples from [iterator.requirements] include: InputIterator, ForwardIterator.

20.4.2.1.2 Exposition-only types [expos.only.types]

1
#
Several types defined in Clauses [language.support] through [thread] and Annex [depr] that are used as function parameter or return types are defined for the purpose of exposition only in order to capture their language linkage.
The declarations of such types are followed by a comment ending in exposition only.
[ Example
: 
namespace std {
  extern "C" using some-handler = int(int, void*, double);  // exposition only
}
The type placeholder some-handler can now be used to specify a function that takes a callback parameter with C language linkage.
— end example
 ]

20.4.2.1.3 Enumerated types [enumerated.types]

1
#
Several types defined in Clause [input.output] are enumerated types.
Each enumerated type may be implemented as an enumeration or as a synonym for an enumeration.161
2
#
The enumerated type enumerated can be written:
enum enumerated { , , , , ..... };

inline const ();
inline const ();
inline const ();
inline const ();
  .....
3
#
Here, the names , , etc.
 represent enumerated elements for this particular enumerated type.
All such elements have distinct values.
161)
Such as an integer type, with constant integer values ([basic.fundamental]).

20.4.2.1.4 Bitmask types [bitmask.types]

1
#
Several types defined in Clauses [language.support] through [thread] and Annex [depr] are bitmask types.
Each bitmask type can be implemented as an enumerated type that overloads certain operators, as an integer type, or as a bitset ([template.bitset]).
2
#
The bitmask type bitmask can be written:
// For exposition only.
// int_­type is an integral type capable of representing all values of the bitmask type.
enum bitmask : int_type {
   = 1 << 0,  = 1 << 1,  = 1 << 2,  = 1 << 3, .....
};

inline constexpr ();
inline constexpr ();
inline constexpr ();
inline constexpr ();
  .....

constexpr bitmask operator&(bitmask X, bitmask Y) {
  return static_cast<bitmask>(
    static_cast<int_type>(X) & static_cast<int_type>(Y));
}
constexpr bitmask operator|(bitmask X, bitmask Y) {
  return static_cast<bitmask>(
    static_cast<int_type>(X) | static_cast<int_type>(Y));
}
constexpr bitmask operator^(bitmask X, bitmask Y){
  return static_cast<bitmask>(
    static_cast<int_type>(X) ^ static_cast<int_type>(Y));
}
constexpr bitmask operator~(bitmask X){
  return static_cast<bitmask>(~static_cast<int_type>(X));
}
bitmask& operator&=(bitmask& X, bitmask Y){
  X = X & Y; return X;
}
bitmask& operator|=(bitmask& X, bitmask Y) {
  X = X | Y; return X;
}
bitmask& operator^=(bitmask& X, bitmask Y) {
  X = X ^ Y; return X;
}
3
#
Here, the names , , etc.
 represent bitmask elements for this particular bitmask type.
All such elements have distinct, nonzero values such that, for any pair and where , & is nonzero and & is zero.
Additionally, the value 0 is used to represent an empty bitmask, in which no bitmask elements are set.
4
#
The following terms apply to objects and values of bitmask types:
  • (4.1)
    To set a value Y in an object X is to evaluate the expression X |= Y.
  • (4.2)
    To clear a value Y in an object X is to evaluate the expression X &= ~Y.
  • (4.3)
    The value Y is set in the object X if the expression X & Y is nonzero.

20.4.2.1.5 Character sequences [character.seq]

1
#
The C standard library makes widespread use of characters and character sequences that follow a few uniform conventions:
  • (1.1)
    A letter is any of the 26 lowercase or 26 uppercase letters in the basic execution character set.
  • (1.2)
    The decimal-point character is the (single-byte) character used by functions that convert between a (single-byte) character sequence and a value of one of the floating-point types.
    It is used in the character sequence to denote the beginning of a fractional part.
    It is represented in Clauses [language.support] through [thread] and Annex [depr] by a period, '.', which is also its value in the "C" locale, but may change during program execution by a call to setlocale(int, const char*),162 or by a change to a locale object, as described in Clauses [locales] and [input.output].
  • (1.3)
    A character sequence is an array object ([dcl.array]) A that can be declared as T A[N], where T is any of the types char, unsigned char, or signed char ([basic.fundamental]), optionally qualified by any combination of const or volatile.
    The initial elements of the array have defined contents up to and including an element determined by some predicate.
    A character sequence can be designated by a pointer value S that points to its first element.
162)
declared in <clocale> ([c.locales]).

20.4.2.1.5.1 Byte strings [byte.strings]

1
#
A null-terminated byte string, or ntbs, is a character sequence whose highest-addressed element with defined content has the value zero (the terminating null character); no other element in the sequence has the value zero.
2
#
The length of an ntbs is the number of elements that precede the terminating null character.
An empty ntbs has a length of zero.
3
#
The value of an ntbs is the sequence of values of the elements up to and including the terminating null character.
4
#
A static ntbs is an ntbs with static storage duration.164
163)
Many of the objects manipulated by function signatures declared in <cstring> ([c.strings]) are character sequences or ntbss.
The size of some of these character sequences is limited by a length value, maintained separately from the character sequence.
164)
A string literal, such as "abc", is a static ntbs.

20.4.2.1.5.2 Multibyte strings [multibyte.strings]

1
#
A null-terminated multibyte string, or ntmbs, is an ntbs that constitutes a sequence of valid multibyte characters, beginning and ending in the initial shift state.165
2
#
A static ntmbs is an ntmbs with static storage duration.
165)
An ntbs that contains characters only from the basic execution character set is also an ntmbs.
Each multibyte character then consists of a single byte.

20.4.2.2 Functions within classes [functions.within.classes]

1
#
For the sake of exposition, Clauses [language.support] through [thread] and Annex [depr] do not describe copy/move constructors, assignment operators, or (non-virtual) destructors with the same apparent semantics as those that can be generated by default ([class.ctor], [class.dtor], [class.copy]).
It is unspecified whether the implementation provides explicit definitions for such member function signatures, or for virtual destructors that can be generated by default.
2
#
For the sake of exposition, the library clauses sometimes annotate constructors with EXPLICIT.
Such a constructor is conditionally declared as either explicit or non-explicit ([class.conv.ctor]).
[ Note
:
This is typically implemented by declaring two such constructors, of which at most one participates in overload resolution.
— end note
 ]

20.4.2.3 Private members [objects.within.classes]

1
#
Clauses [language.support] through [thread] and Annex [depr] do not specify the representation of classes, and intentionally omit specification of class members ([class.mem]).
An implementation may define static or non-static class members, or both, as needed to implement the semantics of the member functions specified in Clauses [language.support] through [thread] and Annex [depr].
2
#
For the sake of exposition, some subclauses provide representative declarations, and semantic requirements, for private members of classes that meet the external specifications of the classes.
The declarations for such members are followed by a comment that ends with exposition only, as in:
streambuf* sb;  // exposition only
3
#
An implementation may use any technique that provides equivalent observable behavior.