C++领域¶

Added in version 1.0.

C++域名（名称 cpp ）支持记录C++项目。

实体声明指令¶

以下指令可用。所有声明都可以以可见性语句开头 (public , private 或 protected ).

.. cpp:class:: class specifier¶

.. cpp:struct:: class specifier¶

描述一个类/结构，可能具有继承规范，例如：：

.. cpp:class:: MyClass : public MyBase, MyOtherBase

的区别 cpp:class 和 cpp:struct 只是装饰性的：在输出中呈现的前置符，以及在索引中显示的说明符。

类可以直接在嵌套作用域内声明，例如：：

.. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase

类模板可以声明为：：

.. cpp:class:: template<typename T, std::size_t N> std::array

或使用换行符：：

.. cpp:class:: template<typename T, std::size_t N> \
               std::array

完整和部分模板专业化可以声明：：

.. cpp:class:: template<> \
               std::array<bool, 256>

.. cpp:class:: template<typename T> \
               std::array<T, 42>

Added in version 2.0: 的 cpp:struct 指令。

.. cpp:function:: (member) function prototype¶

描述功能或成员功能，例如：：

.. cpp:function:: bool myMethod(int arg1, std::string arg2)

   A function with parameters and types.

.. cpp:function:: bool myMethod(int, double)

   A function with unnamed parameters.

.. cpp:function:: const T &MyClass::operator[](std::size_t i) const

   An overload for the indexing operator.

.. cpp:function:: operator bool() const

   A casting operator.

.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept

   A constexpr function.

.. cpp:function:: MyClass::MyClass(const MyClass&) = default

   A copy constructor with default implementation.

功能模板还可以描述为：：

.. cpp:function:: template<typename U> \
                  void print(U &&u)

和功能模板专业化：：

.. cpp:function:: template<> \
                  void print(int i)

:single-line-parameter-list: (no value)¶: 确保函数的参数将在单个逻辑行上发出，重写 cpp_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 7.1.

.. cpp:member:: (member) variable declaration¶

.. cpp:var:: (member) variable declaration¶

描述变量或成员变量，例如：：

.. cpp:member:: std::string MyClass::myMember

.. cpp:var:: std::string MyClass::myOtherMember[N][M]

.. cpp:member:: int a = 42

变量模板还可以描述为：：

.. cpp:member:: template<class T> \
                constexpr T pi = T(3.1415926535897932385)

.. cpp:type:: typedef declaration¶

.. cpp:type:: name

.. cpp:type:: type alias declaration

将类型描述为typedef声明、类型别名声明或简单描述具有未指定类型的类型名称，例如：：

.. cpp:type:: std::vector<int> MyList

   A typedef-like declaration of a type.

.. cpp:type:: MyContainer::const_iterator

   Declaration of a type alias with unspecified type.

.. cpp:type:: MyType = std::unordered_map<int, std::string>

   Declaration of a type alias.

类型别名也可以被模板化：：

.. cpp:type:: template<typename T> \
              MyContainer = std::vector<T>

示例如下所示。

typedef std::vector<int> MyList¶: 类型的类似typedef的声明。

type MyContainer::const_iterator¶: 具有未指定类型的类型别名的声明。

using MyType = std::unordered_map<int, std::string>¶: 类型别名的声明。

template<typename T> using MyContainer = std::vector<T>¶

.. cpp:enum:: unscoped enum declaration¶

.. cpp:enum-struct:: scoped enum declaration¶

.. cpp:enum-class:: scoped enum declaration¶

描述（范围）enum，可能具有指定的基础类型。在无作用域enum内声明的任何列举器都将在enum作用域和父作用域中声明。示例：：

.. cpp:enum:: MyEnum

   An unscoped enum.

.. cpp:enum:: MySpecificEnum : long

   An unscoped enum with specified underlying type.

.. cpp:enum-class:: MyScopedEnum

   A scoped enum.

.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type

   A scoped enum with non-default visibility, and with a specified
   underlying type.

.. cpp:enumerator:: name¶

.. cpp:enumerator:: name = constant

描述一个列举器，可选地定义其值，例如：：

.. cpp:enumerator:: MyEnum::myEnumerator

.. cpp:enumerator:: MyEnum::myOtherEnumerator = 42

.. cpp:union:: name¶: 描述一个工会。

Added in version 1.8.

.. cpp:concept:: template-parameter-list name¶

警告

对概念的支持是实验性的。它基于当前的标准草案和概念技术规范。功能可能会随着其发展而变化。

描述一个概念。它必须恰好有1个模板参数列表。该名称可能是一个嵌套名称。示例：：

.. cpp:concept:: template<typename It> std::Iterator

   Proxy to an element of a notional sequence that can be compared,
   indirected, or incremented.

   **Notation**

   .. cpp:var:: It r

      An lvalue.

   **Valid Expressions**

   - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
   - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
     :cpp:expr:`r` is incrementable.

这将呈现如下：

template<typename It> concept std::Iterator¶

可以比较、间接或增量的概念序列元素的代理。

Notation

It r¶: 左值。

Valid Expressions

