Conversion Rule Tag

conversion-rule

The conversion-rule tag specifies how a primitive-type, a container-type, or a 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 code can be inserted directly, via add-conversion (providing snippet functionality) or via insert-template (XML template, see Using Code Templates).

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

The 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>”).

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

target-to-native

The 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

Each 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, a container-type, or 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>

The 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_#, and %OUTTYPE, must be provided by the generator as in the native-to-target tag.

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