Contents

IntegerFormatStyle

A structure that converts between integer values and their textual representations.

Declaration

struct IntegerFormatStyle<Value> where Value : BinaryInteger

Overview

Instances of IntegerFormatStyle create localized, human-readable text from BinaryInteger numbers and parse string representations of numbers into instances of BinaryInteger types. All of the Swift standard library’s integer types, such as Int and UInt32, conform to 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 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 formatted(_:) 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 number to create format styles within the call to the formatted(_:) 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

Topics

Creating an integer format style

Formatting integer values

Customizing style behavior

Acessing style locale

Applying currency styles

Applying measurement styles

Applying list styles

Creating attributed strings

Parsing integers

Supporting types

Default Implementations

See Also

Data formatting in Swift