*r ，当 r 是不可引用的。
++r ，具有返回类型 It& ，当 r 是可增量的。

Added in version 1.5.

选项¶

一些指令支持选项：

:no-index-entry: 和 :no-contents-entry: ，看到了基本标记 .
:tparam-line-spec: ，用于模板化声明。如果指定，每个模板参数将在单独的行上呈现。

Added in version 1.6.

匿名实体¶

C++支持匿名命名空间、类、枚举和联合。为了记录起见，必须给它们起一些以 @, e.g., @42 or @data. These names can also be used in cross-references and (type) expressions, though nested symbols will be found even when omitted. The @... name将始终呈现为 [anonymous] （可能作为链接）。

示例：：

.. cpp:class:: Data

   .. cpp:union:: @data

      .. cpp:var:: int a

      .. cpp:var:: double b

Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.

这将呈现为：

class Data¶

union [anonymous]¶

int a¶

double b¶

明确参考： Data::[anonymous]::a .空头裁判： Data::a .

Added in version 1.8.

混淆声明¶

有时候，在主文档之外的其他地方列出声明可能会有所帮助，例如，创建类接口的概要时。以下指令可用于此目的。

.. cpp:alias:: name or function signature¶

插入一个或多个别名声明。每个实体都可以在 cpp:any 作用如果给出了函数的名称（而不是完整签名），则将列出该函数的所有重载。

例如：：

.. cpp:alias:: Data::a
               overload_example::C::f

成为

int a
void f(double d) const
void f(double d)
void f(int i)
void f()

而：：

.. cpp:alias:: void overload_example::C::f(double d) const
               void overload_example::C::f(double d)

成为

void f(double d) const
void f(double d)

Added in version 2.0.

选项

:maxdepth: int¶: 也插入嵌套声明，最多插入给定的总深度。使用0表示无限深度，使用1表示提到的声明。返回至1。

Added in version 3.5.

:noroot:¶: 跳过提到的声明并仅呈现嵌套声明。需要 maxdepth 0或至少2。

Added in version 3.5.

受约束的模板¶

警告

对概念的支持是实验性的。它基于当前的标准草案和概念技术规范。功能可能会随着其发展而变化。

备注

Sphinx目前不支持 requires 条文

占位符¶

声明可以使用概念的名称来引入受约束的模板参数，或者使用关键字 auto 引入无约束模板参数：：

.. cpp:function:: void f(auto &&arg)

   A function template with a single unconstrained template parameter.

.. cpp:function:: void f(std::Iterator it)

   A function template with a single template parameter, constrained by the
   Iterator concept.

模板介绍¶

简单的受约束函数或类模板可以用 template introduction 而不是模板参数列表：：

.. cpp:function:: std::Iterator{It} void advance(It &it)

    A function template with a template parameter constrained to be an
    Iterator.

.. cpp:class:: std::LessThanComparable{T} MySortedContainer

    A class template with a template parameter constrained to be
    LessThanComparable.

它们呈现如下。

std::Iterator{It} void advance(It &it)¶: 具有模板参数约束为迭代器的函数模板。

std::LessThanComparable{T} class MySortedContainer¶: 模板参数限制为LessThanComparable的类模板。

但请注意，不会对参数兼容性进行检查。例如， Iterator{A, B, C} 即使它不是有效的C++，也会被接受为入门。

内联表达和类型¶

:cpp:expr:¶

:cpp:texpr:¶

插入C++运算式或类型作为内联代码 (cpp:expr ）或内联文本 (cpp:texpr ).例如：：

.. cpp:var:: int a = 42

.. cpp:function:: int f(int i)

An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).

A type: :cpp:expr:`const MySortedContainer<int>&`
(or as text :cpp:texpr:`const MySortedContainer<int>&`).

将呈现如下：

int a = 42¶

int f(int i)¶

一个表情： a * f(a) (or文本： a * f(a) ).

A类型： const MySortedContainer<int>& (or诸如文字 const MySortedContainer<int>& ).

Added in version 1.7: 的 cpp:expr 作用

Added in version 1.8: 的 cpp:texpr 作用

命名空间¶

C++域中的声明默认放置在全局作用域中。可以使用三个命名空间指令更改当前范围。它们管理堆栈声明，其中 cpp:namespace 重置堆栈并更改给定的范围。

的 cpp:namespace-push 指令将范围更改为当前范围的给定内部范围。

的 cpp:namespace-pop 指令撤销了最近的 cpp:namespace-push 指令。

.. cpp:namespace:: scope specification¶

将后续对象的当前范围更改为给定范围，并重置命名空间指令堆栈。请注意，命名空间不需要与C++命名空间相对应，但可以以类名称结尾，例如：：

.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass

所有后续对象都将被定义，就好像它们的名称是在前面加上作用域一样。将从当前范围中开始搜索后续交叉引用。

使用 NULL , 0 ，或者 nullptr 因为范围将更改为全球范围。

命名空间声明也可以模板化，例如：：

.. cpp:class:: template<typename T> \
               std::vector

.. cpp:namespace:: template<typename T> std::vector

.. cpp:function:: std::size_t size() const

宣布 size 作为类模板的成员函数 std::vector . 等价地，这可以使用以下命令声明：

