| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision |
| reference:polymorphic [2018/09/08 22:26] – [Labels] gawrilow | user_guide:extend:polymorphic [2019/01/28 17:40] – ↷ Links adapted because of a move operation oroehrig |
|---|
| |
| ===== Signature ===== | ===== Signature ===== |
| The signature describes the number and types of arguments expected by an overloaded instance, as well as default values for optional arguments. The syntax of the most primitive elements is borrowed from the standard perl //function prototypes//, enriched with further elements for [[reference:rulefiles#type_definitions|property types]] and "big" object types, [[reference:rulefiles#fuctions|option lists]] and other keyword arguments, etc. The "standard" elements are encoded with one-symbol codes, they can be written in traditional style glued together, or in a more legible style with commas and white spaces in between. Advanced elements must be separated with commas. | The signature describes the number and types of arguments expected by an overloaded instance, as well as default values for optional arguments. The syntax of the most primitive elements is borrowed from the standard perl //function prototypes//, enriched with further elements for [[user_guide:extend:rulefiles#type_definitions|property types]] and "big" object types, [[user_guide:extend:rulefiles#fuctions|option lists]] and other keyword arguments, etc. The "standard" elements are encoded with one-symbol codes, they can be written in traditional style glued together, or in a more legible style with commas and white spaces in between. Advanced elements must be separated with commas. |
| |
| Signatures of pure perl functions and wrapped C++ functions share many common elements, but also have few differences. Unless mentioned explicitly, the elements described below may be used in both cases. C++ functions are recognized by the ''c++'' [[#attributes|attribute]]. | Signatures of pure perl functions and wrapped C++ functions share many common elements, but also have few differences. Unless mentioned explicitly, the elements described below may be used in both cases. C++ functions are recognized by the ''c++'' [[#attributes|attribute]]. |
| |
| ==== Typechecks ==== | ==== Typechecks ==== |
| A type checking clause may be specified for functions with type parameters. It can contain an expression performing arbitrary checks on the deduced or explicitly given type parameters, e.g. by calling a [[reference:rulefiles#typechecks|type checking function]]. Default values for type parameters, if applicable, are assigned prior to evaluation of the type checking expression. The expression should return a boolean value signaling success or failure; it must not raise exceptions. In the successful case, the function body is executed; otherwise, the function is discarded from candidates and the overload resolution continues. | A type checking clause may be specified for functions with type parameters. It can contain an expression performing arbitrary checks on the deduced or explicitly given type parameters, e.g. by calling a [[user_guide:extend:rulefiles#typechecks|type checking function]]. Default values for type parameters, if applicable, are assigned prior to evaluation of the type checking expression. The expression should return a boolean value signaling success or failure; it must not raise exceptions. In the successful case, the function body is executed; otherwise, the function is discarded from candidates and the overload resolution continues. |
| |
| Besides performing pure checks, the type checking clause may upgrade the deduced parameter values by calling a meta-function ''type_upgrade<''T'','' other type''>''. This meta-function upgrades T to //other type// if it is allowed by upgrade relations and T has not been explicitly specified by the caller. Even if the upgrade is not possible, this function succeeds and simply returns the unchanged type of T. | Besides performing pure checks, the type checking clause may upgrade the deduced parameter values by calling a meta-function ''type_upgrade<''T'','' other type''>''. This meta-function upgrades T to //other type// if it is allowed by upgrade relations and T has not been explicitly specified by the caller. Even if the upgrade is not possible, this function succeeds and simply returns the unchanged type of T. |
| :: Tells that the function returns an object which can be modified by assigning a value to it. Primarily used with methods giving access to elements of some data container like a matrix or vector. | :: Tells that the function returns an object which can be modified by assigning a value to it. Primarily used with methods giving access to elements of some data container like a matrix or vector. |
| ? ''returns('' type '')'' | ? ''returns('' type '')'' |
| :: Tells that the function returns an object of the given type. Usually the return value is automatically recognized by the auto-generated wrapper and hooked under an appropriately "blessed" perl reference. This attribute should only be used in special cases where the automatic recognition does not work or must be overridden. In particular, this attribute must be used with [[reference:cpp_type_binding#abstract_property_types|abstract property types]]. | :: Tells that the function returns an object of the given type. Usually the return value is automatically recognized by the auto-generated wrapper and hooked under an appropriately "blessed" perl reference. This attribute should only be used in special cases where the automatic recognition does not work or must be overridden. In particular, this attribute must be used with [[user_guide:extend:cpp_type_binding#abstract_property_types|abstract property types]]. |
| ? ''returns(@)'' | ? ''returns(@)'' |
| :: Tells that the function returns several values in a list context. As usual in perl, when called in scalar context, the //last// value from the list will be taken for further processing. | :: Tells that the function returns several values in a list context. As usual in perl, when called in scalar context, the //last// value from the list will be taken for further processing. |