Data type conversion functions

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

convert

Converts an expression from one supported data type to another.

numbertostring

Converts an integer or float expression to a string expression, using a specified mask.

stringtotime

Converts a string expression to a time expression, using a specified mask.

timetostring

Converts a time expression to a string expression, using a specified mask.

is_valid

Determines whether the specified expression is a valid value that can be converted to the specified simple data type.

 

convert

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

Convert from boolean

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.

 

Convert from float

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) Formerly known as GMT (Greenwich Mean Time), UTC is the standard world-wide reference time zone.

For example, convert (5.3, time) returns 1/1/1970 00:00:05.

 

Convert from integer

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.

 

Convert from string

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

See Configure Process Engine general properties for information about the date/time mask.

 

Convert from time

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

See Configure Process Engine general properties for information about the date/time mask.

time

No change

 

numbertostring

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.

 

Numeric mask

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; leading and/or 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.

 

Numeric mask samples

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

 

Rounding off numbers

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

 is_valid

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)