9 Classes [class]

A class definition introduces a new type. [ Example:

struct X { int a; };
struct Y { int a; };
X a1;
Y a2;
int a3;

declares three variables of three different types. This implies that

a1 = a2;                        // error: Y assigned to X
a1 = a3;                        // error: int assigned to X

are type mismatches, and that

int f(X);
int f(Y);

declare an overloaded (Clause [over]) function f() and not simply a single function f() twice. For the same reason,

struct S { int a; };
struct S { int a; };            // error, double definition

is ill-formed because it defines S twice.  — end example ]

A class declaration introduces the class name into the scope where it is declared and hides any class, variable, function, or other declaration of that name in an enclosing scope ([basic.scope]). If a class name is declared in a scope where a variable, function, or enumerator of the same name is also declared, then when both declarations are in scope, the class can be referred to only using an elaborated-type-specifier ([basic.lookup.elab]). [ Example:

struct stat {
  // ...
};

stat gstat;                     // use plain stat to
                                // define variable

int stat(struct stat*);         // redeclare stat as function

void f() {
  struct stat* ps;              // struct prefix needed
                                // to name struct stat
  stat(ps);                     // call stat()
}

 — end example ] A declaration consisting solely of class-key identifier; is either a redeclaration of the name in the current scope or a forward declaration of the identifier as a class name. It introduces the class name into the current scope. [ Example:

struct s { int a; };

void g() {
  struct s;                     // hide global struct s
                                // with a block-scope declaration
  s* p;                         // refer to local struct s
  struct s { char* p; };        // define local struct s
  struct s;                     // redeclaration, has no effect
}

 — end example ] [ Note: Such declarations allow definition of classes that refer to each other. [ Example:

class Vector;

class Matrix {
  // ...
  friend Vector operator*(const Matrix&, const Vector&);
};

class Vector {
  // ...
  friend Vector operator*(const Matrix&, const Vector&);
};

Declaration of friends is described in [class.friend], operator functions in [over.oper].  — end example ]  — end note ]

[ Note: An elaborated-type-specifier ([dcl.type.elab]) can also be used as a type-specifier as part of a declaration. It differs from a class declaration in that if a class of the elaborated name is in scope the elaborated name will refer to it.  — end note ] [ Example:

struct s { int a; };

void g(int s) {
  struct s* p = new struct s;   // global s
  p->a = s;                     // parameter s
}

 — end example ]

[ Note: The declaration of a class name takes effect immediately after the identifier is seen in the class definition or elaborated-type-specifier. For example,

class A * A;

first specifies A to be the name of a class and then redefines it as the name of a pointer to an object of that class. This means that the elaborated form class A must be used to refer to the class. Such artistry with names can be confusing and is best avoided.  — end note ]

A typedef-name ([dcl.typedef]) that names a class type, or a cv-qualified version thereof, is also a class-name. If a typedef-name that names a cv-qualified class type is used where a class-name is required, the cv-qualifiers are ignored. A typedef-name shall not be used as the identifier in a class-head.

The member-specification in a class definition declares the full set of members of the class; no member can be added elsewhere. Members of a class are data members, member functions ([class.mfct]), nested types, enumerators, and member templates ([temp.mem]) and specializations thereof. [ Note: A specialization of a static data member template is a static data member. A specialization of a member function template is a member function. A specialization of a member class template is a nested class.  — end note ]

A member-declaration does not declare new members of the class if it is

• (2.1)

  a friend declaration ([class.friend]),

• (2.2)

  a static_assert-declaration,

• (2.3)

  a using-declaration ([namespace.udecl]), or

• (2.4)

  an empty-declaration.

For any other member-declaration, each declared entity that is not an unnamed bit-field ([class.bit]) is a member of the class, and each such member-declaration shall either declare at least one member name of the class or declare at least one unnamed bit-field.

A data member is a non-function member introduced by a member-declarator. A member function is a member that is a function. Nested types are classes ([class.name], [class.nest]) and enumerations ([dcl.enum]) declared in the class and arbitrary types declared as members by use of a typedef declaration ([dcl.typedef]) or alias-declaration. The enumerators of an unscoped enumeration ([dcl.enum]) defined in the class are members of the class.

