C++ 域¶

Added in version 1.0.

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

用于声明实体的指令¶

以下指令可用。所有声明都可以从可见性声明开始（“公共”，“四人”或“受保护的”）。

.. cpp:class:: class specifier¶

.. cpp:struct:: class specifier¶

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

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

cpp:class 和:rst:dir: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)¶: Ensures that the function’s parameters will be emitted on a single logical line, overriding cpp_maximum_signature_line_length and 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¶

描述（范围）枚举，可能具有指定的基础类型。在unscoped枚举中声明的任何枚举器都将在枚举范围和父范围内声明。例子：

.. 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¶

可比较、间接或递增的概念性序列的一个元素的代理。

符号

It r¶: 一个左值。

有效表达

*r，当 r 是可解除引用的。
++r，返回类型 It&，当 r 是可递增的。

Added in version 1.5.

选项¶

一些指令支持选项:

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

Added in version 1.6.

匿名的实体¶

C++ 支持匿名命名空间、类、枚举和联合。为了文档起见，必须给它们一些以 “@ ”开头的名字，例如，“@42”或 “@data”。这些名称也可以在交叉引用和（类型）表达中使用，尽管嵌套符号即使在省略时也会被找到。 “@…”名称将始终显示为**[匿名]**（可能作为链接）。

例如:

.. 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¶

显式ref: Data::[anonymous]::a 。简写ref: 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()

whereas:

.. 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表示 mentioned declaration 。默认为1。

Added in version 3.5.

:noroot:¶: 跳过 mentioned declarations ，只渲染嵌套的声明。要求 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。

但请注意，不会对参数兼容性进行检查。例如，“template introduction”将被接受作为介绍，即使它不是有效的 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)`（或文本: :cpp:texpr:`a * f(a)）。

类型: const MySortedContainer<int>& （或作为文本:cpp:texpr:const MySortedContainer<int>&）。

Added in version 1.7: The cpp:expr role.

Added in version 1.8: The cpp:texpr role.

命名空间¶

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”指令（不只是弹出作用域）。例如，之后：

.. cpp:namespace:: A::B

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

.. cpp:namespace-pop::

当前范围将是“A::B”（不是“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.

信息字段列表¶

All the C++ directives for declaring entities support the following info fields (see also 信息字段列表):

tparam: Description of a template parameter.

The cpp:function directive additionally supports the following fields:

param, parameter, arg, argument: Description of a parameter.
returns, return: Description of a return value.
retval, retvals: An alternative to returns for describing the result of the function.
throws, throw, exception: Description of a possibly thrown exception.

Added in version 4.3: The retval field type.

交叉引用¶

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

: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: 将:rst:role:cpp:struct 角色作为:rst:role:`cpp:class`角色的别名。

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

这些角色遵循Sphinx xref-syntax`规则。这意味着在引用（部分）模板专门化时必须小心，例如：如果链接看起来像这样:“:cpp:class:`MyClass”。这被解释为“int”的链接，标题为“MyClass”。在这种情况下，用反斜杠转义开口尖括号，如下所示:“MyClass<int>”。

当不需要自定义标题时，使用内联表达式的角色可能会很有用，如 cpp:expr`和:rst:role:`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()¶

引用使用:rst:role:cpp:func 角色：

任意的过载：“C::f”， C::f()
还是任意的重载：“C::f()`”，C::f()
特定的重载：“void C::f()”， :cpp:func:`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>¶

通常，引用必须包含每个模板参数列表的模板参数列表。因此可以参考上面的完整专业化“template<> Outer1`” (template<> Outer2) 和“template<>template<>Outer<int>::Inner<bool>”(template<>template<>Outer<int>::Inner<bool>).。作为简写，可以省略空模板参数列表，例如，“Outer<int>“”(Outer<int>) 和“Outer<int>::Inner<bool>”(Outer<int>::Inner<bool>)。

部分模板专业化¶

假设以下声明。

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

对部分特化的引用必须始终包含模板参数列表，例如，“template<typename T>Outer<T*>`` (template<typename T> Outer<T*>)。目前，只有当模板参数标识符是相等的字符串时，查找才会成功。

配置变量¶

请参阅:ref:cpp-config。

Sphinx

On this page

Site navigation

C++ 域¶

用于声明实体的指令¶

选项¶

匿名的实体¶

别名声明¶

约束模板¶

占位符¶

模板介绍¶

内联表达式和类型¶

命名空间¶

信息字段列表¶

交叉引用¶

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

重载（成员）函数¶

模板声明¶

（完整）模板专业化¶

部分模板专业化¶

配置变量¶