Contents

Decimal.FormatStyle

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

Declaration

struct FormatStyle

Overview

Instances of Decimal.FormatStyle create localized, human-readable text from Decimal numbers and parse string representations of numbers into instances of Decimal.

Decimal.FormatStyle includes two nested types, Decimal.FormatStyle.Percent and Decimal.FormatStyle.Currency, for working with percentages and currencies, respectively. 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. Decimal.FormatStyle and Decimal.FormatStyle.Percent include a NumberFormatStyleConfiguration, and Decimal.FormatStyle.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 decimal values

Use the formatted() method to create a string representation of a decimal value using the default Decimal.FormatStyle configuration:

let formattedDefault = Decimal(12345.67).formatted()
// formattedDefault is "12,345.67" 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 decimal 0.1 represented in each of the available styles in the en_US locale:

let number: Decimal = 0.1

let formattedNumber = number.formatted(.number)
// formattedNumber is "0.1"

let formattedPercent = number.formatted(.percent)
// formattedPercent is "10%"

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

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: Decimal = 125000.12

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

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

Creating a decimal format style instance

The previous examples use static instances like number to create format styles within the call to the formatted(_:) method. You can also create a Decimal.FormatStyle instance and use it to repeatedly format different values by using the format(_:) method, as shown here:

let percentFormatStyle = Decimal.FormatStyle.Percent()

percentFormatStyle.format(0.5) // "50%"
percentFormatStyle.format(0.855) // "85.5%"
percentFormatStyle.format(1.0) // "100%"

Parsing decimal values

You can use Decimal.FormatStyle to parse strings into decimal values. You can define the format style within the type’s initializer or pass in a format style created outside the function. The following demonstrates both approaches:

let price = try? Decimal("$3,500.63",
                         format: .currency(code: "USD")) // 3500.63

let priceFormatStyle = Decimal.FormatStyle.Currency(code: "USD")
let salePrice = try? Decimal("$731.67",
                             format: priceFormatStyle) // 731.67

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: $49,525.99"
let matcher = Regex {
    OneOrMore(.any)
    ": "
    Capture {
        One(.localizedCurrency(code:Locale.Currency("USD"),
                               locale:Locale(identifier: "en_US")))
    }
}
let match = source.firstMatch(of: matcher)
let localizedDecimal = match?.1 // 49525.99

Topics

Creating a decimal format style

Customizing style behavior

Accesssing style locale

Applying currency styles

Applying measurement styles

Creating attributed strings

Parsing decimals

Supporting types

See Also

Data formatting in Swift