Type conversion

The type conversion operator creates a property that converts an object of one built-in class to an object of another built-in class. The result belongs to the target built-in class. An object of a user class is converted to a numeric or string class — the result is its internal identifier, an integer or its text form — and to the logical class, giving TRUE. There is no conversion to a user class: an object is found by its identifier with a grouping (see operation correctness), and a value narrowed to a user class is given by classification.

Supported conversions

Which conversions are meaningful depends on the built-in class families of the source and target classes:

• Within the family of numbers, the value is kept as far as the target class allows. When the value does not fit in the target class, the result is NULL. An explicit conversion to an integer class in PostgreSQL rounds the value to the nearest integer. If the value is exactly halfway between two integers, NUMERIC selects the integer farther from zero: 2.5 becomes 3, and −2.5 becomes −3. For DOUBLE, the even integer is normally selected: 2.5 becomes 2. To discard the fractional part of a NUMERIC value, use the trunc[…, …] property of the Utils system module with 0 as its second argument. The floor[…] property rounds down, which differs from truncation towards zero for negative fractional values.
• Between numbers and strings, the value is converted between its numeric and textual forms. When the source string cannot be read as a number of the target class, the result is NULL. A string with a fractional part converts to an integer class with the same rounding as a NUMERIC.
• Strings also convert to and from the JSON, JSONTEXT, XML, and HTML classes.
• Within the family of dates and times, a DATETIME converts to its date (DATE) and its time (TIME), and a DATE converts to the DATETIME at midnight of that date. Converting a ZDATETIME to DATE, TIME or DATETIME gives the date, the time or the date and time of that moment in the time zone of the current locale. Conversely, a DATETIME is taken as the local date and time in that zone, and a DATE as midnight of that date. A TIME cannot be converted to the other classes of the family, and a DATE cannot be converted to TIME: such a conversion fails when the query is executed.

String and file types

String types can be converted to human-readable file types (CSVFILE, XMLFILE, JSONFILE, HTMLFILE, etc.), and vice versa - human-readable file types can be converted to string types. A file of a specific type can also be converted to a file of dynamic type (FILE, NAMEDFILE) and back, keeping the file content. The dynamic-type file additionally carries the extension, and NAMEDFILE also the name.

info

Dynamic-type files (FILE, NAMEDFILE) convert to strings and back directly: the file content is read as UTF-8 text (when it is not valid UTF-8 text, the result is NULL), and a string is written as the content of a file with the dat extension (a value of the HTML class — with the html extension). To get a different extension, convert the string to a file of a specific type first — for example, to CSVFILE, and only then to FILE: the resulting file will have the csv extension

Implicit conversions

Apart from the explicit conversion operator, the platform converts a value to another class implicitly in several contexts, without any conversion written by the developer:

• When values of different but compatible classes are combined — by addition or subtraction (see the arithmetic operators), by the selection operators, or by the extremum operators — each value is converted to their common ancestor, which becomes the result class. In particular, the number classes widen this way (an INTEGER combined with a NUMERIC becomes that NUMERIC).
• In string concatenation, an operand that is not a string is converted to a string.
• When a value is written to a property of a different but compatible class, it is converted to that class. A string assigned to a property without parameters, or for one fixed set of argument values, can be cut implicitly to the length of a shorter target string class. A change over a set of objects does not guarantee such cutting: a value longer than the length of the target class can fail with a database error at the assignment or, for a stored property, when the changes are applied. To limit the length of a string explicitly, convert it to the target string class.
• A file of a specific type is converted to a file of dynamic type (FILE, NAMEDFILE) implicitly — for example during data import without a specified format, or when working with an external system. The resulting extension is determined as for the explicit conversion.

Language

To implement conversion, the type conversion operator is used.

Examples

itemCount = DATA INTEGER (Store);
itemCountToString(s) = BPSTRING[10](itemCount(s));

barcode = DATA STRING[15] (Item);
longBarcode(Item i) = LONG(barcode(i));