FloatingPointFormatStyle

struct FloatingPointFormatStyle<Value> where Value : BinaryFloatingPoint

Overview

Instances of FloatingPointFormatStyle create localized, human-readable text from doc://com.apple.documentation/documentation/swift/binaryfloatingpoint numbers and parse string representations of numbers into instances of doc://com.apple.documentation/documentation/swift/binaryfloatingpoint types. All of the Swift standard library’s floating-point types, such as doc://com.apple.documentation/documentation/swift/double, doc://com.apple.documentation/documentation/swift/float, and doc://com.apple.documentation/documentation/swift/float80, conform to doc://com.apple.documentation/documentation/swift/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 doc://com.apple.documentation/documentation/swift/binaryfloatingpoint/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 doc://com.apple.documentation/documentation/swift/binaryfloatingpoint/formatted(_:)-4ksqj 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 FormatStyle/number-8c8rj to create format styles within the call to the doc://com.apple.documentation/documentation/swift/binaryfloatingpoint/formatted(_:)-4ksqj 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