Following are brief descriptions of the functions that convert expressions from one data type to another. For more detailed information about a specific function (such as usage and syntax), click the function name.
Function | What it does |
---|---|
Converts an expression from one supported data type to another. |
|
Converts an integer or float expression to a string expression, using a specified mask. |
|
Converts a string expression to a time expression, using a specified mask. |
|
Converts a time expression to a string expression, using a specified mask. |
|
Determines whether the specified expression is a valid value that can be converted to the specified simple data type. |
This function converts an expression from one supported data type to another. Use the following syntax:
convert (source_expr, type_name)
where: |
source_expr |
is an expression of any supported data type. This expression will be converted to the data type specified in type_name.
|
|
type_name |
is the data type to which source_expr will be converted. Valid entries are float, float[ ], integer, integer[ ], string, string[ ], boolean, boolean[ ], time, and time[ ]. Note that if type_name is followed by square brackets ([ ]), then source_expr must also be an array. Each element in the array will be converted to type_name by the rules that apply for the simple data type. |
The results of the convert function vary depending on the data types of source_exp and type_name. For summary information, select the data type of source_expr from the list below.
boolean
float
integer
string
time
NOTE Be aware that using the convert function with certain data type combinations results in syntax errors. For example, it is illogical to convert a time data type to a boolean data type, so a syntax error occurs. As necessary, use the is_valid function to verify an expression's type before using that expression in a convert function
If the source_expr is of type boolean, the results of the convert function are as follows.
Convert from boolean to... | Results |
---|---|
boolean |
No change. |
float |
If the boolean expression is true, the result is 1; if the boolean expression is false, the result is 0. |
integer |
If the boolean expression is true, the result is 1; if the boolean expression is false, the result is 0. |
string |
If the boolean expression is true, the result is "true"; if the boolean expression is false, the result is "false". |
time |
Syntax error. |
If the source_expr is of type float, the results of the convert function are as follows.
Convert from float to... | Results |
---|---|
boolean |
If source_expr = 0, the result is false; if source_expr = 1, the result is true. If source_expr <> 0 or 1, a syntax error results. |
float |
No change. |
integer |
Converts the integer part of the source_expr (that is, truncates all numbers to the right of the decimal point). An error occurs if the result is not within the range for integers. See Integer. |
string |
Results in a string of numeric characters representing the float. |
time |
Uses the integer part of the source_expr as the number of seconds to add to 1/1/1970 00:00:00 UTC (Coordinated Universal Time); returns the new time. UTC (Coordinated Universal Time) For example, convert (5.3, time) returns 1/1/1970 00:00:05. |
If the source_expr is of type integer, the results of the convert function are as follows.
Convert from integer to... | Results |
---|---|
boolean |
If source_expr = 0, the result is false; if source_expr = 1, the result is true. If source_expr <> 0 or 1, a syntax error results. |
float |
Results in the equivalent float value. |
integer |
No change. |
string |
Results in a string of numeric characters representing the integer. |
time |
Uses the source_expr as the number of seconds to add to 1/1/1970 00:00:00 UTC (Coordinated Universal Time); returns the new time. For example, convert (5, time) returns 1/1/1970 00:00:05. |
If the source_expr is of type string, the results of the convert function are as follows.
Convert from string to... | Results |
---|---|
boolean |
Syntax error, unless source_expr = "true" or source_expr = "false". (Any combination of upper and lower case is acceptable.) |
float |
Syntax error, unless source_expr is a legitimate representation of a float value. |
integer |
Syntax error, unless source_expr is a legitimate representation of an integer value. |
string |
No change. |
time |
Syntax error, unless source_expr is a legitimate representation of a time value and uses the format specified in the date/time mask for Process Engine. See Configure Process Engine general properties for information about the date/time mask. |
If the source_expr is of type time, the results of the convert function are as follows.
Convert from time to... | Results |
---|---|
boolean |
Syntax error. |
float |
Returns the number of seconds between the current system time and 1/1/1970 00:00:00 UTC (Coordinated Universal Time). For example, if SysTime = 1/1/1970 00:00:28 UTC, convert (SysTime, float) returns 28. If the current system time is set to a time zone other than UTC, the convert function makes the necessary adjustment. For example, there is an 8-hour difference between PST and UTC; if SysTime = 1/1/1970 00:00:28 PST (Pacific Standard Time) and the local time zone is Pacific Standard Time, then convert(SysTime, float) returns 28828.0. 8(hours) * 60(minutes) *60(seconds) + 28(seconds) |
integer |
Returns the number of seconds between the current system time and 1/1/1970 00:00:00 UTC (Coordinated Universal Time). For example, if SysTime = 1/1/1970 00:00:28 UTC, convert (SysTime, integer) returns 28. If the current system time is set to a time zone other than UTC, the convert function makes the necessary adjustment. For example, there is an 8-hour difference between PST and UTC; if SysTime = 1/1/1970 00:00:28 PST (Pacific Standard Time) and the local time zone is Pacific Standard Time, then convert(SysTime, integer) returns 28828. 8(hours) * 60(minutes) *60(seconds) + 28(seconds) |
string |
Results in a string representation of the source_expr. Note that this string uses the format specified in the date/time mask for Process Engine. See Configure Process Engine general properties for information about the date/time mask. |
time |
No change |
This function converts a float or integer expression to a string expression, using the format you specify. Use this function when you want to display a number in a certain format (for example, $1,000,000). You can also use the numbertostring function to round off numbers.
Use the following syntax:
numbertostring (num_exp{, num_mask}opt)
where: |
num_exp |
is an expression of type float or type integer. |
|
num_mask |
is a numeric mask that determines the format of the numbertostring function's output. While optional, note that if you do not enter a numeric mask, the numbertostring function is equivalent to the convert function. |
A numeric mask is a template used to format the output of the numbertostring function. A numeric mask is a string expression containing any valid combination of the following components.
Component | Meaning |
---|---|
+ (plus) |
When the first or last component in the mask, displays the sign of the number. When in a position other than first or last, the plus sign will be inserted in the output string exactly where you put it in the mask. For example: numbertostring (12345, "###+##") outputs 123+45 |
- (minus) |
When the first or last component in the mask, displays a negative sign if the number is negative, or displays a space if the number is positive. When in a position other than first or last, the minus sign will be inserted in the output string exactly where you put it in the mask. For example: numbertostring (123456789, "###-##-####") outputs 123-45-6789 |
# (number sign) |
Displays a digit if it is significant. When the mask contains more #s than there are significant digits, the rightmost #s receive digits first and excess #s are filled with blanks. |
0 (zero) |
Displays a digit whether or not it is significant; both leading and trailing zeros can result. |
. (decimal) |
Determines where the decimal point goes. If not specified, the decimal point is assumed to be at the right end of the mask. The number is rounded off to fit into the mask. Only one decimal point is allowed in a mask. |
Below is the resulting output when the numbertostring function converts the following numbers: 0, +29, -3344, and 77.88369. The output is formatted according to the numeric masks shown.
NOTE If the mask is too small for the number, an error occurs. The mask is too small if there are too few #s or 0s to the left of the decimal point. For example, the mask ## is inadequate for the number 300.
Mask | 0 | +29 | -3344 | 77.88369 |
---|---|---|---|---|
0000 |
0000 |
0029 |
3344 |
0078 |
#### |
|
29 |
3344 |
78 |
$#,### |
$ |
$29 |
$3,344 |
$78 |
+#### |
+ |
+29 |
-3344 |
+78 |
-#### |
|
29 |
-3344 |
78 |
####+ |
+ |
29+ |
3344- |
78+ |
####- |
|
29 |
3344- |
78 |
##.## |
. |
29. |
Runtime error |
77.88 |
To round off a number, use the numbertostring function and the appropriate numeric mask. Each number is rounded off to fit the last place in the mask. The following example rounds a number off to thousandths. In the example, Number1 is the name of an expression of type float.
numbertostring (Number1, "#,###.###")
If Number1 = 3344.7788, the resulting output is:
3,344.779
This function determines whether the specified expression is a valid value that can be converted to the specified simple data type. This function returns the boolean value true if the expression is valid; otherwise, the function returns a value of false. It can be useful to verify an expression's type via the is_valid function before using that expression in a convert function. Use the following syntax:
is_valid (expr, type)
where: |
expr |
is any expression.
|
|
type |
is a simple data type (boolean, float, integer, string, time). |
Following are two examples using string expressions. The first example returns true, the second example returns false. In the first example, str = "true".
is_valid (str, boolean)
is_valid ("1.2.3", float)
The example below verifies whether the specified float expression is valid for conversion to type integer; this example returns false because the float value is out of the range of valid integer values.
is_valid (1e20, integer)