diff options
Diffstat (limited to 'sources/shiboken6/doc/typesystem_conversionrule.rst')
| -rw-r--r-- | sources/shiboken6/doc/typesystem_conversionrule.rst | 184 |
1 files changed, 92 insertions, 92 deletions
diff --git a/sources/shiboken6/doc/typesystem_conversionrule.rst b/sources/shiboken6/doc/typesystem_conversionrule.rst index 4ac2bd365..9a8f51c18 100644 --- a/sources/shiboken6/doc/typesystem_conversionrule.rst +++ b/sources/shiboken6/doc/typesystem_conversionrule.rst @@ -8,99 +8,99 @@ 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 :ref:`user-defined-type-conversion`). - - It is a child of the :ref:`container-type`, :ref:`primitive-type` or - :ref:`value-type` and may contain :ref:`native-to-target` or - :ref:`native-to-target` child nodes. - - .. code-block:: xml - - <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 :ref:`add-conversion` (providing snippet - functionality) or via :ref:`insert-template` (XML template, - see :ref:`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 :ref:`conversionrule-on-arguments`). +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 :ref:`user-defined-type-conversion`). -.. _native-to-target: - -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 :ref:`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. - :ref:`insert-template` tags may be used to insert commonly repeating code. +It is a child of the :ref:`container-type`, :ref:`primitive-type` or +:ref:`value-type` and may contain :ref:`native-to-target` or +:ref:`native-to-target` child nodes. - .. code-block:: xml +.. code-block:: xml + <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> - 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 code can be inserted directly, via :ref:`add-conversion` (providing snippet +functionality) or via :ref:`insert-template` (XML template, +see :ref:`using-code-templates`). - The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes). +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 :ref:`conversionrule-on-arguments`). + +.. _native-to-target: + +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 :ref:`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. +:ref:`insert-template` tags may be used to insert commonly repeating code. + +.. code-block:: xml + + <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 :ref:`inject-code` nodes). .. _target-to-native: 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 - :ref:`conversion-rule` node and may have one or several :ref:`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*. +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 +:ref:`conversion-rule` node and may have one or several :ref:`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*. - .. code-block:: xml +.. code-block:: xml - <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> + <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: @@ -108,26 +108,26 @@ target-to-native 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 :ref:`target-to-native` node. +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 :ref:`target-to-native` node. - .. code-block:: xml +.. code-block:: xml - <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> + <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 ``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 :ref:`inject-code` nodes). +The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes). |