|
Format string
| The format string can contain placeholders (format specifier, precision specifier) for the generated output string. The specifiers define how the output value is represented. Using the format string, the output string can be formatted according to special requirements.The format string uses the following syntax: {0[:format_specifier][precision]}
(The curly brackets are mandatory. Optional parameters are enclosed by square brackets.)
 Numeric format specifiers
The following table describes the available numeric format specifiers and examples of the output produced by the specifier (for a description of the precision specifier option see below):
| Format specifier | Description | Examples |
| '{0}' or '{0:I}' or '' | Default values are used (see "Valid and default format specifiers" below). The IEC form of the data type is generated. | TO_STRING(BYTE#16#FF, '');(* returns '16#FF' *)
TO_STRING(lint#-1234567890123456789, '{0}');(* returns '-1234567890123456789' *)
TO_STRING(real#1.23456789E+015, '{0:I}');(* returns '1.234568E+15' *) |
| 'd', 'D', 'D8', 'D16' | Decimal integer.Converts the input value to a string of decimal digits (0-9). In case of a negative value, the output string is preceded by a minus sign. | TO_STRING(BYTE#16#FF, '{0:d}'); (* returns '255' *)
TO_STRING(BYTE#16#FF, '{0:d}'); (* returns '255' *)
TO_STRING(BYTE#16#FF, '{0:D8}'); (* returns '00000255' *)
TO_STRING(UDINT#4294967295, '{0:D16}'); (* returns '0000004294967295' *) |
| 'e', 'E', 'E10', 'e4' | Floating point exponential.Converts the input value to a string in scientific notation with the exponent prefixed by the letter e or E (e.g., 1.23E+01).For exponents <= 99, the exponent contains 2 digits; otherwise 3 digits. | TO_STRING(REAL#12.123456789, '{0:e}'); (* returns '1.212346e+01' *)
TO_STRING(REAL#12.123456789, '{0:E}'); (* returns '1.212346E+01' *)
TO_STRING(LREAL#-12.123456789, '{0:E10}'); (* returns '-1.2123456789E+01' *)
TO_STRING(LREAL#-12.123456789, '{0:e4}'); (* returns '-1.2123e+01' *) |
| 'f', 'F', 'F6', 'f4' | Floating point number.Converts the input value to a string in fixed-point number format (e.g., 12.1256). In case of a negative value, the output string is preceded by a minus sign.Default: 6 digits after the point. | TO_STRING(REAL#12.123456789, '{0:f}'); (* returns '12.123457' *)
TO_STRING(REAL#12.123456789, '{0:F}'); (* returns '12.123457' *)
TO_STRING(LREAL#-12.123456789, '{0:F6}'); (* returns '-12.123457' *)
TO_STRING(LREAL#-12.123456789, '{0:f4}'); (* returns '-12.1235' *) |
| 'x', 'X', 'x8', 'X8' | Hexadecimal integer.Converts the input value to a string in hexadecimal format. | TO_STRING(WORD#16#FFFF, '{0:x}'); (* returns 'ffff' *)
TO_STRING(WORD#16#FFFF, '{0:X}'); (* returns 'FFFF' *)
TO_STRING(WORD#16#FFFF, '{0:x8}'); (* returns '0000ffff' *)
TO_STRING(WORD#16#FFFF, '{0:X8}'); (* returns '0000FFFF' *) |
Character format specifiers
The following table describes the available character format specifiers and gives examples of the output produced by the specifier:
| Format specifier | Description | Examples |
| 'c', 'C' | Single character.Converts the input value to a single character (including special characters).
Conversion is based on ASCII encoding.The input value must be of the data type BYTE, WORD, DWORD or LWORD. | TO_STRING(BYTE#65, '{0:C}'); (* returns 'A' *)
TO_STRING(WORD#16#3A, '{0:C}'); (* returns ':' *)
TO_STRING(DWORD#16#40, '{0:C}'); (* returns '@' *)
TO_STRING(LWORD#16#61, '{0:C}'); (* returns 'a' *)
TO_STRING(BYTE#7, '{0:c}'); (* returns '' , because the output would be a control character *) |
Time format specifiers
The following table describes the available time format specifiers and gives examples of the output produced by the specifier (for a description of the precision specifier see below):
| Format specifier | Description | Examples |
| '{0}' or {0:I} or '' | Default values (see "Valid and default format specifiers" below) are used. The IEC form of the data type is generated. | TO_STRING(TIME#2s, ''); (* returns 'T#2s' *)
TO_STRING(LTIME#2s, '{0}'); (* returns 'LT#2s' *)
TO_STRING(LDATE#2007-10-05, '{0:I}'); (* returns 'LD#2007-10-05' *)
TO_STRING(LTOD#09:07:01.123456789, ''); (* returns 'LTOD#09:07:01.123_456_789' *)
TO_STRING(LDT#2012-10-03-16:06:07.123456789, '{0:I}'); (* returns 'LDT#2012-10-03-16:06:07.123_456_789' *) |
| 'y', 'yy', 'yyy', 'yyyy' | Extracts the year from the date. | TO_STRING(LDATE#2007-10-05, '{0:y yy yyy yyyy}'); (* returns '7 07 2007 2007' *) |
| 'M', 'MM', 'MMM', 'MMMM' | Extracts the month from the date as a numerical value (from 1 to 12) or as a string (full or abbreviated month name). | TO_STRING(LDATE#2007-10-05, '{0:M MM MMM MMMM}'); (* returns '10 10 Oct October' *) |
| 'd', 'dd', 'ddd', 'dddd' | Extracts the day of month from the date as a numerical value (from 1 to 31) or as a string (full or abbreviated weekday name). | TO_STRING(LDATE#2007-10-05, '{0:d dd ddd dddd}'); (* returns '5 05 Fr Friday' *) |
| 'h', 'hh', 'H', 'HH' | Extracts the hour from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY) using 24-hour or 12-hour format. | TO_STRING(LDT#2012-10-03-16:06:07.123456789, '{0:h hh H HH}'); (* returns '4 04 16 16' *) |
| 'm', 'mm' | Extracts the minutes from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY). | TO_STRING(LDT#2012-10-03-16:06:07.123456789, '{0:m mm}'); (* returns '6 06' *) |
| 's', 'ss' | Extracts the seconds from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY). | TO_STRING(LDT#2012-10-03-16:06:07.123456789, '{0:s ss}'); (* returns '7 07' *) |
| 'f', 'ff', 'fff', 'ffff' | Extracts the fractional part of a second from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY). | TO_STRING(LTOD#09:07:01.123456789, '{0:f ff fff ffff}'); (* returns '1 12 123 1234' *) |
| 'F', 'FF', 'FFF', 'FFFF' | Extracts the fractional part without zeroes of a second from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY). | TO_STRING(LTOD#09:07:01.123456789, '{0:F FF FFF FFFF}'); (* returns '1 12 123 1234' *) |
| '{0:hh:mm:ss.fff}' | Extracts the full date without microseconds and nanoseconds from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY). | TO_STRING(LTOD#09:07:01.123456789, '{0:hh:mm:ss.fff}'); (* returns '09:07:01.123' *) |
Precision
The optional precision value is an unsigned integer that directly follows the format specifier. It is used to indicate the precision with which the input value is to be converted. The precision value has different meanings for the different format specifiers.
| Format specifier | Precision |
| 'd', 'D', 'x', 'X' | Minimum number of digits to be output in the resulting string. If necessary, the output string is filled with zeros to its left until the result contains the number of digits specified by the precision value.Example:
TO_STRING(BYTE#16#FF, '{0:D8}'); (* returns '00000255' *) |
| 'e', 'E', 'f', 'F' | Number of digits after the decimal point.Default: 6 digits after the decimal point.Example:
TO_STRING(LREAL#-12.123456789, '{0:E4}'); (* returns '-1.2123E+01' *) |
Valid and default format specifiers
The following table shows the valid formats and the default formats for the specific input data types. The default format is used if an empty format '' or an empty placeholder '{0}' or the IEC format '{0:I}' is specified.
|
Input data type |
Valid formats |
Default format |
| SINT, INT, DINT, LINT | {0:D}, {0:X}, {0:I} | {0:D} |
USINT
UINT
UDINT | {0:D}, {0:X}, {0:I} | {0:D} |
| BYTE, WORD, DWORD, LWORD | {0:C}, {0:D}, {0:X}, {0:I} | 16#{0:X} |
| REAL, LREAL | {0:D}, {0:E}, {0:F}, {0:I} | {0:E} |
| TIME | {0:D}, {0:X}, {0:I} | T#{0:hh}:{0:mm}:{0:ss}.{0:fff}s(Empty parts in front and end are eliminated) |
| LTIME | {0:D}, {0:X}, {0:I} | LT#{0:hh}:{0:mm}:{0:ss}.{0:fff}_{us}_{ns}s(Empty parts in front and end are eliminated) |
| LDATE | {0:D}, {0:X}, {0:I} | LD#{0:yyyy}-{0:MM}-{0:dd} |
| LTOD | {0:D}, {0:X}, {0:I} | LTOD#{0:hh}:{0:mm}:{0:ss}.{0:fff}_{us}_{ns}
(µs and ns only for default format) |
| LDT | {0:D}, {0:X}, {0:I} | LDT#{0:yyyy}-{0:MM}-{0:dd}-{0:hh}:{0:mm}:{0:ss}.{0:fff}_{us}_{ns}
(µs and ns only for default format) |
|
