Contents

FloatingPointFormatStyle

A structure that converts between floating-point values and their textual representations.

Declaration

struct FloatingPointFormatStyle<Value> where Value : BinaryFloatingPoint

Overview

Instances of FloatingPointFormatStyle create localized, human-readable text from BinaryFloatingPoint numbers and parse string representations of numbers into instances of BinaryFloatingPoint types. All of the Swift standard library’s floating-point types, such as Double, Float, and Float80, conform to BinaryFloatingPoint, and therefore work with this format style.

FloatingPointFormatStyle includes two nested types, FloatingPointFormatStyle.Percent and FloatingPointFormatStyle.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. FloatingPointFormatStyle and FloatingPointFormatStyle.Percent include a NumberFormatStyleConfiguration, and FloatingPointFormatStyle.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 floating-point values

Use the formatted() method to create a string representation of a floating-point value using the default FloatingPointFormatStyle configuration.

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

let number = 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 = 123456.78

let defaultFormatting = exampleNumber.formatted(.number)
// defaultFormatting is "123 456,78" for the "fr_FR" locale.
// defaultFormatting is "123,456.78" for the "en_US" locale.

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

Creating a floating-point 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 a FloatingPointFormatStyle instance and use it to repeatedly format different values, with the format(_:) method:

let percentFormatStyle = FloatingPointFormatStyle<Double>.Percent()

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

Parsing floating-point values

You can use FloatingPointFormatStyle to parse strings into floating-point values. You can define the format style within the type’s initializer or pass in a format style created outside the function, as shown here:

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

let priceFormatStyle = FloatingPointFormatStyle<Double>.Currency(code: "USD")
let salePrice = try? Double("$731.67",
                             format: priceFormatStyle) // 731.67

Matching regular expressions

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

import RegexBuilder
let source = "Percentage complete: 55.1%"
let matcher = Regex {
    OneOrMore(.any)
    ": "
    Capture {
        One(.localizedDoublePercentage(locale: Locale(identifier: "en_US")))
    }
}
let match = source.firstMatch(of: matcher)
let localizedPercentage = match?.1
print("\(localizedPercentage!)") // 0.551

Topics

Creating a floating-point format style

Customizing style behavior

Accessing style locale

Applying currency styles

Applying measurement styles

Applying list styles

Creating attributed strings

Parsing floating-point numbers

Supporting types

See Also

Data formatting in Swift