Handlebar Helper Function: Format

Formats output based on a format string and optional type specification. It supports formatting dates, numbers, and strings according to specified patterns and culture settings.

Parameter	Type	Description
`subject`	`any`	Required. The value to format.
`formatString`	`string`	Required. The format pattern to apply. See Format Strings.
`type`	`string`	The type to format as. Valid values: `"date"`, `"numeric"`. If not specified, uses general string formatting.
`culture`	`string`	The culture code for formatting, such as `en-US` or `zh_TW`. Supports both hyphen and underscore formats. Defaults to current runtime culture if not specified.

The value that you specify for the formatString parameter determines the type of formatting to apply to the subject. These sections describe the different format strings that you can use.

Date formats are highly configurable and can be customized to suit your needs. These sections describe the different format strings that you can use.

Use the string patterns listed in this table to format dates and times. The values in the Example Output column are based on the date Monday, March 15, 2024 at 2:30:45 PM in the UTC-6 time zone with the en_US culture.

StringPattern	Name	Example Output
`d`	Short date	3/15/2024
`D`	Long date	Friday, March 15, 2024
`f`	Full date/time (short)	Friday, March 15, 2024 2:30 PM
`F`	Full date/time (long)	Friday, March 15, 2024 2:30:45 PM
`g`	General (short)	3/15/2024 2:30 PM
`G`	General (long)	3/15/2024 2:30:45 PM
`M`	Month day	March 15
`O`	Round-trip	2024-03-15T08:30:45.1230000-06:00
`R`	RFC1123	Fri, 15 Mar 2024 14:30:45 GMT
`s`	Sortable	2024-03-15T08:30:45
`t`	Short time	2:30 PM
`T`	Long time	2:30:45 PM
`u`	Universal sortable	2024-03-15 14:30:45Z
`U`	Universal full	2024-03-15T14:30:45.0Z
`Y`	Year month	March 2024

Use the string patterns listed in this table to format dates. The values in the Example column are based on the date Monday, March 15, 2024 at 2:30:45 PM in the UTC-6 time zone with the en_US culture.

String Pattern	Description	Example	Valid Range
`yyyy`	4-digit year	2024	0001–9999
`yyy`	3-digit year (minimum)	2024	001–999
`yy`	2-digit year	24	00–99
`y`	1-digit year (minimum)	2024	1–9999
`MMMM`	Full month name	March	Culture-dependent
`MMM`	Abbreviated month name	Mar	Culture-dependent
`MM`	2-digit month	03	01–12
`M`	Month without leading zero	3	1–12
`dddd`	Full day of week	Friday	Culture-dependent
`ddd`	Abbreviated day of week	Fri	Culture-dependent
`dd`	2-digit day	15	01–31
`d`	Day without leading zero	15	1–31

Use the string patterns listed in this table to format times. The values in the Example column are based on the time 2:30:45 PM in the UTC-6 time zone with the en_US culture.

String Pattern	Description	Example	Valid Range
`HH`	24-hour format (2-digit)	14	00–23
`H`	24-hour format (1-digit min)	14	0–23
`hh`	12-hour format (2-digit)	02	01–12
`h`	12-hour format (1-digit min)	2	1–12
`mm`	Minutes (2-digit)	30	00–59
`m`	Minutes (1-digit min)	30	0–59
`ss`	Seconds (2-digit)	45	00–59
`s`	Seconds (1-digit min)	45	0–59
`fff`	Milliseconds (3-digit)	123	000–999
`ff`	Centiseconds (2-digit)	12	00–99
`f`	Deciseconds (1-digit)	1	0–9
`tt`	AM/PM designator	PM	Culture-dependent
`t`	First char of AM/PM	P	Culture-dependent

You can further format dates and times using these literals and separators.

String Pattern	Description	Example
`'text'`	Literal text (single quotes)	'of'
`"text"`	Literal text (double quotes)	"the"
`/`	Date separator	/
`:`	Time separator	:
`-`	Dash separator	-
	Space	(space)

You can customize the way that numbers are formatted by using predefined or custom format strings.

Use the string patterns listed in this table to format numbers. The values in the Example columns are based on the en_US culture setting.

