Format String Syntax

Overview

The format string syntax let’s you quickly and easily convert numeric data and time data in seconds (with optional fractional part) to a nicely formatted string. As a simple example, this syntax will allow you to display a floating point value with only 2 digits of precision: the format string %.2f applied to 12.345 will yield the string 12.34.

The format string syntax also allows for placing ordinary text around any format syntax to compose more complex strings, and the format syntax will still be replaced within accordingly. For example, specifying a format string of: Length: %d for some input value of 10 would result in the string: Length: 10. Notice the special character % used here. If a literal % character is desired in a result string simply use %%.

Below is a complete list of available format string syntax options with descriptions and examples.

Special Case: Rounding To Integer When Fractional Part Is 0.5

The format string syntax employs a special rounding strategy when rounding to integers. For numbers with fractional parts equal to 0.5, it attempts to avoid the standard “high bias” which always rounds 0.5 up. Instead, a balance is struck when rounding up numbers with exactly 0.5 as the fractional part:

if the whole part is odd, the result rounds up as usual (ex. 11.5 rounds to integer 12, as usual)
if the whole part is even, the result rounds down (ex. 12.5 rounds to integer 12, not 13)

Number Formats

The available format string syntax provides the ability to format data to forms: integer, floating point, scientific notation, engineering notation, SI notation (international standard notation), and hexadecimal, octal, and binary integers. The number of digits of precision or significant digits can also be controlled, and in relevant cases padding and zeros can be added or removed.

Below is a complete list of numeric formatting options.

Automatic (%g)

Automatic formatting formats values to either scientific notation or floating-point notation based on the value received.

Formats values to floating point values with 6 digits of precision:

%g formats 12 to 12.000000
%g formats 12.6 to 12.600000

Formats values above 10^7 to scientific notation with 6 digits of precision:

%g formats 11234560 to 1.123456E+7
%g formats 11234560.2 to 1.123456E+7

The enhanced format %#g removes trailing zeros:

%#g formats 13.00 to 13
%#g formats 13000000 to 1.3E+7

Integer (%d)

Formats numbers to integer format.

Formats numbers to integers:

%d formats 12 to 12

Floating-point values are rounded to signed 64-bit integers:

%d formats 12.67 to 13
%d formats 10.5 to 10 (rounds down; see “Special Case: Rounding To Integer When The Fractional Part Is 0.5” above)
%d formats 11.5 to 12

NaN and any values greater than the largest signed 64-bit integer are rounded to the largest signed 64-bit integer: 9223372036854775807:

%d formats NaN to 9223372036854775807
%d formats 9223372036854775808 to 9223372036854775807

The enhanced format %<significant digits>d specifies the number of significant digits to resolve:

%_2d formats 12674 to 13000

Floating Point (%f)

Formats numbers to a floating point format.

Formats numbers to floating point notation:

%f formats 12.67 to 12.67

The enhanced format %.<precision>f specifies the number of digits of precision to use:

%.1f formats 12.67 to 12.7
%.3f formats 12.67 to 12.670
%.0f formats 10.5 to 10 (rounds down; see “Special Case: Rounding To Integer When The Fractional Part Is 0.5” above)
%.0f formats 11.5 to 12

The enhanced format %_<significant digits>f specifies the number of significant digits to resolve:

%_3f formats 12.67 to 12.7
%_5f formats 12.67 to 12.670
%_2f formats 10.5 to 10
%_2f formats 11.5 to 11

Scientific Notation (%e)

Formats numbers to scientific notation.

Formats numbers to scientific notation:

%e formats 12 to 1.2E+1

The enhanced format %.<precision>e specifies the number of digits of precision to use:

%.2e formats 12.67 to 1.27E+1
%.4e formats 12.67 to 1.2670E+1
%.1e formats 10.5 to 1.0E+1 (rounds down; see “Special Case: Rounding To Integer When The Fractional Part Is 0.5” above)
%.1e formats 11.5 to 1.2E+1

The enhanced format %_<significant digits>e specifies the number of significant digits to resolve:

%_3f formats 12.67 to 1.27E+1
%_5f formats 12.67 to 1.2670E+1
%_2f formats 10.5 to 1.0E+1
%_2f formats 11.5 to 1.2E+1

Engineering Notation (%^e)

Formats numbers to engineering notation, which forces the exponent to be a multiple of 3 so the number is effectively expressed in thousands, millions, billions etc.

Formats numbers to engineering notation:

%^e formats 12674 to 12.674E+3

The enhanced format %^.<precision>e specifies the number of digits of precision to use:

%^.2e formats 12674 to 12.67E+3
%^.4e formats 12674 to 12.6740E+3
%^.0e formats 10.5 to 10E+0 (rounds down; see “Special Case: Rounding To Integer When The Fractional Part Is 0.5” above)
%^.0e formats 11.5 to 12E+0

The enhanced format %^_<significant digits>e specifies the number of significant digits to resolve:

%^_3e formats 12674 to 12.7E+3
%^_6e formats 12674 to 12.6740E+3
%^_5e formats 12670.5 to 12.670E+3 (rounds down; see “Special Case: Rounding To Integer When The Fractional Part Is 0.5” above)
%^_5e formats 12671.5 to 12.672E+3

SI Notation (%p)

Formats numbers to SI notation (international standard notation) which uses suffixes to represent thousands (k), millions (M), billions (G) and more.

Formats numbers to SI (International System of Units) notation:

%p formats 12000000 to 12.000000M