A data member or member function may be declared static in its member-declaration, in which case it is a static member (see [class.static]) (a static data member ([class.static.data]) or static member function ([class.static.mfct]), respectively) of the class. Any other data member or member function is a non-static member (a non-static data member or non-static member function ([class.mfct.non-static]), respectively). [ Note: A non-static data member of non-reference type is a member subobject of a class object ([intro.object]). — end note ]

A member shall not be declared twice in the member-specification, except that

• (5.1)

  a nested class or member class template can be declared and then later defined, and

• (5.2)

  an enumeration can be introduced with an opaque-enum-declaration and later redeclared with an enum-specifier.

[ Note: A single name can denote several member functions provided their types are sufficiently different (Clause [over]).  — end note ]

A class is considered a completely-defined object type ([basic.types]) (or complete type) at the closing } of the class-specifier. Within the class member-specification, the class is regarded as complete within function bodies, default arguments, noexcept-specifiers, and default member initializers (including such things in nested classes). Otherwise it is regarded as incomplete within its own class member-specification.

In a member-declarator, an = immediately following the declarator is interpreted as introducing a pure-specifier if the declarator-id has function type, otherwise it is interpreted as introducing a brace-or-equal-initializer. [ Example:

struct S {
  using T = void();
  T * p = 0;        // OK: brace-or-equal-initializer
  virtual T f = 0;  // OK: pure-specifier
};

 — end example ]

A brace-or-equal-initializer shall appear only in the declaration of a data member. (For static data members, see [class.static.data]; for non-static data members, see [class.base.init] and [dcl.init.aggr]). A brace-or-equal-initializer for a non-static data member specifies a default member initializer for the member, and shall not directly or indirectly cause the implicit definition of a defaulted default constructor for the enclosing class or the exception specification of that constructor.

A member shall not be declared with the extern storage-class-specifier. Within a class definition, a member shall not be declared with the thread_local storage-class-specifier unless also declared static.

The decl-specifier-seq may be omitted in constructor, destructor, and conversion function declarations only; when declaring another kind of member the decl-specifier-seq shall contain a type-specifier that is not a cv-qualifier. The member-declarator-list can be omitted only after a class-specifier or an enum-specifier or in a friend declaration ([class.friend]). A pure-specifier shall be used only in the declaration of a virtual function ([class.virtual]) that is not a friend declaration.

The optional attribute-specifier-seq in a member-declaration appertains to each of the entities declared by the member-declarators; it shall not appear if the optional member-declarator-list is omitted.

A virt-specifier-seq shall contain at most one of each virt-specifier. A virt-specifier-seq shall appear only in the declaration of a virtual member function ([class.virtual]).

Non-static data members shall not have incomplete types. In particular, a class C shall not contain a non-static member of class C, but it can contain a pointer or reference to an object of class C.

[ Note: See [expr.prim] for restrictions on the use of non-static data members and non-static member functions.  — end note ]

[ Note: The type of a non-static member function is an ordinary function type, and the type of a non-static data member is an ordinary object type. There are no special member function types or data member types.  — end note ]

[ Example: A simple example of a class definition is

struct tnode {
  char tword[20];
  int count;
  tnode* left;
  tnode* right;
};

which contains an array of twenty characters, an integer, and two pointers to objects of the same type. Once this definition has been given, the declaration

tnode s, *sp;

declares s to be a tnode and sp to be a pointer to a tnode. With these declarations, sp->count refers to the count member of the object to which sp points; s.left refers to the left subtree pointer of the object s; and s.right->tword[0] refers to the initial character of the tword member of the right subtree of s.  — end example ]

Non-static data members of a (non-union) class with the same access control (Clause [class.access]) are allocated so that later members have higher addresses within a class object. The order of allocation of non-static data members with different access control is unspecified (Clause [class.access]). Implementation alignment requirements might cause two adjacent members not to be allocated immediately after each other; so might requirements for space for managing virtual functions ([class.virtual]) and virtual base classes ([class.mi]).

