A structure that converts between decimal values and their textual representations.
Members (15)
get · iOS 15.0+
attributed
TypeScript
get attributed(): Decimal_FormatStyle_Attributed
Swift declaration
var attributed: Decimal.FormatStyle.Attributed { get }
An attributed format style based on the decimal format style.
Use this modifier to create a ``Decimal/FormatStyle/Attributed`` instance, which formats
values as ``AttributedString`` instances. These attributed strings contain attributes from
the ``AttributeScopes/FoundationAttributes/NumberFormatAttributes`` attribute scope. Use
these attributes to determine which runs of the attributed string represent different
parts of the formatted value.
The following example finds runs of the attributed string that represent different parts
of a formatted currency, and adds additional attributes like
``AttributeScopes/SwiftUIAttributes/foregroundColor`` and
``AttributeScopes/FoundationAttributes/inlinePresentationIntent``.
```swift
func attributedPrice(price: Decimal) -> AttributedString {
var attributedPrice = price.formatted(
.currency(code: "USD")
.attributed)
for run in attributedPrice.runs {
if run.attributes.numberSymbol == .currency ||
run.attributes.numberSymbol == .decimalSeparator {
attributedPrice[run.range].foregroundColor = .red
}
if run.attributes.numberPart == .integer ||
run.attributes.numberPart == .fraction {
attributedPrice[run.range].inlinePresentationIntent = [.stronglyEmphasized]
}
}
return attributedPrice
}
```
User interface frameworks like SwiftUI can use these attributes when presenting the
attributed string.
get · iOS 15.0+
parseStrategy
TypeScript
get parseStrategy(): Decimal_ParseStrategy<Decimal_FormatStyle>
Swift declaration
var parseStrategy: Decimal.ParseStrategy<Decimal.FormatStyle> { get }
Modifies the format style to use the specified decimal separator display strategy.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and a second style that uses the ``NumberFormatStyleConfiguration/DecimalSeparatorDisplayStrategy/always``
strategy. It then applies each style to an array of decimal values that don't have a
fractional part. The formatting that the modified style applies adds a trailing decimal
separator in all cases.
```swift
let defaultStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let alwaysStyle = defaultStyle.decimalSeparator(strategy: .always)
let nums: [Decimal] = [100.0, 1000.0, 10000.0, 100000.0, 1000000.0]
let defaultNums = nums.map { defaultStyle.format($0) } // ["100", "1,000", "10,000", "100,000", "1,000,000"]
let alwaysNums = nums.map { alwaysStyle.format($0) } // ["100.", "1,000.", "10,000.", "100,000.", "1,000,000."]
```
- Parameter strategy: The decimal separator display strategy to apply to the format style.
- Returns: A decimal format style modified to use the specified decimal separator display strategy.
Modifies the format style to use the specified sign display strategy for displaying or omitting sign symbols.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and a second style that displays a sign for all values except zero. It then applies each
style to an array of decimal values. The formatting that the modified style applies adds
the negative (`-`) or positive (`+`) sign to all the numbers.
```swift
let defaultStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let alwaysStyle = defaultStyle.sign(strategy: .always(includingZero: false))
let nums: [Decimal] = [-2.1, -1.2, 0, 1.4, 2.5]
let defaultNums = nums.map { defaultStyle.format($0) } // ["-2.1", "-1.2", "0", "1.4", "2.5"]
let alwaysNums = nums.map { alwaysStyle.format($0) } // ["-2.1", "-1.2", "0", "+1.4", "+2.5"]
```
- Parameter strategy: The sign display strategy to apply to the format style.
- Returns: A decimal format style modified to use the specified sign display strategy.
Modifies the format style to use the specified scale.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and a second style that scales by a `multiplicand` of `0.001`. It then applies each
style to an array of decimal values. The formatting that the modified style applies
expresses each value in terms of one-thousandths.
```swift
let defaultStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let scaledStyle = defaultStyle.scale(0.001)
let nums: [Decimal] = [100.1, 1000.2, 10000.3, 100000.4, 1000000.5]
let defaultNums = nums.map { defaultStyle.format($0) } // ["100.1", "1,000.2", "10,000.3", "100,000.4", "1,000,000.5"]
let scaledNums = nums.map { scaledStyle.format($0) } // ["0.1001", "1.0002", "10.0003", "100.0004", "1,000.0005"]
```
- Parameter multiplicand: The multiplicand to apply to the format style.
- Returns: A decimal format style modified to use the specified scale.
method · iOS 15.0+
format
TypeScript
format(value: Decimal): string
Swift declaration
func format(_ value: Decimal) -> String
Formats a decimal value using this style.
Use this method when you want to create a single style instance and then use it to format
multiple decimal values. The following example creates a style that uses the `en_US` locale
and then adds the ``NumberFormatStyleConfiguration/Notation/scientific`` modifier. It then
applies this style to all of the decimal values in an array.
```swift
let scientificStyle = Decimal.FormatStyle(
locale: Locale(identifier: "en_US"))
.notation(.scientific)
let nums: [Decimal] = [100.1, 1000.2, 10000.3, 100000.4, 1000000.5]
let formattedNums = nums.map { scientificStyle.format($0) } // ["1.001E2", "1.0002E3", "1.00003E4", "1.000004E5", "1E6"]
```
To format a single value, use the ``Decimal`` instance method ``Decimal/formatted(_:)``,
passing in an instance of ``Decimal/FormatStyle``, or ``Decimal/formatted()`` to use a
default style.
- Parameter value: The decimal value to format.
- Returns: A string representation of `value` formatted according to the style's configuration.
get · iOS 15.0+
locale
TypeScript
get locale(): Locale
Swift declaration
var locale: Locale
The locale of the format style.
Use the ``locale(_:)`` modifier to create a copy of this format style with a different locale.
set · iOS 15.0+
locale
TypeScript
set locale(value: Locale)
Swift declaration
var locale: Locale
The locale of the format style.
Use the ``locale(_:)`` modifier to create a copy of this format style with a different locale.
init · iOS 15.0+
init
TypeScript
static init(locale?: Locale): Decimal_FormatStyle
Swift declaration
init(locale: Locale = .autoupdatingCurrent)
Creates a decimal format style that uses the given locale.
Create a ``Decimal/FormatStyle`` instance when you intend to apply a given style to multiple
decimal values. The following example creates a style that uses the `en_US` locale, which
uses three-based grouping and comma separators. It then applies this style to all the
``Decimal`` values in an array.
```swift
let enUSstyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let decimals: [Decimal] = [100.1, 1000.2, 10000.3, 100000.4, 1000000.5]
let formattedDecimals = decimals.map { enUSstyle.format($0) } // ["100.1", "1,000.2", "10,000.3", "100,000.4", "1,000,000.5"]
```
To format a single integer, you can use the ``Decimal`` instance method ``Decimal/formatted(_:)``
passing in an instance of ``Decimal/FormatStyle``.
- Parameter locale: The locale to use when formatting or parsing decimal values.
Defaults to `Locale.autoupdatingCurrent`.
Modifies the format style to use the specified locale.
Use this modifier to change the locale that an existing format style uses. To instead
determine the locale that this format style uses, use the ``locale`` property.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and applies the ``notation(_:)`` modifier to use compact name notation. Next, the sample
creates a second style based on this, but that uses the German (`DE`) locale. It then
applies each style to an array of decimal values.
```swift
let compactStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
.notation(.compactName)
let germanStyle = compactStyle.locale(Locale(identifier: "DE"))
let nums: [Decimal] = [100, 1000, 10000, 100000, 1000000]
let enUSCompactNums = nums.map { compactStyle.format($0) } // ["100", "1K", "10K", "100K", "1M"]
let deCompactNums = nums.map { germanStyle.format($0) } // ["100", "1000", "10.000", "100.000", "1 Mio."]
```
- Parameter locale: The locale to apply to the format style.
- Returns: A decimal format style modified to use the provided locale.
Modifies the format style to use the specified rounding rule and increment.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and a modified style that rounds integers to the nearest multiple of `100`. It then
formats the value `1999.95` using these format styles.
```swift
let defaultStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let roundedStyle = defaultStyle.rounded(rule: .toNearestOrEven,
increment: 100)
let num: Decimal = 1999.95
let defaultNum = num.formatted(defaultStyle) // "1,999.95"
let roundedNum = num.formatted(roundedStyle) // "2,000"
```
- Parameters:
- rule: The rounding rule to apply to the format style.
- increment: A multiple by which the formatter rounds the fractional part. The formatter
produces a value that is an even multiple of this increment. If this parameter is
`nil` (the default), the formatter doesn't apply an increment.
- Returns: A decimal format style modified to use the specified rounding rule and increment.
Modifies the format style to use the specified grouping.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and a second style that never uses grouping. It then applies each style to an array of
decimal values. The formatting that the modified style applies eliminates the three-digit
grouping usually performed for the `en_US` locale.
```swift
let defaultStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let neverStyle = defaultStyle.grouping(.never)
let nums: [Decimal] = [100.1, 1000.2, 10000.3, 100000.4, 1000000.5]
let defaultNums = nums.map { defaultStyle.format($0) } // ["100.1", "1,000.2", "10,000.3", "100,000.4", "1,000,000.5"]
let neverNums = nums.map { neverStyle.format($0) } // ["100.1", "1000.2", "10000.3", "100000.4", "1000000.5"]
```
- Parameter group: The grouping to apply to the format style.
- Returns: A decimal format style modified to use the specified grouping.
Modifies the format style to use the specified notation.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and a second style that uses scientific notation style. It then applies each style to
an array of decimal values.
```swift
let defaultStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let scientificStyle = defaultStyle.notation(.scientific)
let nums: [Decimal] = [100.1, 1000.2, 10000.3, 100000.4, 1000000.5]
let defaultNums = nums.map { defaultStyle.format($0) } // ["100.1", "1,000.2", "10,000.3", "100,000.4", "1,000,000.5"]
let scientificNums = nums.map { scientificStyle.format($0) } // ["1.001E2", "1.0002E3", "1.00003E4", "1.000004E5", "1E6"]
```
- Parameter notation: The notation to apply to the format style.
- Returns: A decimal format style modified to use the specified notation.
Matches the input string within the specified bounds, beginning at the given index.
Don't call this method directly. Regular expression matching and capture calls it
automatically when matching substrings.
- Parameters:
- input: An input string to match against.
- index: The index within `input` at which to begin searching.
- bounds: The bounds within `input` in which to search.
- Returns: The upper bound where the match terminates and a matched instance, or `nil` if there isn't a match.
Modifies the format style to use the specified precision.
The ``NumberFormatStyleConfiguration/Precision`` type lets you specify fixed numbers of digits
to show for a number's integer and fractional parts. You can also set a fixed number of
significant digits.
The following example creates a default ``Decimal/FormatStyle`` for the `en_US` locale,
and a second style that uses a maximum of four significant digits. It then applies each
style to an array of decimal values. The formatting applied by the modified style truncates
precision to `0` after the fourth most-significant digit.
```swift
let defaultStyle = Decimal.FormatStyle(locale: Locale(identifier: "en_US"))
let precisionStyle = defaultStyle.precision(.significantDigits(1...4))
let nums: [Decimal] = [123.1, 1234.1, 12345.1, 123456.1, 1234567.1]
let defaultNums = nums.map { defaultStyle.format($0) } // ["123.1", "1,234.1", "12,345.1", "123,456.1", "1,234,567.1"]
let precisionNums = nums.map { precisionStyle.format($0) } // ["123.1", "1,234", "12,350", "123,500", "1,235,000"]
```
- Parameter p: The precision to apply to the format style.
- Returns: A decimal format style modified to use the specified precision.