The enhanced format %.<precision>p specifies the number of digits of precision to use:

%.2p formats 12000000 to 12.00M
%.4p formats 12000 to 12.0000K

The enhanced format %_<significant digits>p specifies the number of significant digits to resolve:

%_1p formats 12000000 to 10M
%_2p formats 12000000 to 12M
%_4p formats 12000000 to 12.00M
%_5p formats 12000.5 to 12.000k (rounds down; see “Special Case: Rounding To Integer When The Fractional Part Is 0.5” above)
%_5p formats 12001.5 to 12.002k

Hexadecimal (%x)

Formats an integer to hexadecimal (base 16).

Formats numbers in hexadecimal:

%x formats 10 to A

Formats with a specified width floating point values to integers:

%x formats 10.5 to A (rounds down; see “Special Case: Rounding To Integer When The Fractional Part Is 0.5” above)
%x formats 11.5 to C

The enhanced format %<width>x specifies the width of the result and will pad on the left with spaces:

%2x formats 12 to <space>C (i.e. " C" but without the quotes)

The enhanced format %-<width>x specifies the width of the result and will pad on the right with spaces:

%-2x formats 12 to C<space> (i.e. "C " but without the quotes)

The enhanced format %0<width>x specifies the width of the result and will pad on the left with zeros:

%02x formats 12 to 0C

Octal (%o)

Formats an integer to octal (base 8). This works just like hexadecimal described above but uses base 8 instead of base 16.

Binary (%b)

Formats an integer to binary (base 2). This works just like hexadecimal described above but uses base 2 instead of base 16.

Time Formats

Time formats provide the ability to transform a specified duration in seconds to semantic date/time strings including years, months, weeks, days, hours, minutes, seconds, and fractions of seconds. Additional options are provide as well such as the precision for fractions of seconds. Taking relative time as an example, by default %t produces a time string as a colon-delimited hours, minutes, seconds, and fractional seconds (3 digits of precision by default) such as 01:00:01.800 (1 hour, 0 minutes, 1 second, and 0.8 seconds).

However, using the enhanced format %<time format string>t we can control the returned time format further. For example, %<%H hrs %M mins %S secs>t formats 91.8 to 00 hrs 01 mins 31 secs. Using %T (capital T) as a basis will yield absolute / current time when the value to which the format will be applied is the number of seconds (including fractional seconds) since 00:00:00 UTC on 1 January 1904.

Below is a complete list of <time format string> options which can be used with either %<time format string>t or %<time format string>T:

%a abbreviated weekday name (ex. Wed)
%A full weekday name (ex. Wednesday)
%b abbreviated month name (ex. Jun)
%B full month name (ex. June)
%c locale-specific default date and time
%d day of month as 01–31
%H hour as 00–23 (24-hour clock)
%I hour as 01–12 (12-hour clock)
%j day number of the year as 001–366
%m month number as 01–12
%M minute as 00–59
%p AM or PM flag
%S second as 00–59
%<digit>u fractional seconds with precision
%U week number of the year as 00–53, with the first Sunday as the first day of week one; 00 represents the first week
%w weekday as a decimal number as 0–6, with 0 representing Sunday
%W week number of the year as 00–53, with the first Monday as the first day of week one; 00 represents the first week
%x locale-specific date
%.1x long date format
%.2x abbreviated long date format
%X locale-specific time
%y year within century as 00–99; when you scan the numbers, numbers 00–68 represent years in the twenty-first century (2000–2068) and numbers 69–99 represent years in the twentieth century (1969–1999)
%Y year, including the century (ex. 1997)
%z difference between locale time and universal time as HH:MM:SS
%Z time zone name or abbreviation, depending on the operating system locale settings

Relative Time (%t)

Formats elapsed time specified in seconds to a time-formatted string.

Formats a time in seconds to a colon-delimited hours, minutes, seconds, and fractional seconds (3 digits of precision by default):

%t formats 91.8 to 01:31.800
%t formats 3601.8 to 01:00:01.800

The enhanced format %.<precision>t specifies the number of digits of precision:

%.2t formats 91.8 to 01:31.80

The enhanced format %<time format string>t specifies the date / time format to use explicitly:

%<Hours:%H Minutes:%M Seconds:%S>t formats 91.8 to Hours:00 Minutes:01 Seconds:31

Absolute Time (%T)

Formats a current time specified in seconds from 00:00:00 UTC on 1 January 1904 to a formatted date/time string. By default this format, including the punctuation, changes based on the regional settings of the computer. The time changes based on the configured time zone for the computer. However, using the <time format string> options above the precise format returned can be controlled.

Formats the current time based on local computer settings, for example:

%T formats 3725242188.53100014 to 11:29:48.531 PM 1/16/2022 (central time on the machine used for this example)

The enhanced format %<time format string>T specifies the date / time format to use explicitly:

%<%m-%d-%Y>T formats 3725242188.53100014 to 01-16-2022
%<%m-%d-%Y %I:%M:%S%1u>T formats 3725242188.53100014 to 01-16-2022 11:29:48.5

The enhanced format %^<time format string>T (notice the caret ^ character) specifies returning the date in Universal Time (UTC):

%^T formats 3725242188.53100014 to 5:29:48.531 AM 1/17/2022 (note that UTC is 6 hours ahead, which moves the date forward by one day relative to 11:29:48.531 PM 1/16/2022 central time)
%^%m-%d-%Y>T formats 3725242188.53100014 to 01-17-2022

Sixclear JADE

Documentation