ON THIS PAGE:
Format
String(Arg1, [FormatString])
Returns
Converts the supplied argument into a String data type.
Inputs
Arg1: The argument to be converted.
Behaviour: Required
Dimension: Collection, SingleValue, MultiCollection
Valid data types: Boolean, DateTime, Decimal, Integer, Duration
FormatString: The string specifying how to format the result. This must be in quotation marks. Only used when Arg1 is a DateTime or Duration data type.
Behaviour: Optional
Dimensions: SingleValue
Valid data types: String
Format Codes
The following codes within the FormatString are replaced with the relevant information.
- The codes must be in quotation marks. E.g. "Day"
- You may concatenate the codes to produce the desired string. E.g. "DayMonth"
- You may include other text, spaces, and punctuation within the quotation marks. E.g. "Day, Month"
- Any other text within the quotation marks is converted to upper case.
For DateTime arguments
- The codes are not case sensitive.
| DDD | Day of year (001 to 366) |
| DAY | Full weekday name |
| DY | Abbreviated weekday name, e.g. FRI |
| MONTH | Full month name |
| MON | Abbreviated month name, e.g. AUG |
| HH | Hour in 12 hour format (1 - 12) |
| YYYY | Four-digit year |
| A.M. | AM or PM indicator |
| AM | AM or PM indicator |
| P.M. | AM or PM indicator |
| PM | AM or PM indicator |
| WW | Week of year, if Sunday is the first day of the week |
| IW | Week of year, if Monday is the first day of the week |
| DD | Day of month (01 to 31) |
| MM | Month (01 to 12) |
| MI | Minutes (00 to 59) |
| SS | Seconds (00 to 59) |
| D | Day of week |
| IY | Two-digit year (00 to 99) |
| YY | Two-digit year (00 to 99) |
For Duration arguments
- The codes are case sensitive.
- The default pattern is: D:hh:mm:ss.FFFFFFF, where:
| D | Day of month (01 to 31) |
| hh | Hour in 12 hour format (1 - 12) |
| mm | Minutes (00 to 59) |
| ss | Seconds (00 to 59) |
| FFFFFFF | Milliseconds (0 to 9999999) |
The following custom patterns are also available for duration types:
| Character | Meaning | Example |
| D (DD etc) | Total days | 54 hours with a pattern of D:hh:mm → 2:06:00 |
| H (HH etc) | Total hours | 54 hours with a pattern of H:mm → 54:00 |
| h or hh | Hours within a day (0-23) | 54 hours with a pattern of D:hh → 2:06 |
| M (MM etc) | Total minutes | 3 hours and 10 minutes with a pattern of M:ss → 190:00 |
| m or mm | Minutes within an hour (0-59) | 3 hours and 10 minutes with a pattern of H:mm:ss → 3:10:00 |
| S (SS etc) | Total seconds | 2 minutes and 10 seconds with a pattern of S.fff → 70.000 |
| s or ss | Seconds within a minute (0-59) | 2 minutes and 10 seconds with a pattern of M:ss.fff → 2:10.000 |
| f ... fffffff | The fractional second part of the duration, using exactly the specified number of characters. Trailing digits are truncated towards zero. | 1 second, 1234500 ticks: s.fffffff → 1.1234500 Exactly 1 second: s.f → 1.0 |
| F ... FFFFFFF | The fractional second part of the duration, using at most the specified number of characters (up to 7). Trailing digits are truncated towards zero, and trailing insignificant zeroes are truncated. If this comes after a decimal separator and the value is zero, the decimal separator is also truncated. | 1 second, 1234500 ticks: s.FFFFFFF → 1.12345 Exactly 1 second: s.F → 1 |
| + | The sign of the value, always specified whether positive or negative. The character used will depend on the format provider; + and - are used by the invariant culture. | Positive value: +HH:mm → +07:30 Negative value: +HH:mm -> -07:30 |
| - | The sign of the value, only specified when the value is negative. The character used will depend on the format provider; - is used by the invariant culture. | Positive value: -HH:mm → 07:30 Negative value: -HH:mm → -07:30 |
| . | This is always a period ("."); not a culture-sensitive decimal separator. The only difference between a period and any other literal character is that when followed by a series of "F" characters, the period will be removed if there are no fractional seconds. | |
| : | The time separator for the format provider; colon in the invariant culture. | HH:mm → 07:30 |
Other special characters available in duration types:
| Character | Meaning | Example |
| % | Escape to force a single-character custom pattern to be treated as such. | %H → 5 |
| ' | Open and close a text literal, which can include double quotes. | HH'H'mm'M' → 07H30M |
| " | Open and close a text literal, which can include single quotes. | HH"'"mm → 07'30 |
| \ | Escapes the following character. | HH\'mm → 07'30 |
Examples
Expression: String(True)
Result: Returns the Boolean value of True as a string value of "True".
E.g. True
Expression: String(12)
Result: Returns the integer value of 12 as a string value of "12".
E.g. 12
Expression: String(12.2)
Result: Returns the decimal value of 12.2 as a string value of "12.2".
E.g. 12.2
Expression: String(Time(), "HH:MI:SS DD-MON-YYYY")
Result: Format the time as a string in the supplied format.
E.g. 00:00:00 01-Jan-2016
Expression: String({utc'2017-01-18 14:32'}, "DD/MM/YY HH:MI:SS")
Result: Format the supplied time in the specified format string.
E.g. 18/01/17 14:32:00
Expression: String({utc'2017-01-18 14:32'}, "DDMMYYYY")
Result: Format the supplied time as a date in the specified format string.
E.g. 18012017
Expression: String(DateTime(1232256720.0), "DD/MM/YY HH24:MI:SS")
Result: Format the supplied time in the specified format string.
E.g. 18/01/17 14:32:00
Expression: String({du'-01:02:03.456'}, "HH:MI:SS:fffffff")
Result: Format the supplied duration as a time in the specified format string.
E.g. 01:02:03:4560000
Release History
- String() 4.6.5
- Changed Arg1 parameter to support MultiCollection values.
- String() 4.0
- Initial version