Conversion Rule Tag ¶

conversion-rule tag specifies how a primitive-type ， container-type ，或 value-type may be converted to and from the native C++ language types to the target language types.

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

The example above show the structure of a complete conversion rule. Each of the child tags comprising the conversion rule are described in their own sections below.

native-to-target tag tells how to convert a native C++ value to its target language equivalent. The text inside the tag is a C++ code the takes an input value an does what’s needed to convert it to the output value. insert-template tags may be used to insert commonly repeating code.

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

Use the replace node to modify the template code. Notice that the generator must provide type system variables for the input and output values and types, namely %in , %out , %INTYPE and %OUTTYPE . In the case of container types, %INTYPE refers to the full container type (e.g. “list<int>” ) and %INTYPE_0 , %INTYPE_1 , %INTYPE_# , should be replaced by the types used in the container template (e.g. %INTYPE_0 correspondes to “int” for “list<int>” ).

file and snippet attributes are also supported (see inject-code nodes).

target-to-native tag encloses at least one, but usually many, conversions from target language values to C++ native values. The optional attribute replace tells if the target language to C++ conversions will be added to, or if they will replace the implicit conversions collected by ApiExtractor . The default value for it is 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 tag adds a rule for conversion of a target language type, indicated by the type attribute, to the C++ native type represented by the primitive-type ， container-type ，或 value-type , to which the parent conversion-rule belongs.

<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 attribute tells how a target value should be checked to see if it belongs to the type expected. This attribute is optional , for it can be derived from the type attribute, but it isn’t unusual that some special check is needed. The variables %in , %out , %INTYPE , %INTYPE_# ，和 %OUTTYPE , must be provided by the generator as in the native-to-target tag.

file and snippet attributes are also supported (see inject-code nodes).