转换规则标签¶

转换规则¶

conversion-rule 标签指定了如何将 primitive-type、container-type 或 value-type 从原生 C++ 语言类型转换为目标语言类型，反之亦然（另请参阅用户定义类型转换）。

它是container-type、primitive-type或value-type的子节点，可能包含native-to-target或native-to-target子节点。

<value-type>
    <conversion-rule>
        <native-to-target>
        // Code to convert a native value to a target language object.
        </native-to-target>
        <target-to-native>
            <add-conversion type='TARGETTYPEA' check='TARGETTYPEA_CHECK(%in)'>
            // Code to convert target language type object of type TARGETTYPEA
            // to the C++ native type represented by the value/primitive/container-type.
            </add-conversion>
            <add-conversion type='TARGETTYPEB' check='TARGETTYPEB_CHECK(%in)'>
            // Code to convert target language type object of type TARGETTYPEB
            // to the C++ native type represented by the value/primitive/container-type.
            </add-conversion>
        </target-to-native>
    </conversion-rule>
</value-type>

代码可以直接插入，通过add-conversion（提供片段功能）或通过insert-template（XML模板，参见Using Code Templates）。

上面的例子展示了一个完整转换规则的结构。组成转换规则的每个子标签在下面的各自部分中进行了描述。

注意

你也可以使用conversion-rule节点来指定自定义代码，以在目标语言和C++之间转换函数参数（参见conversion-rule）。

native-to-target¶

native-to-target 标签告诉如何将本地的 C++ 值转换为其目标语言的等效值。它是 conversion-rule 节点的子节点。标签内的文本是 C++ 代码，它接受一个输入值并执行将其转换为输出值所需的操作。insert-template 标签可用于插入常见的重复代码。

<conversion-rule>
    <native-to-target>
    // Code to convert a native value to a target language object.
    </native-to-target>
</conversion-rule>

使用替换节点来修改模板代码。请注意，生成器必须为输入和输出值及类型提供类型系统变量，即%in、%out、%INTYPE和%OUTTYPE。在容器类型的情况下，%INTYPE指的是完整的容器类型（例如“list”），而%INTYPE_0、%INTYPE_1、%INTYPE_#应替换为容器模板中使用的类型（例如，%INTYPE_0对应于“list”中的“int”）。

file 和 snippet 属性也受支持（参见 inject-code 节点）。

目标到本地¶

target-to-native 标签包含至少一个，但通常是多个，从目标语言值到 C++ 原生值的转换。它是 conversion-rule 节点的子节点，并且可能有一个或多个 add-conversion 子节点。可选属性 replace 表示目标语言到 C++ 的转换是添加到还是替换由 ApiExtractor 收集的隐式转换。其默认值为 yes。

<conversion-rule>
    <target-to-native replace='yes|no'>
    // List of target to native conversions meant to replace or expand
    // the already existing implicit conversions.
    </target-to-native>
</conversion-rule>

添加转换¶

每个add-conversion标签都会添加一个目标语言类型转换规则，该规则由type属性指示，转换为由primitive-type、container-type或value-type表示的C++原生类型，这些类型属于父级conversion-rule。它是target-to-native节点的子节点。

<target-to-native>
    <add-conversion type='TARGETTYPE' check='TARGETTYPECHECK(%in)'>
    // Code to convert target language type object of type TARGETTYPE_A
    // to the C++ native type represented by the value/primitive/container-type.
    </add-conversion>
<target-to-native>

check 属性指示应如何检查目标值以确定其是否属于预期类型。此属性是可选的，因为它可以从type属性中派生，但通常需要一些特殊检查。变量%in、%out、%INTYPE、%INTYPE_#和%OUTTYPE必须由生成器提供，如native-to-target标签中所示。

file 和 snippet 属性也受支持（参见 inject-code 节点）。