What are the supported Swift String format specifiers?

Question

In Swift, I can format a String with format specifiers:

// This will return "0.120"
String(format: "%.03f", 0.12)

But the official documentation is not giving any information or link regarding the supported format specifiers or how to build a template similar to "%.03f": https://developer.apple.com/documentation/swift/string/3126742-init

It only says:

Returns a String object initialized by using a given format string as a template into which the remaining argument values are substituted.

Answer 1

The format specifiers for String formatting in Swift are the same as those in Objective-C NSString format, itself identical to those for CFString format and are buried deep in the archives of Apple Documentation (same content for both pages, both originally from year 2002 or older):

• https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFStrings/formatSpecifiers.html
• https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Strings/Articles/formatSpecifiers.html

But this documentation page itself is incomplete, for instance the flags, the precision specifiers and the width specifiers aren't mentioned. Actually, it claims to follow IEEE printf specifications (Issue 6, 2004 Edition), itself aligned with the ISO C standard. So those specifiers should be identical to what we have with C printf, with the addition of the %@ specifier for Objective-C objects, and the addition of the poorly documented %D, %U, %O specifiers and q length modifier.

---

Specifiers

Each conversion specification is introduced by the '%' character or by the character sequence "%n$".

n is the index of the parameter, like in:

String(format: "%2$@ %1$@", "world", "Hello")

Format Specifiers

%@    Objective-C object, printed as the string returned by descriptionWithLocale: if available, or description otherwise.

Actually, you may also use some Swift types, but they must be defined inside the standard library in order to conform to the CVarArg protocol, and I believe they need to support bridging to Objective-C objects: https://developer.apple.com/documentation/foundation/object_runtime/classes_bridged_to_swift_standard_library_value_types.

String(format: "%@", ["Hello", "world"])

%%    '%' character.

String(format: "100%% %@", true.description)

%d, %i    Signed 32-bit integer (int).

String(format: "from %d to %d", Int32.min, Int32.max)

%u, %U, %D    Unsigned 32-bit integer (unsigned int).

String(format: "from %u to %u", UInt32.min, UInt32.max)

%x    Unsigned 32-bit integer (unsigned int), printed in hexadecimal using the digits 0–9 and lowercase a–f.

String(format: "from %x to %x", UInt32.min, UInt32.max)

%X    Unsigned 32-bit integer (unsigned int), printed in hexadecimal using the digits 0–9 and uppercase A–F.

String(format: "from %X to %X", UInt32.min, UInt32.max)

%o, %O    Unsigned 32-bit integer (unsigned int), printed in octal.

String(format: "from %o to %o", UInt32.min, UInt32.max)

%f    64-bit floating-point number (double), printed in decimal notation. Produces "inf", "infinity", or "nan".

