______________________________________________________________________
7 Declarations [dcl.dcl]
______________________________________________________________________
1 Declarations specify how names are to be interpreted. Declarations
have the form
declaration-seq:
declaration
declaration-seq declaration
declaration:
block-declaration
function-definition
template-declaration
explicit-instantiation
explicit-specialization
linkage-specification
namespace-definition
block-declaration:
simple-declaration
asm-definition
namespace-alias-definition
using-declaration
using-directive
simple-declaration:
decl-specifier-seqopt init-declarator-listopt ;
[Note: asm-definitions are described in _dcl.asm_, and linkage-speci-
fications are described in _dcl.link_. Function-definitions are
described in _dcl.fct.def_ and template-declarations are described in
clause _temp_. Namespace-definitions are described in _names-
pace.def_, using-declarations are described in _namespace.udecl_ and
using-directives are described in _namespace.udir_. ] The simple-dec-
laration
decl-specifier-seqopt init-declarator-listopt ;
is divided into two parts: decl-specifiers, the components of a decl-
specifier-seq, are described in _dcl.spec_ and declarators, the compo-
nents of an init-declarator-list, are described in clause _dcl.decl_.
2 A declaration occurs in a scope (_basic.scope_); the scope rules are
summarized in _basic.lookup_. A declaration that declares a function
or defines a class, namespace, template, or function also has one or
more scopes nested within it. These nested scopes, in turn, can have
declarations nested within them. Unless otherwise stated, utterances
in clause _dcl.dcl_ about components in, of, or contained by a decla-
ration or subcomponent thereof refer only to those components of the
declaration that are not nested within scopes nested within the decla-
ration.
3 In a simple-declaration, the optional init-declarator-list can be
omitted only when declaring a class (clause _class_) or enumeration
(_dcl.enum_), that is, when the decl-specifier-seq contains either a
class-specifier, an elaborated-type-specifier with a class-key
(_class.name_), or an enum-specifier. In these cases and whenever a
class-specifier or enum-specifier is present in the decl-specifier-
seq, the identifiers in these specifiers are among the names being
declared by the declaration (as class-names, enum-names, or enumera-
tors, depending on the syntax). In such cases, and except for the
declaration of an unnamed bit-field (_class.bit_), the decl-specifier-
seq shall introduce one or more names into the program, or shall rede-
clare a name introduced by a previous declaration. [Example:
enum { }; // ill-formed
typedef class { }; // ill-formed
--end example]
4 Each init-declarator in the init-declarator-list contains exactly one
declarator-id, which is the name declared by that init-declarator and
hence one of the names declared by the declaration. The type-speci-
fiers (_dcl.type_) in the decl-specifier-seq and the recursive
declarator structure of the init-declarator describe a type
(_dcl.meaning_), which is then associated with the name being declared
by the init-declarator.
5 If the decl-specifier-seq contains the typedef specifier, the declara-
tion is called a typedef declaration and the name of each init-
declarator is declared to be a typedef-name, synonymous with its asso-
ciated type (_dcl.typedef_). If the decl-specifier-seq contains no
typedef specifier, the declaration is called a function declaration if
the type associated with the name is a function type (_dcl.fct_) and
an object declaration otherwise.
6 Syntactic components beyond those found in the general form of decla-
ration are added to a function declaration to make a function-defini-
tion. An object declaration, however, is also a definition unless it
contains the extern specifier and has no initializer (_basic.def_). A
definition causes the appropriate amount of storage to be reserved and
any appropriate initialization (_dcl.init_) to be done.
7 Only in function declarations for constructors, destructors, and type
conversions can the decl-specifier-seq be omitted.1)
7.1 Specifiers [dcl.spec]
1 The specifiers that can be used in a declaration are
decl-specifier:
storage-class-specifier
type-specifier
function-specifier
friend
typedef
_________________________
1) The "implicit int" rule of C is no longer supported.
decl-specifier-seq:
decl-specifier-seqopt decl-specifier
2 The longest sequence of decl-specifiers that could possibly be a type
name is taken as the decl-specifier-seq of a declaration. The
sequence shall be self-consistent as described below. [Example:
typedef char* Pc;
static Pc; // error: name missing
Here, the declaration static Pc is ill-formed because no name was
specified for the static variable of type Pc. To get a variable
called Pc, a type-specifier (other than const or volatile) has to be
present to indicate that the typedef-name Pc is the name being
(re)declared, rather than being part of the decl-specifier sequence.
For another example,
void f(const Pc); // void f(char* const) (not const char*)
void g(const int Pc); // void g(const int)
--end example]
3 [Note: since signed, unsigned, long, and short by default imply int, a
type-name appearing after one of those specifiers is treated as the
name being (re)declared. [Example:
void h(unsigned Pc); // void h(unsigned int)
void k(unsigned int Pc); // void k(unsigned int)
--end example] --end note]
7.1.1 Storage class specifiers [dcl.stc]
1 The storage class specifiers are
storage-class-specifier:
auto
register
static
extern
mutable
At most one storage-class-specifier shall appear in a given decl-spec-
ifier-seq. If a storage-class-specifier appears in a decl-specifier-
seq, there can be no typedef specifier in the same decl-specifier-seq
and the init-declarator-list of the declaration shall not be empty
(except for global anonymous unions, which shall be declared static
(_class.union_)). The storage-class-specifier applies to the name
declared by each init-declarator in the list and not to any names
declared by other specifiers. A storage-class-specifier shall not be
specified in an explicit specialization (_temp.expl.spec_) or an
explicit instantiation (_temp.explicit_) directive.
2 The auto or register specifiers can be applied only to names of
objects declared in a block (_stmt.block_) or to function parameters
(_dcl.fct.def_). They specify that the named object has automatic
storage duration (_basic.stc.auto_). An object declared without a
storage-class-specifier at block scope or declared as a function
parameter has automatic storage duration by default. [Note: hence,
the auto specifier is almost always redundant and not often used; one
use of auto is to distinguish a declaration-statement from an expres-
sion-statement (_stmt.ambig_) explicitly. --end note]
3 A register specifier has the same semantics as an auto specifier
together with a hint to the implementation that the object so declared
will be heavily used. [Note: the hint can be ignored and in most
implementations it will be ignored if the address of the object is
taken. --end note]
4 The static specifier can be applied only to names of objects and func-
tions and to anonymous unions (_class.union_). There can be no static
function declarations within a block, nor any static function parame-
ters. A static specifier used in the declaration of an object
declares the object to have static storage duration
(_basic.stc.static_). A static specifier can be used in declarations
of class members; _class.static_ describes its effect. For the link-
age of a name declared with a static specifier, see _basic.link_.
5 The extern specifier can be applied only to the names of objects and
functions. The extern specifier cannot be used in the declaration of
class members or function parameters. For the linkage of a name
declared with an extern specifier, see _basic.link_.
6 A name declared in a namespace scope without a storage-class-specifier
has external linkage unless it has internal linkage because of a pre-
vious declaration and provided it is not declared const. Objects
declared const and not explicitly declared extern have internal link-
age.
7 The linkages implied by successive declarations for a given entity
shall agree. That is, within a given scope, each declaration declar-
ing the same object name or the same overloading of a function name
shall imply the same linkage. Each function in a given set of over-
loaded functions can have a different linkage, however. [Example:
static char* f(); // f() has internal linkage
char* f() // f() still has internal linkage
{ /* ... */ }
char* g(); // g() has external linkage
static char* g() // error: inconsistent linkage
{ /* ... */ }
void h();
inline void h(); // external linkage
inline void l();
void l(); // external linkage
inline void m();
extern void m(); // external linkage
static void n();
inline void n(); // internal linkage
static int a; // a has internal linkage
int a; // error: two definitions
static int b; // b has internal linkage
extern int b; // b still has internal linkage
int c; // c has external linkage
static int c; // error: inconsistent linkage
extern int d; // d has external linkage
static int d; // error: inconsistent linkage
--end example]
8 The name of a declared but undefined class can be used in an extern
declaration. Such a declaration can only be used in ways that do not
require a complete class type. [Example:
struct S;
extern S a;
extern S f();
extern void g(S);
void h()
{
g(a); // error: S is incomplete
f(); // error: S is incomplete
}
--end example] The mutable specifier can be applied only to names of
class data members (_class.mem_) and cannot be applied to names
declared const or static, and cannot be applied to reference members.
[Example:
class X {
mutable const int* p; // OK
mutable int* const q; // ill-formed
};
--end example]
9 The mutable specifier on a class data member nullifies a const speci-
fier applied to the containing class object and permits modification
of the mutable class member even though the rest of the object is
const (_dcl.type.cv_).
7.1.2 Function specifiers [dcl.fct.spec]
1 Function-specifiers can be used only in function declarations.
function-specifier:
inline
virtual
explicit
2 A function declaration (_dcl.fct_, _class.mfct_, _class.friend_) with
an inline specifier declares an inline function. The inline specifier
indicates to the implementation that inline substitution of the func-
tion body at the point of call is to be preferred to the usual func-
tion call mechanism. An implementation is not required to perform
this inline substitution at the point of call; however, even if this
inline substitution is omitted, the other rules for inline functions
defined by _dcl.fct.spec_ shall still be respected.
3 A function defined within a class definition is an inline function.
The inline specifier shall not appear on a block scope function
declaration.2)
4 An inline function shall be defined in every translation unit in which
it is used and shall have exactly the same definition in every case
_________________________
2) The inline keyword has no effect on the linkage of a function.
(_basic.def.odr_). [Note: a call to the inline function may be
encountered before its definition appears in the translation unit. ]
If a function with external linkage is declared inline in one transla-
tion unit, it shall be declared inline in all translation units in
which it appears; no diagnostic is required. An inline function with
external linkage shall have the same address in all translation units.
[Note: a static local variable in an extern inline function always
refers to the same object. ]
5 The virtual specifier shall only be used in declarations of nonstatic
class member functions that appear within a member-specification of a
class declaration; see _class.virtual_.
6 The explicit specifier shall be used only in declarations of construc-
tors within a class declaration; see _class.conv.ctor_.
7.1.3 The typedef specifier [dcl.typedef]
1 Declarations containing the decl-specifier typedef declare identifiers
that can be used later for naming fundamental (_basic.fundamental_) or
compound (_basic.compound_) types. The typedef specifier shall not be
used in a function-definition (_dcl.fct.def_), and it shall not be
combined in a decl-specifier-seq with any other kind of specifier
except a type-specifier.
typedef-name:
identifier
A name declared with the typedef specifier becomes a typedef-name.
Within the scope of its declaration, a typedef-name is syntactically
equivalent to a keyword and names the type associated with the identi-
fier in the way described in clause _dcl.decl_. A typedef-name is
thus a synonym for another type. A typedef-name does not introduce a
new type the way a class declaration (_class.name_) or enum declara-
tion does. [Example: after
typedef int MILES, *KLICKSP;
the constructions
MILES distance;
extern KLICKSP metricp;
are all correct declarations; the type of distance is int; that of
metricp is "pointer to int." ]
2 In a given scope, a typedef specifier can be used to redefine the name
of any type declared in that scope to refer to the type to which it
already refers. [Example:
typedef struct s { /* ... */ } s;
typedef int I;
typedef int I;
typedef I I;
--end example]
3 In a given scope, a typedef specifier shall not be used to redefine
the name of any type declared in that scope to refer to a different
type. [Example:
class complex { /* ... */ };
typedef int complex; // error: redefinition
--end example] Similarly, in a given scope, a class or enumeration
shall not be declared with the same name as a typedef-name that is
declared in that scope and refers to a type other than the class or
enumeration itself. [Example:
typedef int complex;
class complex { /* ... */ }; // error: redefinition
--end example]
4 A typedef-name that names a class is a class-name (_class.name_). If
a typedef-name is used following the class-key in an elaborated-type-
specifier (_dcl.type.elab_) or in the class-head of a class declara-
tion (_class_), or is used as the identifier in the declarator for a
constructor or destructor declaration (_class.ctor_, _class.dtor_),
the program is ill-formed. [Example:
struct S {
S();
~S();
};
typedef struct S T;
S a = T(); // OK
struct T * p; // error
--end example]
5 If the typedef declaration defines an unnamed class (or enum), the
first typedef-name declared by the declaration to be that class type
(or enum type) is used to denote the class type (or enum type) for
linkage purposes only (_basic.link_). [Example:
typedef struct { } *ps, S; // S is the class name for linkage purposes
--end example] [Note: if the typedef-name is used where a class-name
(or enum-name) is required, the program is ill-formed. For example,
typedef struct {
S(); // error: requires a return type because S is
// an ordinary member function, not a constructor
} S;
--end note]
7.1.4 The friend specifier [dcl.friend]
1 The friend specifier is used to specify access to class members; see
_class.friend_.
7.1.5 Type specifiers [dcl.type]
1 The type-specifiers are
type-specifier:
simple-type-specifier
class-specifier
enum-specifier
elaborated-type-specifier
cv-qualifier
As a general rule, at most one type-specifier is allowed in the com-
plete decl-specifier-seq of a declaration. The only exceptions to
this rule are the following:
2
--const or volatile can be combined with any other type-specifier.
However, redundant cv-qualifiers are prohibited except when intro-
duced through the use of typedefs (_dcl.typedef_) or template type
arguments (_temp.arg_), in which case the redundant cv-qualifiers
are ignored.
--signed or unsigned can be combined with char, long, short, or int.
--short or long can be combined with int.
--long can be combined with double.
3 At least one type-specifier that is not a cv-qualifier is required in
a declaration unless it declares a constructor, destructor or conver-
sion function.3)
4 [Note: class-specifiers and enum-specifiers are discussed in clause
_class_ and _dcl.enum_, respectively. The remaining type-specifiers
are discussed in the rest of this section. ]
7.1.5.1 The cv-qualifiers [dcl.type.cv]
1 There are two cv-qualifiers, const and volatile. If a cv-qualifier
appears in a decl-specifier-seq, the init-declarator-list of the dec-
laration shall not be empty. [Note: _basic.type.qualifier_ describes
how cv-qualifiers affect object and function types. ]
2 An object declared in namespace scope with a const-qualified type has
internal linkage unless it is explicitly declared extern or unless it
was previously declared to have external linkage. A variable of
const-qualified integral or enumeration type initialized by an inte-
gral constant expression can be used in integral constant expressions
(_expr.const_). [Note: as described in _dcl.init_, the definition of
an object or subobject of const-qualified type must specify an ini-
tializer or be subject to default-initialization. ]
3 A pointer or reference to a cv-qualified type need not actually point
or refer to a cv-qualified object, but it is treated as if it does; a
const-qualified access path cannot be used to modify an object even if
the object referenced is a non-const object and can be modified
through some other access path. [Note: cv-qualifiers are supported by
the type system so that they cannot be subverted without casting
(_expr.const.cast_). ]
4 Except that any class member declared mutable (_dcl.stc_) can be modi-
fied, any attempt to modify a const object during its lifetime
_________________________
3) There is no special provision for a decl-specifier-seq that lacks a
type-specifier or that has a type-specifier that only specifies cv-
qualifiers. The "implicit int" rule of C is no longer supported.
(_basic.life_) results in undefined behavior.
5 [Example:
const int ci = 3; // cv-qualified (initialized as required)
ci = 4; // ill-formed: attempt to modify const
int i = 2; // not cv-qualified
const int* cip; // pointer to const int
cip = &i; // OK: cv-qualified access path to unqualified
*cip = 4; // ill-formed: attempt to modify through ptr to const
int* ip;
ip = const_cast<int*>(cip); // cast needed to convert const int* to int*
*ip = 4; // defined: *ip points to i, a non-const object
const int* ciq = new const int (3); // initialized as required
int* iq = const_cast<int*>(ciq); // cast required
*iq = 4; // undefined: modifies a const object
6 For another example
class X {
public:
mutable int i;
int j;
};
class Y {
public:
X x;
Y();
};
const Y y;
y.x.i++; // well-formed: mutable member can be modified
y.x.j++; // ill-formed: const-qualified member modified
Y* p = const_cast<Y*>(&y); // cast away const-ness of y
p->x.i = 99; // well-formed: mutable member can be modified
p->x.j = 99; // undefined: modifies a const member
--end example]
7 If an attempt is made to refer to an object defined with a volatile-
qualified type through the use of an lvalue with a non-volatile-quali-
fied type, the program behaviour is undefined.
8 [Note: volatile is a hint to the implementation to avoid aggressive
optimization involving the object because the value of the object
might be changed by means undetectable by an implementation. See
_intro.execution_ for detailed semantics. In general, the semantics
of volatile are intended to be the same in C++ as they are in C. ]
7.1.5.2 Simple type specifiers [dcl.type.simple]
1 The simple type specifiers are
simple-type-specifier:
::opt nested-name-specifieropt type-name
char
wchar_t
bool
short
int
long
signed
unsigned
float
double
void
type-name:
class-name
enum-name
typedef-name
The simple-type-specifiers specify either a previously-declared user-
defined type or one of the fundamental types (_basic.fundamental_).
Table 1 summarizes the valid combinations of simple-type-specifiers
and the types they specify.
Table 1--simple-type-specifiers and the types they specify
+-------------------+----------------------+
|Specifier(s) | Type |
+-------------------+----------------------+
|type-name | the type named |
|char | "char" |
|unsigned char | "unsigned char" |
|signed char | "signed char" |
|bool | "bool" |
|unsigned | "unsigned int" |
|unsigned int | "unsigned int" |
|signed | "int" |
|signed int | "int" |
|int | "int" |
|unsigned short int | "unsigned short int" |
|unsigned short | "unsigned short int" |
|unsigned long int | "unsigned long int" |
|unsigned long | "unsigned long int" |
|signed long int | "long int" |
|signed long | "long int" |
|long int | "long int" |
|long | "long int" |
|signed short int | "short int" |
|signed short | "short int" |
|short int | "short int" |
|short | "short int" |
|wchar_t | "wchar_t" |
|float | "float" |
|double | "double" |
|long double | "long double" |
|void | "void" |
+-------------------+----------------------+
When multiple simple-type-specifiers are allowed, they can be freely
intermixed with other decl-specifiers in any order. It is implementa-
tion-defined whether bit-fields and objects of char type are repre-
sented as signed or unsigned quantities. The signed specifier forces
char objects and bit-fields to be signed; it is redundant with other
integral types.
7.1.5.3 Elaborated type specifiers [dcl.type.elab]
1 elaborated-type-specifier:
class-key ::opt nested-name-specifieropt identifier
enum ::opt nested-name-specifieropt identifier
typename ::opt nested-name-specifier identifier
typename ::opt nested-name-specifier identifier < template-argument-list >
2 If an elaborated-type-specifier is the sole constituent of a declara-
tion, the declaration is ill-formed unless it is an explicit
specialization (_temp.expl.spec_), an explicit instantiation
(_temp.explicit_) or it has one of the following forms:
class-key identifier ;
friend class-key identifier ;
friend class-key ::identifier ;
friend class-key nested-name-specifier identifier ;
3 _basic.lookup.elab_ describes how name look up proceeds for the iden-
tifier in an elaborated-type-specifier. If the identifier resolves to
a class-name or enum-name, the elaborated-type-specifier introduces it
into the declaration the same way a simple-type-specifier introduces
its type-name. If the identifier resolves to a typedef-name or a tem-
plate type-parameter, the elaborated-type-specifier is ill-formed.
[Note: this implies that, within a class template with a template
type-parameter T, the declaration
friend class T;
is ill-formed. ] If name look up does not find a declaration for the
name, the elaborated-type-specifier is ill-formed unless it is of the
simple form class-key identifier in which case the identifier is
declared as described in _basic.scope.pdecl_.
4 The class-key or enum keyword present in the elaborated-type-specifier
shall agree in kind with the declaration to which the name in the
elaborated-type-specifier refers. This rule also applies to the form
of elaborated-type-specifier that declares a class-name or friend
class since it can be construed as referring to the definition of the
class. Thus, in any elaborated-type-specifier, the enum keyword shall
be used to refer to an enumeration (_dcl.enum_), the union class-key
shall be used to refer to a union (clause _class_), and either the
class or struct class-key shall be used to refer to a class (clause
_class_) declared using the class or struct class-key.
7.2 Enumeration declarations [dcl.enum]
1 An enumeration is a distinct type (_basic.fundamental_) with named
constants. Its name becomes an enum-name, within its scope.
enum-name:
identifier
enum-specifier:
enum identifieropt { enumerator-listopt }
enumerator-list:
enumerator-definition
enumerator-list , enumerator-definition
enumerator-definition:
enumerator
enumerator = constant-expression
enumerator:
identifier
The identifiers in an enumerator-list are declared as constants, and
can appear wherever constants are required. An enumerator-definition
with = gives the associated enumerator the value indicated by the con-
stant-expression. The constant-expression shall be of integral or
enumeration type. If the first enumerator has no initializer, the
value of the corresponding constant is zero. An enumerator-definition
without an initializer gives the enumerator the value obtained by
increasing the value of the previous enumerator by one.
2 [Example:
enum { a, b, c=0 };
enum { d, e, f=e+2 };
defines a, c, and d to be zero, b and e to be 1, and f to be 3. ]
3 The point of declaration for an enumerator is immediately after its
enumerator-definition. [Example:
const int x = 12;
{ enum { x = x }; }
Here, the enumerator x is initialized with the value of the constant
x, namely 12. ]
4 Each enumeration defines a type that is different from all other
types. Following the closing brace of an enum-specifier, each enumer-
ator has the type of its enumeration. Prior to the closing brace, the
type of each enumerator is the type of its initializing value. If an
initializer is specified for an enumerator, the initializing value has
the same type as the expression. If no initializer is specified for
the first enumerator, the type is an unspecified integral type. Oth-
erwise the type is the same as the type of the initializing value of
the preceding enumerator unless the incremented value is not repre-
sentable in that type, in which case the type is an unspecified inte-
gral type sufficient to contain the incremented value.
5 The underlying type of an enumeration is an integral type that can
represent all the enumerator values defined in the enumeration. It is
implementation-defined which integral type is used as the underlying
type for an enumeration except that the underlying type shall not be
larger than int unless the value of an enumerator cannot fit in an int
or unsigned int. If the enumerator-list is empty, the underlying type
is as if the enumeration had a single enumerator with value 0. The
value of sizeof() applied to an enumeration type, an object of enumer-
ation type, or an enumerator, is the value of sizeof() applied to the
underlying type.
6 For an enumeration where emin is the smallest enumerator and emax is
the largest, the values of the enumeration are the values of the
underlying type in the range bmin to bmax, where bmin and bmax are,
respectively, the smallest and largest values of the smallest bit-
field that can store emin and emax.4) It is possible to define an enu-
meration that has values not defined by any of its enumerators.
7 Two enumeration types are layout-compatible if they have the same
underlying type.
_________________________
4) On a two's-complement machine, bmax is the smallest value greater
than or equal to max(abs(emin)-1,abs(emax)) of the form 2M-1; bmin is
zero if emin is non-negative and -(bmax+1) otherwise.
8 The value of an enumerator or an object of an enumeration type is con-
verted to an integer by integral promotion (_conv.prom_). [Example:
enum color { red, yellow, green=20, blue };
color col = red;
color* cp = &col;
if (*cp == blue) // ...
makes color a type describing various colors, and then declares col as
an object of that type, and cp as a pointer to an object of that type.
The possible values of an object of type color are red, yellow, green,
blue; these values can be converted to the integral values 0, 1, 20,
and 21. Since enumerations are distinct types, objects of type color
can be assigned only values of type color.
color c = 1; // error: type mismatch,
// no conversion from int to color
int i = yellow; // OK: yellow converted to integral value 1
// integral promotion
--end example]
9 An expression of arithmetic or enumeration type can be converted to an
enumeration type explicitly. The value is unchanged if it is in the
range of enumeration values of the enumeration type; otherwise the
resulting enumeration value is unspecified.
10The enum-name and each enumerator declared by an enum-specifier is
declared in the scope that immediately contains the enum-specifier.
These names obey the scope rules defined for all names in
(_basic.scope_) and (_basic.lookup_). An enumerator declared in class
scope can be referred to using the class member access operators ::, .
(dot) and -> (arrow)), see _expr.ref_. [Example:
class X {
public:
enum direction { left='l', right='r' };
int f(int i)
{ return i==left ? 0 : i==right ? 1 : 2; }
};
void g(X* p)
{
direction d; // error: direction not in scope
int i;
i = p->f(left); // error: left not in scope
i = p->f(X::right); // OK
i = p->f(p->left); // OK
// ...
}
--end example]
7.3 Namespaces [basic.namespace]
1 A namespace is an optionally-named declarative region. The name of a
namespace can be used to access entities declared in that namespace;
that is, the members of the namespace. Unlike other declarative
regions, the definition of a namespace can be split over several parts
of one or more translation units.
2 A name declared outside all named namespaces, blocks (_stmt.block_)
and classes (clause _class_) has global namespace scope
(_basic.scope.namespace_).
7.3.1 Namespace definition [namespace.def]
1 The grammar for a namespace-definition is
namespace-name:
original-namespace-name
namespace-alias
original-namespace-name:
identifier
namespace-definition:
named-namespace-definition
unnamed-namespace-definition
named-namespace-definition:
original-namespace-definition
extension-namespace-definition
original-namespace-definition:
namespace identifier { namespace-body }
extension-namespace-definition:
namespace original-namespace-name { namespace-body }
unnamed-namespace-definition:
namespace { namespace-body }
namespace-body:
declaration-seqopt
2 The identifier in an original-namespace-definition shall not have been
previously defined in the declarative region in which the original-
namespace-definition appears. The identifier in an original-names-
pace-definition is the name of the namespace. Subsequently in that
declarative region, it is treated as an original-namespace-name.
3 The original-namespace-name in an extension-namespace-definition shall
have previously been defined in an original-namespace-definition in
the same declarative region.
4 Every namespace-definition shall appear in the global scope or in a
namespace scope (_basic.scope.namespace_).
5 Because a namespace-definition contains declarations in its namespace-
body and a namespace-definition is itself a declaration, it follows
that namespace-definitions can be nested. [Example:
namespace Outer {
int i;
namespace Inner {
void f() { i++; } // Outer::i
int i;
void g() { i++; } // Inner::i
}
}
--end example]
7.3.1.1 Unnamed namespaces [namespace.unnamed]
1 An unnamed-namespace-definition behaves as if it were replaced by
namespace unique { /* empty body */ }
using namespace unique;
namespace unique { namespace-body }
where all occurrences of unique in a translation unit are replaced by
the same identifier and this identifier differs from all other identi-
fiers in the entire program.5) [Example:
namespace { int i; } // unique::i
void f() { i++; } // unique::i++
namespace A {
namespace {
int i; // A::unique::i
int j; // A::unique::j
}
void g() { i++; } // A::unique::i++
}
using namespace A;
void h() {
i++; // error: unique::i or A::unique::i
A::i++; // A::unique::i
j++; // A::unique::j
}
--end example]
2 The use of the static keyword is deprecated when declaring objects in
a namespace scope (see annex _depr_); the unnamed-namespace provides a
superior alternative.
7.3.1.2 Namespace member definitions [namespace.memdef]
1 Members of a namespace can be defined within that namespace. [Exam-
ple:
namespace X {
void f() { /* ... */ }
}
_________________________
5) Although entities in an unnamed namespace might have external link-
age, they are effectively qualified by a name unique to their transla-
tion unit and therefore can never be seen from any other translation
unit.
--end example]
2 Members of a named namespace can also be defined outside that names-
pace by explicit qualification (_namespace.qual_) of the name being
defined, provided that the entity being defined was already declared
in the namespace and the definition appears after the point of decla-
ration in a namespace that encloses the declaration's namespace.
[Example:
namespace Q {
namespace V {
void f();
}
void V::f() { /* ... */ } // OK
void V::g() { /* ... */ } // error: g() is not yet a member of V
namespace V {
void g();
}
}
namespace R {
void Q::V::g() { /* ... */ } // error: R doesn't enclose Q
}
--end example]
3 Every name first declared in a namespace is a member of that names-
pace. If a friend declaration in a non-local class first declares a
class or function6) the friend class or function is a member of the
innermost enclosing namespace. The name of the friend is not found by
simple name lookup until a matching declaration is provided in that
namespace scope (either before or after the class declaration granting
friendship). If a friend function is called, its name may be found by
the name lookup that considers functions from namespaces and classes
associated with the types of the function arguments
(_basic.lookup.koenig_). When looking for a prior declaration of a
class or a function declared as a friend, scopes outside the innermost
enclosing namespace scope are not considered. [Example:
_________________________
6) this implies that the name of the class or function is unqualified.
// Assume f and g have not yet been defined.
void h(int);
namespace A {
class X {
friend void f(X); // A::f is a friend
class Y {
friend void g(); // A::g is a friend
friend void h(int); // A::h is a friend
// ::h not considered
};
};
// A::f, A::g and A::h are not visible here
X x;
void g() { f(x); } // definition of A::g
void f(X) { /* ... */} // definition of A::f
void h(int) { /* ... */ } // definition of A::h
// A::f, A::g and A::h are visible here and known to be friends
}
using A::x;
void h()
{
A::f(x);
A::X::f(x); // error: f is not a member of A::X
A::X::Y::g(); // error: g is not a member of A::X::Y
}
--end example]
7.3.2 Namespace alias [namespace.alias]
1 A namespace-alias-definition declares an alternate name for a names-
pace according to the following grammar:
namespace-alias:
identifier
namespace-alias-definition:
namespace identifier = qualified-namespace-specifier ;
qualified-namespace-specifier:
::opt nested-name-specifieropt namespace-name
2 The identifier in a namespace-alias-definition is a synonym for the
name of the namespace denoted by the qualified-namespace-specifier and
becomes a namespace-alias. [Note: when looking up a namespace-name in
a namespace-alias-definition, only namespace names are considered, see
_basic.lookup.udir_. ]
3 In a declarative region, a namespace-alias-definition can be used to
redefine a namespace-alias declared in that declarative region to
refer only to the namespace to which it already refers. [Example: the
following declarations are well-formed:
namespace Company_with_very_long_name { /* ... */ }
namespace CWVLN = Company_with_very_long_name;
namespace CWVLN = Company_with_very_long_name; // OK: duplicate
namespace CWVLN = CWVLN;
--end example]
4 A namespace-name or namespace-alias shall not be declared as the name
of any other entity in the same declarative region. A namespace-name
defined at global scope shall not be declared as the name of any other
entity in any global scope of the program. No diagnostic is required
for a violation of this rule by declarations in different translation
units.
7.3.3 The using declaration [namespace.udecl]
1 A using-declaration introduces a name into the declarative region in
which the using-declaration appears. That name is a synonym for the
name of some entity declared elsewhere.
using-declaration:
using typenameopt ::opt nested-name-specifier unqualified-id ;
using :: unqualified-id ;
2 The member name specified in a using-declaration is declared in the
declarative region in which the using-declaration appears. [Note:
only the specified name is so declared; specifying an enumeration name
in a using-declaration does not declare its enumerators in the using-
declaration's declarative region. ]
3 Every using-declaration is a declaration and a member-declaration and
so can be used in a class definition. [Example:
struct B {
void f(char);
void g(char);
enum E { e };
union { int x; };
};
struct D : B {
using B::f;
void f(int) { f('c'); } // calls B::f(char)
void g(int) { g('c'); } // recursively calls D::g(int)
};
--end example]
4 A using-declaration used as a member-declaration shall refer to a mem-
ber of a base class of the class being defined, shall refer to a mem-
ber of an anonymous union that is a member of a base class of the
class being defined, or shall refer to an enumerator for an enumera-
tion type that is a member of a base class of the class being defined.
[Example:
class C {
int g();
};
class D2 : public B {
using B::f; // OK: B is a base of D2
using B::e; // OK: e is an enumerator of base B
using B::x; // OK: x is a union member of base B
using C::g; // error: C isn't a base of D2
};
--end example] [Note: since constructors and destructors do not have
names, a using-declaration cannot refer to a constructor or a destruc-
tor for a base class. Since specializations of member templates for
conversion functions are not found by name lookup, they are not con-
sidered when a using-declaration specifies a conversion function
(_temp.mem_). ] If an assignment operator brought from a base class
into a derived class scope has the signature of a copy-assignment
operator for the derived class (_class.copy_), the using-declaration
does not by itself suppress the implicit declaration of the derived
class copy-assignment operator; the copy-assignment operator from the
base class is hidden or overridden by the implicitly-declared copy-
assignment operator of the derived class, as described below.
5 A using-declaration for a member shall be a member-declaration.
[Example:
struct X {
int i;
static int s;
};
void f()
{
using X::i; // error: X::i is a class member
// and this is not a member declaration.
using X::s; // error: X::s is a class member
// and this is not a member declaration.
}
--end example]
6 Members declared by a using-declaration can be referred to by explicit
qualification just like other member names (_namespace.qual_). In a
using-declaration, a prefix :: refers to the global namespace. [Exam-
ple:
void f();
namespace A {
void g();
}
namespace X {
using ::f; // global f
using A::g; // A's g
}
void h()
{
X::f(); // calls ::f
X::g(); // calls A::g
}
--end example]
7 A using-declaration is a declaration and can therefore be used repeat-
edly where (and only where) multiple declarations are allowed. [Exam-
ple:
namespace A {
int i;
}
namespace A1 {
using A::i;
using A::i; // OK: double declaration
}
void f()
{
using A::i;
using A::i; // error: double declaration
}
class B {
public:
int i;
};
class X : public B {
using B::i;
using B::i; // error: double member declaration
};
--end example]
8 The entity declared by a using-declaration shall be known in the con-
text using it according to its definition at the point of the using-
declaration. Definitions added to the namespace after the using-dec-
laration are not considered when a use of the name is made. [Example:
namespace A {
void f(int);
}
using A::f; // f is a synonym for A::f;
// that is, for A::f(int).
namespace A {
void f(char);
}
void foo()
{
f('a'); // calls f(int),
} // even though f(char) exists.
void bar()
{
using A::f; // f is a synonym for A::f;
// that is, for A::f(int) and A::f(char).
f('a'); // calls f(char)
}
--end example] [Note: partial specializations of class templates are
found by looking up the primary class template and then considering
all partial specializations of that template. If a using-declaration
names a class template, partial specializations introduced after the
using-declaration are effectively visible because the primary template
is visible (_temp.class.spec_). ]
9 Since a using-declaration is a declaration, the restrictions on decla-
rations of the same name in the same declarative region
(_basic.scope_) also apply to using-declarations. [Example:
namespace A {
int x;
}
namespace B {
int i;
struct g { };
struct x { };
void f(int);
void f(double);
void g(char); // OK: hides struct g
}
void func()
{
int i;
using B::i; // error: i declared twice
void f(char);
using B::f; // OK: each f is a function
f(3.5); // calls B::f(double)
using B::g;
g('a'); // calls B::g(char)
struct g g1; // g1 has class type B::g
using B::x;
using A::x; // OK: hides struct B::x
x = 99; // assigns to A::x
struct x x1; // x1 has class type B::x
}
--end example]
10If a function declaration in namespace scope or block scope has the
same name and the same parameter types as a function introduced by a
using-declaration, the program is ill-formed. [Note: two using-decla-
rations may introduce functions with the same name and the same param-
eter types. If, for a call to an unqualified function name, function
overload resolution selects the functions introduced by such using-
declarations, the function call is ill-formed. [Example:
namespace B {
void f(int);
void f(double);
}
namespace C {
void f(int);
void f(double);
void f(char);
}
void h()
{
using B::f; // B::f(int) and B::f(double)
using C::f; // C::f(int), C::f(double), and C::f(char)
f('h'); // calls C::f(char)
f(1); // error: ambiguous: B::f(int) or C::f(int) ?
void f(int); // error:
// f(int) conflicts with C::f(int) and B::f(int)
}
--end example] ]
11When a using-declaration brings names from a base class into a derived
class scope, member functions in the derived class override and/or
hide member functions with the same name and parameter types in a base
class (rather than conflicting). [Example:
struct B {
virtual void f(int);
virtual void f(char);
void g(int);
void h(int);
};
struct D : B {
using B::f;
void f(int); // OK: D::f(int) overrides B::f(int);
using B::g;
void g(char); // OK
using B::h;
void h(int); // OK: D::h(int) hides B::h(int)
};
void k(D* p)
{
p->f(1); // calls D::f(int)
p->f('a'); // calls B::f(char)
p->g(1); // calls B::g(int)
p->g('a'); // calls D::g(char)
}
--end example] [Note: two using-declarations may introduce functions
with the same name and the same parameter types. If, for a call to an
unqualified function name, function overload resolution selects the
functions introduced by such using-declarations, the function call is
ill-formed. ]
12For the purpose of overload resolution, the functions which are intro-
duced by a using-declaration into a derived class will be treated as
though they were members of the derived class. In particular, the
implicit this parameter shall be treated as if it were a pointer to
the derived class rather than to the base class. This has no effect
on the type of the function, and in all other respects the function
remains a member of the base class.
13All instances of the name mentioned in a using-declaration shall be
accessible. In particular, if a derived class uses a using-
declaration to access a member of a base class, the member name shall
be accessible. If the name is that of an overloaded member function,
then all functions named shall be accessible. The base class members
mentioned by a using-declaration shall be visible in the scope of at
least one of the direct base classes of the class where the using-dec-
laration is specified. [Note: because a using-declaration designates
a base class member (and not a member subobject or a member function
of a base class subobject), a using-declaration cannot be used to
resolve inherited member ambiguities. For example,
struct A { int x(); };
struct B : A { };
struct C : A {
using A::x;
int x(int);
};
struct D : B, C {
using C::x;
int x(double);
};
int f(D* d) {
return d->x(); // ambiguous: B::x or C::x
}
]
14The alias created by the using-declaration has the usual accessibility
for a member-declaration. [Example:
class A {
private:
void f(char);
public:
void f(int);
protected:
void g();
};
class B : public A {
using A::f; // error: A::f(char) is inaccessible
public:
using A::g; // B::g is a public synonym for A::g
};
--end example]
15[Note: use of access-declarations (_class.access.dcl_) is deprecated;
member using-declarations provide a better alternative. ]
7.3.4 Using directive [namespace.udir]
1 using-directive:
using namespace ::opt nested-name-specifieropt namespace-name ;
A using-directive shall not appear in class scope, but may appear in
namespace scope or in block scope. [Note: when looking up a names-
pace-name in a using-directive, only namespace names are considered,
see _basic.lookup.udir_. ]
2 A using-directive specifies that the names in the nominated namespace
can be used in the scope in which the using-directive appears after
the using-directive. During unqualified name look up
(_basic.lookup.unqual_), the names appear as if they were declared in
the nearest enclosing namespace which contains both the using-direc-
tive and the nominated namespace. [Note: in this context, "contains"
means "contains directly or indirectly". ] A using-directive does not
add any members to the declarative region in which it appears. [Exam-
ple:
namespace A {
int i;
namespace B {
namespace C {
int i;
}
using namespace A::B::C;
void f1() {
i = 5; // OK, C::i visible in B and hides A::i
}
}
namespace D {
using namespace B;
using namespace C;
void f2() {
i = 5; // ambiguous, B::C::i or A::i?
}
}
void f3() {
i = 5; // uses A::i
}
}
void f4() {
i = 5; // ill-formed; neither i is visible
}
]
3 The using-directive is transitive: if a scope contains a using-direc-
tive that nominates a second namespace that itself contains using-
directives, the effect is as if the using-directives from the second
namespace also appeared in the first. [Example:
namespace M {
int i;
}
namespace N {
int i;
using namespace M;
}
void f()
{
using namespace N;
i = 7; // error: both M::i and N::i are visible
}
For another example,
namespace A {
int i;
}
namespace B {
int i;
int j;
namespace C {
namespace D {
using namespace A;
int j;
int k;
int a = i; // B::i hides A::i
}
using namespace D;
int k = 89; // no problem yet
int l = k; // ambiguous: C::k or D::k
int m = i; // B::i hides A::i
int n = j; // D::j hides B::j
}
}
--end example]
4 If a namespace is extended by an extended-namespace-definition after a
using-directive for that namespace is given, the additional members of
the extended namespace and the members of namespaces nominated by
using-directives in the extended-namespace-definition can be used
after the extended-namespace-definition.
5 If name look up finds a declaration for a name in two different names-
paces, and the declarations do not declare the same entity and do not
declare functions, the use of the name is ill-formed. [Note: in par-
ticular, the name of an object, function or enumerator does not hide
the name of a class or enumeration declared in a different namespace.
For example,
namespace A { class X { }; }
namespace B { void X(int); }
using namespace A;
using namespace B;
void f() {
X(1); // error: name X found in two namespaces
}
--end note]
6 During overload resolution, all functions from the transitive search
are considered for argument matching. The set of declarations found
by the transitive search is unordered. [Note: in particular, the
order in which namespaces were considered and the relationships among
the namespaces implied by the using-directives do not cause preference
to be given to any of the declarations found by the search. ] An
ambiguity exists if the best match finds two functions with the same
signature, even if one is in a namespace reachable through using-
directives in the namespace of the other.7) [Example:
_________________________
7) During name lookup in a class hierarchy, some ambiguities may be
namespace D {
int d1;
void f(char);
}
using namespace D;
int d1; // OK: no conflict with D::d1
namespace E {
int e;
void f(int);
}
namespace D { // namespace extension
int d2;
using namespace E;
void f(int);
}
void f()
{
d1++; // error: ambiguous ::d1 or D::d1?
::d1++; // OK
D::d1++; // OK
d2++; // OK: D::d2
e++; // OK: E::e
f(1); // error: ambiguous: D::f(int) or E::f(int)?
f('a'); // OK: D::f(char)
}
--end example]
7.4 The asm declaration [dcl.asm]
1 An asm declaration has the form
asm-definition:
asm ( string-literal ) ;
The meaning of an asm declaration is implementation-defined. [Note:
Typically it is used to pass information through the implementation to
an assembler. ]
7.5 Linkage specifications [dcl.link]
1 All function types, function names, and variable names have a language
linkage. [Note: Some of the properties associated with an entity with
language linkage are specific to each implementation and are not
described here. For example, a particular language linkage may be
associated with a particular form of representing names of objects and
functions with external linkage, or with a particular calling conven-
tion, etc. ] The default language linkage of all function types,
function names, and variable names is C++ language linkage. Two func-
tion types with different language linkages are distinct types even if
_________________________
resolved by considering whether one member hides the other along some
paths (_class.member.lookup_). There is no such disambiguation when
considering the set of names found as a result of following using-di-
rectives.
they are otherwise identical.
2 Linkage (_basic.link_) between C++ and non-C++ code fragments can be
achieved using a linkage-specification:
linkage-specification:
extern string-literal { declaration-seqopt }
extern string-literal declaration
The string-literal indicates the required language linkage. The mean-
ing of the string-literal is implementation-defined. A linkage-speci-
fication with a string that is unknown to the implementation is ill-
formed. When the string-literal in a linkage-specification names a
programming language, the spelling of the programming language's name
is implementation-defined. [Note: it is recommended that the spelling
be taken from the document defining that language, for example Ada
(not ADA) and Fortran or FORTRAN (depending on the vintage). The
semantics of a language linkage other than C++ or C are implementa-
tion-defined. ]
3 Every implementation shall provide for linkage to functions written in
the C programming language, "C", and linkage to C++ functions, "C++".
[Example:
complex sqrt(complex); // C++ linkage by default
extern "C" {
double sqrt(double); // C linkage
}
--end example]
4 Linkage specifications nest. When linkage specifications nest, the
innermost one determines the language linkage. A linkage specifica-
tion does not establish a scope. A linkage-specification shall occur
only in namespace scope (_basic.scope_). In a linkage-specification,
the specified language linkage applies to the function types of all
function declarators, function names, and variable names introduced by
the declaration(s). [Example:
extern "C" void f1(void(*pf)(int));
// the name f1 and its function type have C language
// linkage; pf is a pointer to a C function
extern "C" typedef void FUNC();
FUNC f2; // the name f2 has C++ language linkage and the
// function's type has C language linkage
extern "C" FUNC f3; // the name of function f3 and the function's type
// have C language linkage
void (*pf2)(FUNC*); // the name of the variable pf2 has C++ linkage and
// the type of pf2 is pointer to C++ function that
// takes one parameter of type pointer to C function
--end example] A C language linkage is ignored for the names of class
members and the member function type of class member functions.
[Example:
extern "C" typedef void FUNC_c();
class C {
void mf1(FUNC_c*); // the name of the function mf1 and the member
// function's type have C++ language linkage; the
// parameter has type pointer to C function
FUNC_c mf2; // the name of the function mf2 and the member
// function's type have C++ language linkage
static FUNC_c* q; // the name of the data member q has C++ language
// linkage and the data member's type is pointer to
// C function
};
extern "C" {
class X {
void mf(); // the name of the function mf and the member
// function's type have C++ language linkage
void mf2(void(*)()); // the name of the function mf2 has C++ language
// linkage; the parameter has type pointer to
// C function
};
}
--end example]
5 If two declarations of the same function or object specify different
linkage-specifications (that is, the linkage-specifications of these
declarations specify different string-literals), the program is ill-
formed if the declarations appear in the same translation unit, and
the one definition rule (_basic.def.odr_) applies if the declarations
appear in different translation units. Except for functions with C++
linkage, a function declaration without a linkage specification shall
not precede the first linkage specification for that function. A
function can be declared without a linkage specification after an
explicit linkage specification has been seen; the linkage explicitly
specified in the earlier declaration is not affected by such a func-
tion declaration.
6 At most one function with a particular name can have C language link-
age. Two declarations for a function with C language linkage with the
same function name (ignoring the namespace names that qualify it) that
appear in different namespace scopes refer to the same function. Two
declarations for an object with C language linkage with the same name
(ignoring the namespace names that qualify it) that appear in differ-
ent namespace scopes refer to the same object. [Note: because of the
one definition rule (_basic.def.odr_), only one definition for a func-
tion or object with C linkage may appear in the program; that is, such
a function or object must not be defined in more than one namespace
scope. For example,
namespace A {
extern "C" int f();
extern "C" int g() { return 1; }
extern "C" int h();
}
namespace B {
extern "C" int f(); // A::f and B::f refer
// to the same function
extern "C" int g() { return 1; } // ill-formed, the function g
// with C language linkage
// has two definitions
}
int A::f() { return 98; } // definition for the function f
// with C language linkage
extern "C" int h() { return 97; }
// definition for the function h
// with C language linkage
// A::h and ::h refer to the same function
--end note]
7 Except for functions with internal linkage, a function first declared
in a linkage-specification behaves as a function with external link-
age. [Example:
extern "C" double f();
static double f(); // error
is ill-formed (_dcl.stc_). ] The form of linkage-specification that
contains a braced-enclosed declaration-seq does not affect whether the
contained declarations are definitions or not (_basic.def_); the form
of linkage-specification directly containing a single declaration is
treated as an extern specifier (_dcl.stc_) for the purpose of deter-
mining whether the contained declaration is a definition. [Example:
extern "C" int i; // declaration
extern "C" {
int i; // definition
}
--end example] A linkage-specification directly containing a single
declaration shall not specify a storage class. [Example:
extern "C" static void f(); // error
--end example]
8 [Note: because the language linkage is part of a function type, when a
pointer to C function (for example) is dereferenced, the function to
which it refers is considered a C function. ]
9 Linkage from C++ to objects defined in other languages and to objects
defined in C++ from other languages is implementation-defined and lan-
guage-dependent. Only where the object layout strategies of two lan-
guage implementations are similar enough can such linkage be achieved.