Parameters
| Inputs
IN
Data type: | The function is available for the following input data types:
- BOOL, BYTE, WORD, DWORD, LWORD
- Integers: SINT, INT, DINT, LINT, USINT, UINT, UDINT, ULINT
- Floating point numbers: REAL, LREAL
- Duration: TIME, LTIME
- Date: LDATE, LTIME_OF_DAY, LDATE_AND_TIME
- STRING
|
FORMAT
Data type: | Format (of WSTRING type) into which the string is to be converted (see description below).There can be an empty string ("") or the default format specifiers (empty string "", "{0}" or "{0:I}") connected or a standard format specifier (e.g., d for an integer) can be embedded into the string. If an empty string is specified, the default format specifier for the connected input value is used (see "Valid and default format specifiers" below).
Examples in ST
StringOut := TO_WSTRING(INT#256,"Duration is {0:d} ms"); (* results in "Duration is 256 ms" *) StringOut := TO_WSTRING(INT#256,"{0}"); (* results in "256" *) |
Output
OUT
|
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_WSTRING(BYTE#16#FF, "");(* returns "16#FF" *)
TO_WSTRING(lint#-1234567890123456789, "{0}");(* returns "-1234567890123456789" *)
TO_WSTRING(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_WSTRING(BYTE#16#FF, "{0:d}"); (* returns "255" *)
TO_WSTRING(BYTE#16#FF, "{0:d}"); (* returns "255" *)
TO_WSTRING(BYTE#16#FF, "{0:D8}"); (* returns "00000255" *)
TO_WSTRING(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_WSTRING(REAL#12.123456789, "{0:e}"); (* returns "1.212346e+01" *)
TO_WSTRING(REAL#12.123456789, "{0:E}"); (* returns "1.212346E+01" *)
TO_WSTRING(LREAL#-12.123456789, "{0:E10}"); (* returns "-1.2123456789E+01" *)
TO_WSTRING(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_WSTRING(REAL#12.123456789, "{0:f}"); (* returns "12.123457" *)
TO_WSTRING(REAL#12.123456789, "{0:F}"); (* returns "12.123457" *)
TO_WSTRING(LREAL#-12.123456789, "{0:F6}"); (* returns "-12.123457" *)
TO_WSTRING(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_WSTRING(WORD#16#FFFF, "{0:x}"); (* returns "ffff" *)
TO_WSTRING(WORD#16#FFFF, "{0:X}"); (* returns "FFFF" *)
TO_WSTRING(WORD#16#FFFF, "{0:x8}"); (* returns "0000ffff" *)
TO_WSTRING(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_WSTRING(BYTE#65, "{0:C}"); (* returns "A" *)
TO_WSTRING(WORD#16#3A, "{0:C}"); (* returns ":" *)
TO_WSTRING(DWORD#16#40, "{0:C}"); (* returns "@" *)
TO_WSTRING(LWORD#16#61, "{0:C}"); (* returns "a" *)
TO_WSTRING(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_WSTRING(TIME#2s, ""); (* returns "T#2s" *)
TO_WSTRING(LTIME#2s, "{0}"); (* returns "LT#2s" *)
TO_WSTRING(LDATE#2007-10-05, "{0:I}"); (* returns "LD#2007-10-05" *)
TO_WSTRING(LTOD#09:07:01.123456789, ""); (* returns "LTOD#09:07:01.123_456_789" *)
TO_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(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_WSTRING(LREAL#-12.123456789, "{0:E4}"); (* returns "-1.2123E+01" *) |
|