TO_WSTRING

Type Function

Description Converts an input value into an output value of the data type WSTRING. The format string applied to the FORMAT input is used to format the output string, i.e., how the output string is represented.

Notes

When the string output is longer than 80 characters and the FU is directly connected to another FU, temporary string variables of size 80 are used. Calculation/usage will fail. If the result of the operation is longer than 80 characters, then a 'String too short' message will be logged and the output is set to an empty string or the last valid value is kept, respectively. Use an intermediate local variable in-between.

The input value is not checked for validity. In case of an error (see error behavior below), the program execution continues and a string error is written to the Online log in the MESSAGES window.

The function is an overloaded function. It can operate on various input data types.

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 "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

Data type: WSTRING

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 "{0:i}" or "" Default values are used (see "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 *)

Date and Time format specifiers

Note
.Net standard date and time format strings and custom date and time format strings
Although the same format specifiers are used, the result of the formatting is different. The behavior is as follows: First it is searched for a standard specifier and then for a custom specifier. Standard specifiers stand always alone (single character). When there are combinations with other specifiers, the custom specifier is used. To force the custom specifier, a "%" has to be prefixed. Check the results of the formatted string to be sure that the desired result is achieved.

Examples:
TO_WSTRING(LTOD#11:57:31.123.456.789, "{0:s}"); (* standard specifier; returns "1970-01-01T11:57:31" *)
TO_WSTRING(LTOD#11:57:31.123.456.789, "{0:ss}"); (* custom specifier; returns "31" *)
TO_WSTRING(LTOD#11:57:31.123.456.789, "{0:m:s}"); (* custom specifier; returns "57:31" *)
TO_WSTRING(LTOD#11:57:31.123.456.789, "{0:%s}"); (* custom specifier (forced with character "%"); returns "31" *)

The following table describes the available date and 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}", "{0:I}", "{0:i}", or "" Default values (see "Default format specifiers" below) are used. The IEC form of the data type is generated.
("I" additional date and time specifier) 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" *)

"D" Numerical representation (additional date and time specifier) TO_WSTRING(LDATE#1999-09-09, "{0:D}"); (* returns "936835200000000000" *)
TO_WSTRING(LDATE#1970-01-01, "{0:D}"); (* returns "Thursday, 01 January 1970" *)

"x", "X" Hexadecimal representation (additional date and time specifier) TO_WSTRING(LDATE#1999-09-09, "{0:x}"); (* returns ""d004ea69d150000" " *)
TO_WSTRING(LDATE#1999-09-09, "{0:X}"); (* returns "D004EA69D150000" *)

"y", "yy", "yyy", "yyyy" Extracts the year from the date.
Standard date and time specifier: year/month pattern TO_WSTRING(LDATE#2007-10-05, "{0:y yy yyy yyyy}"); (* returns "7 07 2007 2007" *)
TO_WSTRING(LDATE#1999-09-09, "{0:y}"); (* returns "1999 September" *)

"Y" Standard date and time specifier: year/month pattern TO_WSTRING(LDATE#1999-09-09, "{0:Y}"); (* returns "1999 September" *)

"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).
Standard date and time specifier: month/day pattern TO_WSTRING(LDATE#2007-10-05, "{0:M MM MMM MMMM}"); (* returns "10 10 Oct October" *)
TO_WSTRING(LDATE#1999-09-09, "{0:M}"); (* returns " September 09" *)

"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).
Standard date specifier: short date pattern
Standard time specifier: short decimal integer TO_WSTRING(LDATE#2007-10-05, "{0:d dd ddd dddd}"); (* returns "5 05 Fri Friday" *)
TO_WSTRING(LDATE#1970-01-30, "{0:d}"); (* returns "01/30/1970" *)
TO_WSTRING(TIME#5S, 2{0:d}"); (* returns "5000" *)

"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).
Standard date and time specifier: month/day pattern TO_WSTRING(LDT#2012-10-03-16:06:07.123456789, "{0:m mm}"); (* returns "6 06" *)
TO_WSTRING(LDATE#1999-09-09, "{0:m}"); (* returns "September 09" *)

"s", "ss" Extracts the seconds from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY).
Standard date and time specifier: sortable date/time pattern in 24-hour format. Time zone is unspecified. TO_WSTRING(LDT#2012-10-03-16:06:07.123456789, "{0:s ss}"); (* returns "7 07" *)
TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:s}"); (* returns "1970-01-01T13:57:31" *)

"f", "ff", "fff", "ffff", "fffff", "ffffff", "fffffff" Extracts the fractional part of a second from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY).
Standard date and time specifier: full date/time pattern (short time) in 12-hour format TO_WSTRING(LTOD#09:07:01.123456789, "{0:f ff fff ffff}"); (* returns "1 12 123 1234" *)
TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:f}"); (* returns "Thursday, 01 January 1970 1:57 PM" *)

"F", "FF", "FFF", "FFFF", "FFFFF", "FFFFFF", "FFFFFFF" Extracts the fractional part without zeroes of a second from a date time value (LDATE, LDATE_AND_TIME, and LTIME_OF_DAY).
Standard date and time specifier: full date/time pattern (long time) in 12-hour format TO_WSTRING(LTOD#09:07:01.123456789, "{0:F FF FFF FFFF}"); (* returns "1 12 123 1234" *)
TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:F}"); (* returns "Thursday, 01 January 1970 1:57:31 PM" *)

"g", "gg" Extracts the period or era.
Standard date and time specifier: general date/time pattern (short time) in 12-hour format TO_WSTRING(LDATE#1999-09-09, "{0:gg}"); (* returns "A.D." *)
TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:g}"); (* returns "01/01/1970 1:57 PM" *)

"G" Standard date and time specifier: general date/time pattern (long time) TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:G}"); (* returns "01/01/1970 1:57:31 PM" *)

"o", "O" Standard date and time specifier: round-trip date/time pattern. Time zone is unspecified. TO_WSTRING(LDT#1970-01-01-11:57:31.123456789, "{0:o}"); (* returns "1970-01-01T11:57:31.1234567" *)

"r", "R" Standard date and time specifier: RFC1123 pattern. Time zone is unspecified, therefore usage limited. TO_WSTRING(LDT#1970-01-01-11:57:31.123456789, "{0:r}"); (* returns "Thu, 01 Jan 1970 11:57:31 GMT" *)

"t", "tt" Extracts the characters of the AM/PM designator.
Standard date and time specifier: short time pattern in 12-hour format TO_WSTRING(LDT#1970-01-01-11:57:31.123456789, "{0:t tt}"); (* returns "A AM" *)
TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:t}"); (* returns "1:57 PM" *)

"T" Standard date and time specifier: long time pattern in 12-hour format TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:T}"); (* returns "1:57:31 PM" *)

"u" Standard date and time specifier: universal sortable date/time pattern in 24-hour format.
Time zone unspecified. TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:u}"); (* returns "1970-01-0113:57:31Z" *)

"U" Standard date and time specifier: universal full date/time pattern in 12-hour format.
Time zone unspecified. TO_WSTRING(LDT#1970-01-01-13:57:31.123456789, "{0:U}"); (* returns "Thursday, 01 January 1970 1:57:31 PM" *)

"K" Time zone information
Time zone unspecified - not supported. -

"z", "zz", "zzz" Hours/minutes offset from UTC
The signed offset of the local operating system's time zone from UTC. TO_WSTRING(LDT#1970-01-01-11:57:31.123456789, "{0:z zz zzz}"); (* returns "+0 +00 +00:00" )
(UTC format is not available.)

":", "/", "+" and others Separators ":" and "/" are taken as is, no culture specific character is used. TO_WSTRING(LDT#1970-01-01-11:57:31.123456789, "{0:mm:mm/mm+mm}"); (* returns "57:57/57+57" *)

"%" Forces the custom specifier. TO_WSTRING(LDT#2012-10-03-16:06:07.123456789, "{0:%h%F}"); (* returns "41" *)

"\" Forces to output the specifier character. TO_WSTRING(LDT#2012-10-03-16:06:07.123456789, "{0:h \\h}"); (* returns "4 h" *)

"{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" *)

Default format specifiers

The following table shows 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 Default format

SINT, INT, DINT, LINT {0:D}

USINT, UINT, UDINT {0:D}

BYTE, WORD, DWORD, LWORD 16#{0:X}

REAL, LREAL {0:E}

TIME T#{0:hh}:{0:mm}:{0:ss}.{0:fff}s
(Empty parts in front and end are eliminated)

LTIME LT#{0:hh}:{0:mm}:{0:ss}.{0:fff}_{us}_{ns}s
(Empty parts in front and end are eliminated)

LDATE LD#{0:yyyy}-{0:MM}-{0:dd}

LTOD LTOD#{0:hh}:{0:mm}:{0:ss}.{0:fff}_{us}_{ns}
(µs and ns only for default format)

LDT LDT#{0:yyyy}-{0:MM}-{0:dd}-{0:hh}:{0:mm}:{0:ss}.{0:fff}_{us}_{ns}
(µs and ns only for default format)

Error behavior Error behavior

The following table shows the errors which may occur while executing the function and the value returned by the function in the corresponding error case. As described, the value returned by the function in the error case depends on the value of the input (for example, if the input value of data type REAL is not a legal number (NaN), the function returns the string 'NaN').

Error case Output value

Resulted string too short (input string > output string) Empty string ("")

Format string failure Empty string ("")

Real: NaN "NaN"

Real: inf+ "INF"

Real: Inf- "-INF"

If any of the listed errors occurs, a string error is written to the Online log in the MESSAGES window.

Note
Controller stop on string error: The controller can be automatically stopped when a string error occurs. This allows you to locate the error in your project. To enable the automatic stop of the controller in case of a string error, activate the button in the Cockpit toolbar of the controller.

Additional information EN/ENO behavior

The POU is only executed if TRUE is applied to the EN input. If EN = FALSE, the POU is not executed and ENO = FALSE indicates the inactivity.

If any of the errors listed under "Error behavior" occurs while executing the function, ENO is set to FALSE.

Further Info
See the topic "General information on execution control with EN/ENO" for further details.