Pattern	Name	Example (1234.567)	Example (-1234.567)	Notes
`C` or `C2`	Currency	$1,234.57	($1,234.57)	Uses the specified culture's currency symbol and formatting.
`C0`	Currency (no decimals)	$1,235	($1,235)	Rounds to nearest integer.
`C4`	Currency (4 decimals)	$1,234.5670	($1,234.5670)	Zero-padded to 4 decimal places.
`D`	Decimal	1235	-1235	Rounds to nearest integer.
`D8`	Decimal (8 digits)	00001235	-00001235	Left-padded with zeros to 8 digits.
`E` or `E2`	Scientific	1.23E+003	-1.23E+003	Exponential notation with an uppercase 'E'.
`e3`	Scientific (lowercase)	1.235e+003	-1.235e+003	Exponential notation with a lowercase 'e'.
`F` or `F2`	Fixed-point	1234.57	-1234.57	Doesn’t include a thousands separator.
`F0`	Fixed-point (no decimals)	1235	-1235	Rounds to nearest integer.
`F6`	Fixed-point (6 decimals)	1234.567000	-1234.567000	Zero-padded to 6 decimal places.
`G`	General	1234.567	-1234.567
`N` or `N2`	Number	1,234.57	-1,234.57	Includes a thousands separator based on the specified culture.
`N0`	Number (no decimals)	1,235	-1,235	Rounds to nearest integer.
`P` or `P2`	Percent	123,456.70%	-123,456.70%
`P0`	Percent (no decimals)	123,457%	-123,457%	Rounds to nearest integer.
`R`	Round-trip	1234.567	-1234.567	Preserves precision.
`X`	Hexadecimal	4D2	Error	Numbers A-F are shown in uppercase.
`X8`	Hexadecimal (8 digits)	000004D2	Error	Numbers A-F are shown in uppercase. Zero-padded to 8 digits.
`x`	Hexadecimal (lowercase)	4d2	Error	Numbers A-F are shown in lowercase.

Use the custom format strings listed in this table to format numbers. The values in the Example columns are based on the en_US culture setting.

Pattern	Description	Example (1234.567)	Example (0.567)
`0`	Digit placeholder	Required	Required
`#`	Digit placeholder	Optional	Optional
`.`	Decimal point	1234.567	0.567
`,`	Thousands separator	1,234.567	0.567
`%`	Percentage	123456.7%	56.7%
`‰`	Per mille	1234567‰	567‰
`E0`	Scientific notation	1.234567E3	5.67E-1
`;`	Section separator	Format;NegFormat;ZeroFormat
`<text>`	Literal string	1234.567 units	0.567 units
`\`	Escape character	1234.567%	0.567%

By using the ; character, you can specify separate formats for positive, negative, and zero values. For example, Format(1234.567, "N2;N0;N2") returns 1,234.57, and Format(-1234.567, "N2;(F2);N0") returns (1,234.57).

This table shows additional examples of custom numeric formatting strings.

Format String	Input	Output	Description
`#,##0.00`	1234.567	1,234.57	Standard number with 2 decimals
`#,##0`	1234.567	1,235	Rounded to whole number
`000000`	123	000123	Zero-padded to 6 digits
`###.###`	123.456	123.456	Optional digits
`#.##;(#.##);Zero`	-123.45	(123.45)	Negative format section
`#.##;(#.##);Zero`	0	Zero	Zero format section
`# 'units'`	123	123 units	Literal text
`#.##%`	0.1234	12.34%	Percentage
`#.##‰`	0.1234	123.4‰	Per mille

When the type parameter is omitted or is set to string, these rules apply:

If the formatString parameter is empty, the string is returned as-is.
If any format string value is provided, the value is treated as a string template placeholder.
If formatting fails, an exception is thrown.

These rules are applied when formatting strings:

All format patterns are case-sensitive.
Literal text must be enclosed in single or double quotes.
Use a backslash (\) to escape special characters.
If a pattern isn’t valid, an exception is thrown.
Date patterns work only with date types, and numeric patterns workonly with numbers.
Some patterns, such as day and month names, vary by culture.
Numbers can have up to 15 significant digits.
Use semicolon (;) to separate positive, negative, and zero formats.

Use the culture parameter to specify the culture to use for formatting. These locale codes are supported:

en-US (English - United States)
en-GB (English - United Kingdom)
fr-FR (French - France)
de-DE (German - Germany)
es-ES (Spanish - Spain)
ja-JP (Japanese - Japan)
zh-CN (Chinese - China)
zh-TW (Chinese - Taiwan)

The culture value determines the date format conventions, currency symbols, decimal separators, thousands separators, day names, and month names that are used for formatting.

The function returns the formatted value as a string. If formatting fails, it returns the original value as a string (backward compatibility). All format strings are case-sensitive.