修改参数¶

函数参数修改由包含在modify-function、add-function或declare-function节点中的modify-argument节点列表组成。嵌套的remove-argument、replace-default-expression、remove-default-expression、replace-type、reference-count和define-ownership节点指定了修改的详细信息。

<modify-function>
    <modify-argument index="return | this | 1 ..." rename="..."
     invalidate-after-use = "true | false" pyi-type="...">
        // modifications
    </modify-argument>
</modify-function>

将index属性设置为“1”表示第一个参数，“2”表示第二个参数，依此类推。或者，如果您想修改函数的返回值或函数调用的对象，请分别将其设置为“return”或“this”。

可选的 rename 属性用于重命名参数，并在生成的代码中使用这个新名称。此属性可用于启用 keyword arguments 的使用。

可选的 pyi-type 属性指定了出现在签名字符串和 .pyi 文件中的类型。类型字符串是通过检查此属性值、replace-type 修改和 C++ 类型来确定的。例如，该属性可用于将指针返回值包含在 Optional[] 中，以指示可能出现 None。

对于可选的invalidate-after-use属性，请参阅使用后失效。

命名、类型、默认值修改¶

remove-argument¶

remove-argument 节点从函数的签名中移除给定的参数，它是 modify-argument 节点的子节点。

<modify-argument>
    <remove-argument />
</modify-argument>

重命名为¶

rename to 节点用于重命名参数并在生成的代码中使用这个新名称，它是 modify-argument 节点的子节点。

<modify-argument>
    <rename to='...' />
</modify-argument>

警告

此标签已弃用，请改用modify-argument标签中的rename属性。

移除默认表达式¶

remove-default-expression 节点禁用给定参数的默认表达式的使用，它是 modify-argument 节点的子节点。

<modify-argument...>
    <remove-default-expression />
</modify-argument>

替换默认表达式¶

replace-default-expression 节点将指定的参数替换为由 with 属性指定的表达式，并且它是 modify-argument 节点的子节点。

<modify-argument>
    <replace-default-expression with="..." />
</modify-argument>

替换类型¶

replace-type 节点将给定参数的类型替换为由 modified-type 属性指定的类型，它是 modify-argument 节点的子节点。

<modify-argument>
    <replace-type modified-type="..." />
</modify-argument>

如果新类型是一个类，modified-type 属性必须设置为完全限定名称（包括包的名称以及类的名称）。

所有权/引用修改¶

定义所有权¶

define-ownership 标签表示该函数更改了参数对象的所有权规则，并且它是 modify-argument 节点的子节点。

<modify-argument>
      <define-ownership class="target | native"
                        owner="target | c++ | default" />
</modify-argument>

class 属性指定了注入所有权更改代码的函数类（参见代码生成术语）。owner 属性指定了对象的新所有权。它接受以下值：

target: 目标语言将完全拥有该对象的所有权。当目标语言对象被终结时，本地资源将被删除。
c++: 本地代码假定完全拥有该对象。目标语言对象将不会被垃圾回收。
default: 对象将获得默认的所有权，具体取决于它是如何创建的。

引用计数¶

reference-count 标签决定了目标语言的引用计数系统（如果有的话）应如何处理参数，它还指示了拥有被修改函数的类与参数之间的关系类型（表示为存储在所有者类中的被引用对象列表）。它是modify-argument节点的子节点。

<modify-argument>
      <reference-count action="add|remove|set|ignore" variable-name="..." />
</modify-argument>

action 属性指定在调用修改后的方法时应对参数引用计数执行的操作。它接受以下值：

add: 将参数添加到存储在此variable-name或函数签名下的先前参数值列表中，并增加参数引用计数器。
remove: 减少参数的引用计数器，并将其从存储在此variable-name或函数签名下的参数值列表中移除。
set: 减少之前存储的参数值在此variable-name或函数签名下的引用计数并移除它们。存储参数并增加参数引用计数器。
ignore: 对参数引用计数器不做任何处理（听起来毫无价值，但在某些情况下，默认情况下引用计数器的增加是强制性的，这时可能会用到）。

variable-name 属性指定用于保存引用的变量名称。它默认为函数签名。

例如，在模型/视图关系中，视图接收模型作为setModel()方法的参数时，应增加模型的引用计数，因为只要视图存在，模型就应该保持活动状态。请记住，我们假设的视图不能成为模型的父级，因为该模型也可能被其他视图使用。

父级¶

parent 节点允许您定义参数 parent，该参数将拥有参数的所有权，并在父对象被销毁时销毁 C++ 子对象（参见 Parent-child relationship）。它是 modify-argument 节点的子节点。

<modify-argument index="1">
      <parent index="this" action="add | remove" />
</modify-argument>

在index参数中，您必须指定父参数。操作add会在对象之间创建父链接，而remove则会撤销父子关系。

其他修改¶

转换规则¶

conversion-rule 节点允许您编写自定义代码，以在目标语言和 C++ 之间转换给定的参数。然后它是 modify-argument 节点的子节点：

<modify-argument index="2">
<!-- for the second argument of the function -->
<conversion-rule class="target | native">
    // the code
</conversion-rule>
</modify-argument>

class 属性接受以下值之一来定义转换方向为 target-to-native 或 native-to-target：

native: 定义转换方向为 target-to-native。
它类似于现有的元素。有关更多信息，请参见 Conversion Rule Tag。
target: 定义转换方向为 native-to-target。
它类似于现有的元素。有关更多信息，请参见 Conversion Rule Tag。

此节点通常与replace-type和remove-argument节点结合使用。给定的代码将替代生成器的转换代码。

在代码中写入 %N（其中 N 是一个数字），将插入第 N 个参数的名称。或者，使用 %in 和 %out，它们将分别被替换为转换的输入和输出变量的名称。请注意，输出变量必须显式声明，例如：

<conversion-rule class="native">
bool %out = (bool) %in;
</conversion-rule>

注意

你也可以使用conversion-rule节点来指定一个转换代码，该代码将用于替代生成器的转换代码，适用于给定类型的所有情况。

替换值¶

replace-value 属性允许你用固定字符串替换函数的返回语句。此属性只能用于 index 为 0 的参数，该参数始终是函数的返回值。

<modify-argument index="0" replace-value="this"/>