Formatting-and-Parsing - Documentation

Functions to format or parse text, numbers and dates

Functions

format(formatString, arg0, argN) → {string}

Replaces the format item in a specified format string with the string representation of a corresponding object in a specified arguments list.

Parameters:

Name	Type	Description
`formatString`	string	Required. A composite format string. A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. The fixed text is any string that you choose, and each format item corresponds to an object in the arguments list. The composite formatting feature returns a new result string where each format item is replaced by the string representation of the corresponding object in the list. Each format item takes the following form: {index}. With the index starting from 0.
`arg0`	object	Required. The first string to replace in the template using format item syntax.
`argN`	object	Optional. Set of strings to replace in the template using format item syntax. This method takes additional format items as additional parameters to the function.

Returns:

Type:: string

A copy of format string in which format items are replaced by the string representations of arg0...

Examples

// where name equals 'John' and hoursWorked equals '27' this will return 'Name = John, hours = 27'
format('Name = {0}, hours = {1}', name, hoursWorked)

// returns 'The format string can have any number of arguments'
format('{0} {1} {2} {3} {4} {5} {6} {7} {8}', 'The', 'format', 'string', 'can', 'have', 'any', 'number', 'of', 'arguments')

format_date(datetime, formatString)

Convert a datetime object to a string using the specified format. The date format uses the following format specifiers

Format specifier	Examples	Description
yyyy	2014	4 or 2 digit year
yy	14	2 digit year
M	1..12	Month number
MM	01..12	Month number
MMM	Jan	The abbreviated name of the month
MMMM	January	The full name of the month.
d	1..31	Day of month
dd	01..31	Day of month
H	0..23	Hours (24 hour time)
HH	00..23	Hours (24 hour time)
h	0..12	Hours (12 hour time used with a t or tt.)
hh	00..12	Hours (12 hour time used with a t or tt.)
m	0..59	Minutes
mm	00..59	Minutes
s	0..59	Seconds
ss	00..59	Seconds
t	P	Post or ante meridiem
tt	PM	Post or ante meridiem
z	7:00	Offset from UTC as +-HH:mm, +-HHmm, or Z
zz	07:00	Offset from UTC as +-HH:mm, +-HHmm, or Z

Parameters:

Name	Type	Description
`datetime`	datetime	Required. The datetime to format as a string
`formatString`	string	Required. The datetime format

Example

// if mydate is 24/03/2020 17:24 this returns '24 March 2020'
format_date(myDate, 'dd MMM yyyy')

format_number(number, formatString)

Part	Description
0	1 or more zeros are used to specify the number of places to reserve for the whole or decimal part of the format. The number of zeros is the number of places reserved. All significant digits are displayed, but additional zeros are filled to the left of whole numbers or the right of decimal numbers.
,	Use the thousands separator. Any zeros between the comma and the decimal place are ignored, but are used for clearer understanding of the format.
.	Include the decimal part of the number
e+0	Use exponential notation
[]	Square brackets will treat the enclosed format part as optional and only display it if the part exists

Special formatting parts - Including a space between the special format and the number format will include the space in the formatted number

Part	Description
$	The dollar symbol will treat the number as a currency. The $ symbol can be placed at the start or end of the format
%	The percent symbol will treat the number as a percentage (multiplying it 100 before displaying)
a	The letter a will abbreviate the number rounding it to the closest thousand/million/billion etc and include an abbreviation such as k/m/b etc
o	The letter o will include the ordinal abbreviation 1st, 2nd etc.
b	The letter b specifies the number represents bytes, and will round the number to the closest byte storage unit followed by the storage unit (B, KB, GB, TB)

Examples

Number	Format	String
1000.23	'0,0.000'	'1,000.230'
1000.23	'0.0'	'1000.2'
10.23	'0000'	'0010'
0.23	'0.0[0000]'	'0.23'
12398734.202	'0.00e+0'	'1.24e+7'
1000.234	'$0,0.00'	'$1,000.23'
1001	'$ 0,0[.]00'	'$ 1,000'
1000.2	'0,0.00 $'	'1,000.20 $'
1	'0%'	'100%'
0.974878234	'0.000%'	'97.488%'
1230974	'0.0a'	'1.2m'
1	'0o'	'1st'
7884486213	'0.00 b'	'7.88 GB'

Parameters:

Name	Type	Description
`number`	number	Required. The number to format as a string
`formatString`	string	Required. The number format

Example

format_number(mynumber, '0,0.00')

parse_date(dateAsString, dateFormat) → {datetime}

Parses a string as a date with the given date format definition and returns the datetime The date format uses the following format specifiers

Format specifier	Examples	Description
yyyy	2014	4 or 2 digit year
yy	14	2 digit year
M	1..12	Month number
MM	01..12	Month number
MMM	Jan	The abbreviated name of the month
MMMM	January	The full name of the month.
d	1..31	Day of month
dd	01..31	Day of month
H	0..23	Hours (24 hour time)
HH	00..23	Hours (24 hour time)
h	0..12	Hours (12 hour time used with a t or tt.)
hh	00..12	Hours (12 hour time used with a t or tt.)
m	0..59	Minutes
mm	00..59	Minutes
s	0..59	Seconds
ss	00..59	Seconds
t	P	Post or ante meridiem
tt	PM	Post or ante meridiem
z	7:00	Offset from UTC as +-HH:mm, +-HHmm, or Z
zz	07:00	Offset from UTC as +-HH:mm, +-HHmm, or Z

Parameters:

Name	Type	Description
`dateAsString`	string	Required. The string to parse
`dateFormat`	string	Required. The datetime format the string is expected to be in

Returns:

Type:: datetime

Returns the parsed datetime or null if the string can't be parsed

Example

parse_date('2020-03-24 17:24 +10:00', 'yyyy-MM-DD HH:mm Z')

parse_number(numberAsString) → {number}

Parses a string as a number. Most text generated from the format_number method will be parse-able from this method. For example

Text to parse	Parsed number
'974'	974
'0.12345'	0.12345
'10,000.12'	10000.12
'23rd'	23
'$10,000.00'	10000
'3.467TB'	3467000000000
'-76%'	-0.76

Parameters:

Name	Type	Description
`numberAsString`	string	Required. The string to parse

Returns:

Type:: number

Returns the parsed number or null if the string can't be parsed

Example

parse_number('1,000.25')