If T is the name of a class, then each of the following shall have a name different from T:

• (18.1)

  every static data member of class T;

• (18.2)

  every member function of class T [ Note: This restriction does not apply to constructors, which do not have names ([class.ctor])  — end note ];

• (18.3)

  every member of class T that is itself a type;

• (18.4)

  every member template of class T;

• (18.5)

  every enumerator of every member of class T that is an unscoped enumerated type; and

• (18.6)

  every member of every anonymous union that is a member of class T.

In addition, if class T has a user-declared constructor ([class.ctor]), every non-static data member of class T shall have a name different from T.

The common initial sequence of two standard-layout struct (Clause [class]) types is the longest sequence of non-static data members and bit-fields in declaration order, starting with the first such entity in each of the structs, such that corresponding entities have layout-compatible types and either neither entity is a bit-field or both are bit-fields with the same width. [ Example:

  struct A { int a; char b; };
  struct B { const int b1; volatile char b2; };
  struct C { int c; unsigned : 0; char b; };
  struct D { int d; char b : 4; };
  struct E { unsigned int e; char b; };

The common initial sequence of A and B comprises all members of either class. The common initial sequence of A and C and of A and D comprises the first member in each case. The common initial sequence of A and E is empty.  — end example ]

Two standard-layout struct (Clause [class]) types are layout-compatible classes if their common initial sequence comprises all members and bit-fields of both classes ([basic.types]).

Two standard-layout unions are layout-compatible if they have the same number of non-static data members and corresponding non-static data members (in any order) have layout-compatible types ([basic.types]).

In a standard-layout union with an active member ([class.union]) of struct type T1, it is permitted to read a non-static data member m of another union member of struct type T2 provided m is part of the common initial sequence of T1 and T2; the behavior is as if the corresponding member of T1 were nominated. [ Example:

struct T1 { int a, b; };
struct T2 { int c; double d; };
union U { T1 t1; T2 t2; };
int f() {
  U u = { { 1, 2 } }; // active member is t1
  return u.t2.c;      // OK, as if u.t1.a were nominated
}

 — end example ] [ Note: Reading a volatile object through a non-volatile glvalue has undefined behavior ([dcl.type.cv]).  — end note ]

If a standard-layout class object has any non-static data members, its address is the same as the address of its first non-static data member. Otherwise, its address is the same as the address of its first base class subobject (if any). [ Note: There might therefore be unnamed padding within a standard-layout struct object, but not at its beginning, as necessary to achieve appropriate alignment.  — end note ] [ Note: The object and its first subobject are pointer-interconvertible ([basic.compound], [expr.static.cast]).  — end note ]

In a union, a non-static data member is active if its name refers to an object whose lifetime has begun and has not ended ([basic.life]). At most one of the non-static data members of an object of union type can be active at any time, that is, the value of at most one of the non-static data members can be stored in a union at any time. [ Note: One special guarantee is made in order to simplify the use of unions: If a standard-layout union contains several standard-layout structs that share a common initial sequence ([class.mem]), and if a non-static data member of an object of this standard-layout union type is active and is one of the standard-layout structs, it is permitted to inspect the common initial sequence of any of the standard-layout struct members; see [class.mem].  — end note ]

The size of a union is sufficient to contain the largest of its non-static data members. Each non-static data member is allocated as if it were the sole member of a struct. [ Note: A union object and its non-static data members are pointer-interconvertible ([basic.compound], [expr.static.cast]). As a consequence, all non-static data members of a union object have the same address.  — end note ]

A union can have member functions (including constructors and destructors), but it shall not have virtual ([class.virtual]) functions. A union shall not have base classes. A union shall not be used as a base class. If a union contains a non-static data member of reference type the program is ill-formed. [ Note: Absent default member initializers ([class.mem]), if any non-static data member of a union has a non-trivial default constructor ([class.ctor]), copy constructor ([class.copy]), move constructor ([class.copy]), copy assignment operator ([class.copy]), move assignment operator ([class.copy]), or destructor ([class.dtor]), the corresponding member function of the union must be user-provided or it will be implicitly deleted ([dcl.fct.def.delete]) for the union.  — end note ]