.. cpp:class:: template<typename T> \
               std::vector

   .. cpp:function:: std::size_t size() const

或者：：

.. cpp:class:: template<typename T> \
               std::vector

.. cpp:namespace-push:: scope specification¶

相对于当前范围更改范围。例如，在：：之后

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

当前的范围将是 A::B::C::D .

Added in version 1.4.

.. cpp:namespace-pop::¶

撤消以前的 cpp:namespace-push 指令（ not 只需弹出一个范围）。例如，在：：之后

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

.. cpp:namespace-pop::

当前的范围将是 A::B ( not A::B::C ).

如果没有以前的 cpp:namespace-push 已使用指令，但仅使用了 cpp:namespace 指令，则当前范围将重置为全局范围。也就是说， .. cpp:namespace:: A::B 相当于：

.. cpp:namespace:: nullptr

.. cpp:namespace-push:: A::B

Added in version 1.4.

信息字段列表¶

所有用于声明实体的C++指令都支持以下信息字段（另请参阅信息字段列表 ):

tparam ：模板参数的描述。

的 cpp:function 指令还支持以下字段：

param , parameter , arg , argument ：参数的描述。
returns , return ：返回值的描述。
retval , retvals ：替代品 returns 用于描述函数的结果。
throws , throw , exception ：可能引发的异常的描述。

Added in version 4.3: 的 retval 字段类型。

相互参照¶

这些角色链接到给定的声明类型：

:cpp:any:¶
:cpp:class:¶
:cpp:struct:¶
:cpp:func:¶
:cpp:member:¶
:cpp:var:¶
:cpp:type:¶
:cpp:concept:¶
:cpp:enum:¶
:cpp:enumerator:¶: 按名称引用C++声明（详细信息请参阅下文）。名称必须相对于链接的位置进行适当限定。

Added in version 2.0: 的 cpp:struct 作为别名的角色 cpp:class 作用

关于具有模板参数/参数的引用的注释

这些角色跟随狮身克斯语法规则这意味着在引用（部分）模板专门化时必须小心，例如，如果链接看起来像这样： :cpp:class:`MyClass<int> .这被解释为链接到 ``int` 标题为 MyClass .在这种情况下，用反斜线去掉开头尖括号，如下所示： :cpp:class:`MyClass\<int> `.

当不需要自定义标题时，使用内联表达的角色可能很有用， cpp:expr 和 cpp:texpr ，其中角撑不需要脱落。

没有模板参数和模板参数的声明¶

对于链接到非模板化声明，名称必须是嵌套名称，例如， f 或 MyClass::f .

超载（成员）功能¶

当仅使用其名称引用（成员）函数时，该引用将指向任意匹配的重载。的 cpp:any 和 cpp:func 角色使用替代格式，这只是一个完整的函数声明。这将解决精确的匹配过载。例如，考虑以下类声明：

class C¶

void f(double d) const¶

void f(double d)¶

void f(int i)¶

void f()¶

引用使用 cpp:func 角色：

任意超载： C::f , C::f()
任意过载： C::f() , C::f()
具体过载： void C::f() , void C::f()
具体过载： void C::f(int) , void C::f(int)
具体过载： void C::f(double) , void C::f(double)
具体过载： void C::f(double) const , void C::f(double) const

注意到 add_function_parentheses 配置变量不影响特定的过载引用。

模板声明¶

假设以下声明。

class Wrapper¶

template<typename TOuter> class Outer¶

template<typename TInner> class Inner¶

一般来说，引用必须包括模板参数声明和限定名前缀的模板参数。例如：

template\<typename TOuter> Wrapper::Outer (template<typename TOuter> Wrapper::Outer)
template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner (template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner)

目前，只有当模板参数标识符是相等的字符串时，查找才成功。也就是说， template\<typename UOuter> Wrapper::Outer 行不通。

作为一种简写符号，如果省略模板参数列表，那么查找将假设主模板或非模板，但不是部分模板专业化。这意味着以下引用也有效：

Wrapper::Outer (Wrapper::Outer)
Wrapper::Outer::Inner (Wrapper::Outer::Inner)
template\<typename TInner> Wrapper::Outer::Inner (template<typename TInner> Wrapper::Outer::Inner)

（完整）模板专业¶

假设以下声明。

template<typename TOuter> class Outer¶

template<typename TInner> class Inner¶

template<> class Outer<int>¶

template<typename TInner> class Inner¶

template<> class Inner<bool>¶

In general the reference must include a template parameter list for each template argument list. The full specialisation above can therefore be referenced with template\<> Outer\<int> (template<> Outer<int>) and template\<> template\<> Outer\<int>::Inner\<bool> (template<> template<> Outer<int>::Inner<bool>). As a shorthand the empty template parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).

部分模板专业化¶

假设以下声明。

template<typename T> class Outer<T*>¶

References to partial specialisations must always include the template parameter lists, e.g., template\<typename T> Outer\<T*> (template<typename T> Outer<T*>). Currently the lookup only succeed if the template parameter identifiers are equal strings.

配置变量¶

看到 C++域的选项 .