IntegerFormatStyle

struct IntegerFormatStyle<Value> where Value : BinaryInteger

Overview

Instances of IntegerFormatStyle create localized, human-readable text from doc://com.apple.documentation/documentation/swift/binaryinteger numbers and parse string representations of numbers into instances of doc://com.apple.documentation/documentation/swift/binaryinteger types. All of the Swift standard library’s integer types, such as doc://com.apple.documentation/documentation/swift/int and doc://com.apple.documentation/documentation/swift/uint32, conform to doc://com.apple.documentation/documentation/swift/binaryinteger, and therefore work with this format style.

IntegerFormatStyle includes two nested types, IntegerFormatStyle.Percent and IntegerFormatStyle.Currency, for working with percentages and currencies. Each format style includes a configuration that determines how it represents numeric values, for things like grouping, displaying signs, and variant presentations like scientific notation. IntegerFormatStyle and IntegerFormatStyle.Percent include a NumberFormatStyleConfiguration, and IntegerFormatStyle.Currency includes a CurrencyFormatStyleConfiguration. You can customize numeric formatting for a style by adjusting its backing configuration. The system automatically caches unique configurations of a format style to enhance performance.

Formatting integers

Use the doc://com.apple.documentation/documentation/swift/binaryinteger/formatted() method to create a string representation of an integer using the default IntegerFormatStyle configuration.

let formattedDefault = 123456.formatted()
// formattedDefault is "123,456" in en_US locale.
// Other locales may use different separator and grouping behavior.

You can specify a format style by providing an argument to the doc://com.apple.documentation/documentation/swift/binaryinteger/formatted(_:)-73k3e method. The following example shows the number 12345 represented in each of the available styles, in the en_US locale:

let number = 123456

let formattedNumber = number.formatted(.number)
// formattedNumber is "123,456".

let formattedPercent = number.formatted(.percent)
// formattedPercent is "123,456%".

let formattedCurrency = number.formatted(.currency(code: "USD"))
// formattedCurrency is "$123,456.00".

Each style provides methods for updating its numeric configuration, including the number of significant digits, grouping length, and more. You can specify a numeric configuration by calling as many of these methods as you need in any order you choose. The following example shows the same number with default and custom configurations:

let exampleNumber = 123456

let defaultFormatting = exampleNumber.formatted(.number)
// defaultFormatting is "125 000" for the "fr_FR" locale
// defaultFormatting is "125000" for the "jp_JP" locale
// defaultFormatting is "125,000" for the "en_US" locale

let customFormatting = exampleNumber.formatted(
.number
.grouping(.never)
.sign(strategy: .always()))
// customFormatting is "+123456"

Creating an integer format style instance

The previous examples use static factory methods like FormatStyle/number-7fxvo to create format styles within the call to the doc://com.apple.documentation/documentation/swift/binaryinteger/formatted(_:)-73k3e method. You can also create an IntegerFormatStyle instance and use it to repeatedly format different values with the format(_:) method:

let percentFormatStyle = IntegerFormatStyle<Int>.Percent()

percentFormatStyle.format(50) // "50%"
percentFormatStyle.format(85) // "85%"
percentFormatStyle.format(100) // "100%"

Parsing integers

You can use IntegerFormatStyle to parse strings into integer values. You can define the format style within the type’s initializer or pass in a format style you create prior to calling the method, as shown here:

let price = try? Int("$123,456",
format: .currency(code: "USD")) // 123456

let priceFormatStyle = IntegerFormatStyle<Int>.Currency(code: "USD")
let salePrice = try? Int("$120,000",
format: priceFormatStyle) // 120000

Matching regular expressions

Along with parsing numeric values in strings, you can use the Swift regular expression domain-specific language to match and capture numeric substrings. The following example defines a currency format style to match and capture a currency value using US dollars and en_US numeric conventions. The rest of the regular expression ignores any characters prior to a ": " sequence that precedes the currency substring.

import RegexBuilder

let source = "Payment due: $123,456"
let matcher = Regex {
OneOrMore(.any)
": "
Capture {
One(.localizedIntegerCurrency(code: Locale.Currency("USD"),
locale: Locale(identifier: "en_US")))
}
}
let match = source.firstMatch(of: matcher)
let localizedInteger = match?.1 // 123456