[ Example: Consider the following union:

union U {
  int i;
  float f;
  std::string s;
};

Since std::string ([string.classes]) declares non-trivial versions of all of the special member functions, U will have an implicitly deleted default constructor, copy/move constructor, copy/move assignment operator, and destructor. To use U, some or all of these member functions must be user-provided. — end example ]

When the left operand of an assignment operator involves a member access expression ([expr.ref]) that nominates a union member, it may begin the lifetime of that union member, as described below. For an expression E, define the set S(E) of subexpressions of E as follows:

• (5.1)

  If E is of the form A.B, S(E) contains the elements of S(A), and also contains A.B if B names a union member of a non-class, non-array type, or of a class type with a trivial default constructor that is not deleted, or an array of such types.

• (5.2)

  If E is of the form A[B] and is interpreted as a built-in array subscripting operator, S(E) is S(A) if A is of array type, S(B) if B is of array type, and empty otherwise.

• (5.3)

  Otherwise, S(E) is empty.

In an assignment expression of the form E1 = E2 that uses either the built-in assignment operator ([expr.ass]) or a trivial assignment operator ([class.copy]), for each element X of S(E1), if modification of X would have undefined behavior under [basic.life], an object of the type of X is implicitly created in the nominated storage; no initialization is performed and the beginning of its lifetime is sequenced after the value computation of the left and right operands and before the assignment. [ Note: This ends the lifetime of the previously-active member of the union, if any ([basic.life]).  — end note ] [ Example:

union A { int x; int y[4]; };
struct B { A a; };
union C { B b; int k; };
int f() {
  C c;               // does not start lifetime of any union member
  c.b.a.y[3] = 4;    // OK: S(c.b.a.y[3]) contains c.b and c.b.a.y;
                     // creates objects to hold union members c.b and c.b.a.y
  return c.b.a.y[3]; // OK: c.b.a.y refers to newly created object (see [basic.life])
}

struct X { const int a; int b; };
union Y { X x; int k; };
void g() {
  Y y = { { 1, 2 } }; // OK, y.x is active union member ([class.mem])
  int n = y.x.a;
  y.k = 4;   // OK: ends lifetime of y.x, y.k is active member of union
  y.x.b = n; // undefined behavior: y.x.b modified outside its lifetime,
             // S(y.x.b) is empty because X's default constructor is deleted,
             // so union member y.x's lifetime does not implicitly start
}

 — end example ]

[ Note: In general, one must use explicit destructor calls and placement new-expression to change the active member of a union.  — end note ] [ Example: Consider an object u of a union type U having non-static data members m of type M and n of type N. If M has a non-trivial destructor and N has a non-trivial constructor (for instance, if they declare or inherit virtual functions), the active member of u can be safely switched from m to n using the destructor and placement new-expression as follows:

u.m.~M();
new (&u.n) N;

 — end example ]

A class can be declared within a function definition; such a class is called a local class. The name of a local class is local to its enclosing scope. The local class is in the scope of the enclosing scope, and has the same access to names outside the function as does the enclosing function. Declarations in a local class shall not odr-use ([basic.def.odr]) a variable with automatic storage duration from an enclosing scope. [ Example:

int x;
void f() {
  static int s;
  int x;
  const int N = 5;
  extern int q();

  struct local {
    int g() { return x; }       // error: odr-use of automatic variable x
    int h() { return s; }       // OK
    int k() { return ::x; }     // OK
    int l() { return q(); }     // OK
    int m() { return N; }       // OK: not an odr-use
    int* n() { return &N; }     // error: odr-use of automatic variable N
  };
}

local* p = 0;                   // error: local not in scope

 — end example ]

An enclosing function has no special access to members of the local class; it obeys the usual access rules (Clause [class.access]). Member functions of a local class shall be defined within their class definition, if they are defined at all.

If class X is a local class a nested class Y may be declared in class X and later defined in the definition of class X or be later defined in the same scope as the definition of class X. A class nested within a local class is a local class.

A local class shall not have static data members.