String(format: "from %f to %f", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

%F    64-bit floating-point number (double), printed in decimal notation. Produces "INF", "INFINITY", or "NAN".

String(format: "from %F to %F", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

%e    64-bit floating-point number (double), printed in scientific notation using a lowercase e to introduce the exponent.

String(format: "from %e to %e", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

%E    64-bit floating-point number (double), printed in scientific notation using an uppercase E to introduce the exponent.

String(format: "from %E to %E", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

%g    64-bit floating-point number (double), printed in the style of %e if the exponent is less than –4 or greater than or equal to the precision, in the style of %f otherwise.

String(format: "from %g to %g", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

%G    64-bit floating-point number (double), printed in the style of %E if the exponent is less than –4 or greater than or equal to the precision, in the style of %f otherwise.

String(format: "from %G to %G", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

%c    8-bit unsigned character (unsigned char).

String(format: "from %c to %c", "a".utf8.first!, "z".utf8.first!)

%C    16-bit UTF-16 code unit (unichar).

String(format: "from %C to %C", "爱".utf16.first!, "终".utf16.first!)

%s    Null-terminated array of 8-bit unsigned characters.

"Hello world".withCString {
    String(format: "%s", $0)
}

%S    Null-terminated array of 16-bit UTF-16 code units.

"Hello world".withCString(encodedAs: UTF16.self) {
    String(format: "%S", $0)
}

%p    Void pointer (void *), printed in hexadecimal with the digits 0–9 and lowercase a–f, with a leading 0x.

var hello = "world"
withUnsafePointer(to: &hello) {
    String(format: "%p", $0)
}

%n    The argument shall be a pointer to an integer into which is written the number of bytes written to the output so far by this call to one of the fprintf() functions.

The n format specifier seems unsupported in Swift 4+

%a    64-bit floating-point number (double), printed in scientific notation with a leading 0x and one hexadecimal digit before the decimal point using a lowercase p to introduce the exponent.

String(format: "from %a to %a", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

%A    64-bit floating-point number (double), printed in scientific notation with a leading 0X and one hexadecimal digit before the decimal point using a uppercase P to introduce the exponent.

String(format: "from %A to %A", Double.leastNonzeroMagnitude, Double.greatestFiniteMagnitude)

Flags

'    The integer portion of the result of a decimal conversion ( %i, %d, %u, %f, %F, %g, or %G ) shall be formatted with thousands' grouping characters. For other conversions the behavior is undefined. The non-monetary grouping character is used.

The ' flag seems unsupported in Swift 4+

-    The result of the conversion shall be left-justified within the field. The conversion is right-justified if this flag is not specified.

String(format: "from %-12f to %-12d.", Double.leastNonzeroMagnitude, Int32.max)

+    The result of a signed conversion shall always begin with a sign ( '+' or '-' ). The conversion shall begin with a sign only when a negative value is converted if this flag is not specified.

String(format: "from %+f to %+d", Double.leastNonzeroMagnitude, Int32.max)

<space>    If the first character of a signed conversion is not a sign or if a signed conversion results in no characters, a <space> shall be prefixed to the result. This means that if the <space> and '+' flags both appear, the <space> flag shall be ignored.

String(format: "from % d to % d.", Int32.min, Int32.max)

&num;    Specifies that the value is to be converted to an alternative form. For o conversion, it increases the precision (if necessary) to force the first digit of the result to be zero. For x or X conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g , and G conversion specifiers, the result shall always contain a radix character, even if no digits follow the radix character. Without this flag, a radix character appears in the result of these conversions only if a digit follows it. For g and G conversion specifiers, trailing zeros shall not be removed from the result as they normally are. For other conversion specifiers, the behavior is undefined.

String(format: "from %#a to %#x.", Double.leastNonzeroMagnitude, UInt32.max)

0    For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversion specifiers, leading zeros (following any indication of sign or base) are used to pad to the field width; no space padding is performed. If the '0' and '-' flags both appear, the '0' flag is ignored. For d, i, o, u, x, and X conversion specifiers, if a precision is specified, the '0' flag is ignored. If the '0' and '" flags both appear, the grouping characters are inserted before zero padding. For other conversions, the behavior is undefined.

String(format: "from %012f to %012d.", Double.leastNonzeroMagnitude, Int32.max)

Width modifiers

If the converted value has fewer bytes than the field width, it shall be padded with spaces by default on the left; it shall be padded on the right if the left-adjustment flag ( '-' ) is given to the field width. The field width takes the form of an asterisk ( '*' ) or a decimal integer.

String(format: "from %12f to %*d.", Double.leastNonzeroMagnitude, 12, Int32.max)

Precision modifiers

An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, and X conversion specifiers; the number of digits to appear after the radix character for the a, A, e, E, f, and F conversion specifiers; the maximum number of significant digits for the g and G conversion specifiers; or the maximum number of bytes to be printed from a string in the s and S conversion specifiers. The precision takes the form of a period ( '.' ) followed either by an asterisk ( '*' ) or an optional decimal digit string, where a null digit string is treated as zero. If a precision appears with any other conversion specifier, the behavior is undefined.

String(format: "from %.12f to %.*d.", Double.leastNonzeroMagnitude, 12, Int32.max)

Length modifiers

h    Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a short or unsigned short argument.

String(format: "from %hd to %hu", CShort.min, CUnsignedShort.max)

hh    Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a signed char or unsigned char argument.

String(format: "from %hhd to %hhu", CChar.min, CUnsignedChar.max)

l    Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a long or unsigned long argument.

String(format: "from %ld to %lu", CLong.min, CUnsignedLong.max)

ll, q    Length modifiers specifying that a following d, o, u, x, or X conversion specifier applies to a long long or unsigned long long argument.

String(format: "from %lld to %llu", CLongLong.min, CUnsignedLongLong.max)

L    Length modifier specifying that a following a, A, e, E, f, F, g, or G conversion specifier applies to a long double argument.

I wasn't able to pass a CLongDouble argument to format in Swift 4+

z    Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a size_t.

String(format: "from %zd to %zu", size_t.min, size_t.max)

t    Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a ptrdiff_t.

String(format: "from %td to %tu", ptrdiff_t.min, ptrdiff_t.max)

j    Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a intmax_t or uintmax_t argument.

String(format: "from %jd to %ju", intmax_t.min, uintmax_t.max)

Answer 2

Probably supports all of below, which summarizes the format specifiers supported by NSString (source).

The format specifiers supported by the NSString formatting methods and CFString formatting functions follow the IEEE printf specification; the specifiers are summarized in below (Table 1). Note that you can also use the "n$" positional specifiers such as %1$@ %2$s. For more details, see the IEEE printf specification. You can also use these format specifiers with the NSLog function.

Format Specifiers ^{(Table 1)}

Specifier	Description
%@	Objective-C object, printed as the string returned by descriptionWithLocale: if available, or description otherwise. Also works with CFTypeRef objects, returning the result of the CFCopyDescription function.
%%	'%' character.
%d, %D	Signed 32-bit integer (int).
%u, %U	Unsigned 32-bit integer (unsigned int).
%x	Unsigned 32-bit integer (unsigned int), printed in hexadecimal using the digits 0--9 and lowercase a--f.
%X	Unsigned 32-bit integer (unsigned int), printed in hexadecimal using the digits 0--9 and uppercase A--F.
%o, %O	Unsigned 32-bit integer (unsigned int), printed in octal.
%f	64-bit floating-point number (double).
%e	64-bit floating-point number (double), printed in scientific notation using a lowercase e to introduce the exponent.
%E	64-bit floating-point number (double), printed in scientific notation using an uppercase E to introduce the exponent.
%g	64-bit floating-point number (double), printed in the style of %e if the exponent is less than --4 or greater than or equal to the precision, in the style of %f otherwise.
%G	64-bit floating-point number (double), printed in the style of %E if the exponent is less than --4 or greater than or equal to the precision, in the style of %f otherwise.
%c	8-bit unsigned character (unsigned char).
%C	16-bit UTF-16 code unit (unichar).
%s	Null-terminated array of 8-bit unsigned characters. Because the %s specifier causes the characters to be interpreted in the system default encoding, the results can be variable, especially with right-to-left languages. For example, with RTL, %s inserts direction markers when the characters are not strongly directional. For this reason, it's best to avoid %s and specify encodings explicitly.
%S	Null-terminated array of 16-bit UTF-16 code units.
%p	Void pointer (void *), printed in hexadecimal with the digits 0--9 and lowercase a--f, with a leading 0x.
%a	64-bit floating-point number (double), printed in scientific notation with a leading 0x and one hexadecimal digit before the decimal point using a lowercase p to introduce the exponent.
%A	64-bit floating-point number (double), printed in scientific notation with a leading 0X and one hexadecimal digit before the decimal point using a uppercase P to introduce the exponent.
%F	64-bit floating-point number (double), printed in decimal notation.

Length modifiers ^{(Table 2)}

Length modifier	Description
h	Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a short or unsigned short argument.
hh	Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a signed char or unsigned char argument.
l	Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a long or unsigned long argument.
ll, q	Length modifiers specifying that a following d, o, u, x, or X conversion specifier applies to a long long or unsigned long longargument.
L	Length modifier specifying that a following a, A, e, E, f, F, g, or G conversion specifier applies to a long double argument.
z	Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a size_t.
t	Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a ptrdiff_t.
j	Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a intmax_t or uintmax_t argument.

Length modifier example:

#include <limits.h>

// ...

NSString *text = [NSString stringWithFormat:@"Signed %hhd, Unsigned %hhu", CHAR_MIN, UCHAR_MAX];

Or in Swift:

let text = String(format: "Signed %hhd, Unsigned %hhu", CChar.min, CUnsignedChar.max)

Platform Dependencies

OS X uses several data types---NSInteger, NSUInteger,CGFloat, and CFIndex---to provide a consistent means of representing values in 32- and 64-bit environments. In a 32-bit environment, NSInteger and NSUInteger are defined as int and unsigned int, respectively. In 64-bit environments, NSIntegerand NSUInteger are defined as long and unsigned long, respectively. To avoid the need to use different printf-style type specifiers depending on the platform, you can use the specifiers shown in Table 3. Note that in some cases you may have to cast the value.

Table 3  Format specifiers for data types

Type	Format specifier	Considerations
NSInteger	%ld or %lx	Cast the value to long.
NSUInteger	%lu or %lx	Cast the value to unsigned long.
CGFloat	%f or %g	%f works for floats and doubles when formatting; but note the technique described below for scanning.
CFIndex	%ld or %lx	The same as NSInteger.
pointer	%p or %zx	%p adds 0x to the beginning of the output. If you don't want that, use %zx and no typecast.

The following example illustrates the use of %ld to format an NSInteger and the use of a cast.

NSInteger i = 42;
printf("%ld\n", (long)i);

In addition to the considerations mentioned in Table 3, there is one extra case with scanning: you must distinguish the types for float and double. You should use %f for float, %lf for double. If you need to use scanf (or a variant thereof) with CGFloat, switch to double instead, and copy the double to CGFloat.

CGFloat imageWidth;
double tmp;
sscanf (str, "%lf", &tmp);
imageWidth = tmp;

It is important to remember that %lf does not represent CGFloat correctly on either 32- or 64-bit platforms. This is unlike %ld, which works for long in all cases.

Answer 3

Swift 5

    let timeFormatter = DateFormatter()
    let dateFormat = DateFormatter.dateFormat(fromTemplate: "jm", 
                                    options: 0, locale: Locale.current)!
    timeFormatter.dateFormat  = dateFormat