<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 12.0.0 -",
    "tvOS: 15.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 8.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/Decimal/FormatStyle",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "s:So9NSDecimala10FoundationE11FormatStyleV"
  },
  "title" : "Decimal.FormatStyle"
}
-->

# Decimal.FormatStyle

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

```
struct FormatStyle
```

## Overview

Instances of [`Decimal.FormatStyle`](/documentation/Foundation/Decimal/FormatStyle) create localized, human-readable text from [`Decimal`](/documentation/Foundation/Decimal) numbers and parse string representations of numbers into instances of [`Decimal`](/documentation/Foundation/Decimal).

[`Decimal.FormatStyle`](/documentation/Foundation/Decimal/FormatStyle) includes two nested types, [`Decimal.FormatStyle.Percent`](/documentation/Foundation/Decimal/FormatStyle/Percent) and [`Decimal.FormatStyle.Currency`](/documentation/Foundation/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`](/documentation/Foundation/Decimal/FormatStyle) and [`Decimal.FormatStyle.Percent`](/documentation/Foundation/Decimal/FormatStyle/Percent) include a [`NumberFormatStyleConfiguration`](/documentation/Foundation/NumberFormatStyleConfiguration), and [`Decimal.FormatStyle.Currency`](/documentation/Foundation/Decimal/FormatStyle/Currency) includes a [`CurrencyFormatStyleConfiguration`](/documentation/Foundation/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.

> Note:
> Foundation provides other format style types for working with the numeric types that the Swift standard library defines. ``doc://com.apple.foundation/documentation/Foundation/IntegerFormatStyle`` works with types that conform to <doc://com.apple.documentation/documentation/Swift/BinaryInteger>, and ``doc://com.apple.foundation/documentation/Foundation/FloatingPointFormatStyle`` works with types that conform to <doc://com.apple.documentation/documentation/Swift/BinaryFloatingPoint>.

### Formatting decimal values

Use the [`formatted()`](/documentation/Foundation/Decimal/formatted()) method to create a string representation of a decimal value using the default [`Decimal.FormatStyle`](/documentation/Foundation/Decimal/FormatStyle) configuration:

```swift
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(_:)`](/documentation/Foundation/Decimal/formatted(_:)) method. The following example shows the decimal `0.1` represented in each of the available styles in the `en_US` locale:

```swift
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:

```swift
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`](/documentation/Foundation/FormatStyle/number-3luf2) to create format styles within the call to the [`formatted(_:)`](/documentation/Foundation/Decimal/formatted(_:)) method. You can also create a [`Decimal.FormatStyle`](/documentation/Foundation/Decimal/FormatStyle) instance and use it to repeatedly format different values by using the [`format(_:)`](/documentation/Foundation/Decimal/FormatStyle/format(_:)) method, as shown here:

```swift
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`](/documentation/Foundation/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:

```swift
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.

```swift
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

[`init(locale:)`](/documentation/Foundation/Decimal/FormatStyle/init(locale:))

Creates a decimal format style that uses the given locale.

### Formatting decimal values

[`format(_:)`](/documentation/Foundation/Decimal/FormatStyle/format(_:))

Formats a decimal value using this style.

### Customizing style behavior

[`decimalSeparator(strategy:)`](/documentation/Foundation/Decimal/FormatStyle/decimalSeparator(strategy:))

Modifies the format style to use the specified decimal separator display strategy.

[`grouping(_:)`](/documentation/Foundation/Decimal/FormatStyle/grouping(_:))

Modifies the format style to use the specified grouping.

[`locale(_:)`](/documentation/Foundation/Decimal/FormatStyle/locale(_:))

Modifies the format style to use the specified locale.

[`notation(_:)`](/documentation/Foundation/Decimal/FormatStyle/notation(_:))

Modifies the format style to use the specified notation.

[`precision(_:)`](/documentation/Foundation/Decimal/FormatStyle/precision(_:))

Modifies the format style to use the specified precision.

[`rounded(rule:increment:)`](/documentation/Foundation/Decimal/FormatStyle/rounded(rule:increment:))

Modifies the format style to use the specified rounding rule and increment.

[`scale(_:)`](/documentation/Foundation/Decimal/FormatStyle/scale(_:))

Modifies the format style to use the specified scale.

[`sign(strategy:)`](/documentation/Foundation/Decimal/FormatStyle/sign(strategy:))

Modifies the format style to use the specified sign display strategy for displaying or omitting sign symbols.

[`Configuration`](/documentation/Foundation/Decimal/FormatStyle/Configuration)

The type the format style uses for configuration settings.

[`NumberFormatStyleConfiguration`](/documentation/Foundation/NumberFormatStyleConfiguration)

Configuration settings for formatting numbers of different types.

### Accesssing style locale

[`locale`](/documentation/Foundation/Decimal/FormatStyle/locale)

The locale of the format style.

### Applying currency styles

[`Currency`](/documentation/Foundation/Decimal/FormatStyle/Currency)

A format style that converts between decimal currency values and their textual representations.

### Applying measurement styles

[`FormatStyle`](/documentation/Foundation/Measurement/FormatStyle)

A type that provides localized representations of measurements.

### Applying list styles

### Creating attributed strings

[`attributed`](/documentation/Foundation/Decimal/FormatStyle/attributed-swift.property)

An attributed format style based on the decimal format style.

[`Attributed`](/documentation/Foundation/Decimal/FormatStyle/Attributed-swift.struct)

A format style that converts integers into attributed strings.

### Parsing decimals

[`parseStrategy`](/documentation/Foundation/Decimal/FormatStyle/parseStrategy)

The parse strategy that this format style uses.

[`ParseStrategy`](/documentation/Foundation/Decimal/ParseStrategy)

A parse strategy for creating decimal values from formatted strings.

### Locating decimals with regular expressions

[`consuming(_:startingAt:in:)`](/documentation/Foundation/Decimal/FormatStyle/consuming(_:startingAt:in:))

Process the input string within the specified bounds, beginning at the given index, and return the end position (upper bound) of the match and the produced output.

### Supporting types

[`Currency`](/documentation/Foundation/Decimal/FormatStyle/Currency)

A format style that converts between decimal currency values and their textual representations.

[`Percent`](/documentation/Foundation/Decimal/FormatStyle/Percent)

A format style that converts between decimal percentage values and their textual representations.

## Relationships

### Conforms To

[`Encodable`](/documentation/Swift/Encodable)

[`Decodable`](/documentation/Swift/Decodable)

[`Copyable`](/documentation/Swift/Copyable)

[`CustomConsumingRegexComponent`](/documentation/Swift/CustomConsumingRegexComponent)

[`Equatable`](/documentation/Swift/Equatable)

[`FormatStyle`](/documentation/Foundation/FormatStyle)

[`Sendable`](/documentation/Swift/Sendable)

[`Hashable`](/documentation/Swift/Hashable)

[`Escapable`](/documentation/Swift/Escapable)

[`RegexComponent`](/documentation/Swift/RegexComponent)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`ParseableFormatStyle`](/documentation/Foundation/ParseableFormatStyle)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)