- Shiboken
- » Type System Reference

# 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 (see also User Defined Type Conversion).

It may be a child of the container-type and primitive-type nodes, where conversions have to be provided for both directions using the native-to-target and target-to-native child nodes.

It may also appear as a child of value-type or smart-pointer-type where additional conversions from other target language types can be provided using the target-to-native child node.

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

Note

You can also use the `conversion-rule` node to specify customized code to convert a function argument between the target language and C++ (see conversion-rule).

## native-to-target

The native-to-target tag tells how to convert a native C++ value to its target language equivalent. It is a child of the conversion-rule node. 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 provides type system variables for the input and output values and types (see Converter Variables & Functions). The most important ones are %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. It is a child of the conversion-rule node and may have one or several add-conversion child nodes. 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. It is a child of the target-to-native node.

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