<!--
{
  "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/FormatStyle",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "s:10Foundation11FormatStyleP"
  },
  "title" : "FormatStyle"
}
-->

# FormatStyle

A type that converts a given data type into a representation in another type, such as a string.

```
protocol FormatStyle<FormatInput, FormatOutput> : Decodable, Encodable, Hashable
```

## Overview

Types conforming to the [`FormatStyle`](/documentation/Foundation/FormatStyle) protocol take their input type and produce formatted instances of their output type. The formatting process accounts for locale-specific conventions, like grouping and separators for numbers, and presentation of units for measurements. The format styles Foundation provides produce their output as <doc://com.apple.documentation/documentation/Swift/String> or [`AttributedString`](/documentation/Foundation/AttributedString) instances. You can also create custom styles that format their output as any type, like XML or JSON [`Data`](/documentation/Foundation/Data) or an image.

There are two basic approaches to using a [`FormatStyle`](/documentation/Foundation/FormatStyle):

- Create an instance of a type that conforms to [`FormatStyle`](/documentation/Foundation/FormatStyle) and apply it to one or more instances of the input type, by calling the style’s [`format(_:)`](/documentation/Foundation/FormatStyle/format(_:)) method. Use this when you want to customize a style once and apply it repeatedly to many instances.
- Pass an instance of a type that conforms to [`FormatStyle`](/documentation/Foundation/FormatStyle) to the data type’s `formatted(_:)` method, which takes the style as a parameter. Use this for one-off formatting scenarios, or when you want to apply different format styles to the same data value. For the simplest cases, most types that support formatting also have a no-argument `formatted()` method that applies a locale-appropriate default format style.

Foundation provides format styles for integers ([`IntegerFormatStyle`](/documentation/Foundation/IntegerFormatStyle)), floating-point numbers ([`FloatingPointFormatStyle`](/documentation/Foundation/FloatingPointFormatStyle)), decimals ([`Decimal.FormatStyle`](/documentation/Foundation/Decimal/FormatStyle)), measurements ([`Measurement.FormatStyle`](/documentation/Foundation/Measurement/FormatStyle)), arrays ([`ListFormatStyle`](/documentation/Foundation/ListFormatStyle)), and more. The “Conforming types” section below shows all the format styles available from Foundation and any system frameworks that implement the [`FormatStyle`](/documentation/Foundation/FormatStyle) protocol. The numeric format styles also provide supporting format styles to format currency and percent values, like [`IntegerFormatStyle.Currency`](/documentation/Foundation/IntegerFormatStyle/Currency) and [`Decimal.FormatStyle.Percent`](/documentation/Foundation/Decimal/FormatStyle/Percent).

### Modifying a format style

Format styles include modifier methods that return a new format style with an adjusted behavior. The following example creates an [`IntegerFormatStyle`](/documentation/Foundation/IntegerFormatStyle), then applies modifiers to round values down to the nearest 1,000 and applies formatting appropriate to the `fr_FR` locale:

```swift
let style = IntegerFormatStyle<Int>()
    .rounded(rule: .down, increment: 1000)
    .locale(Locale(identifier: "fr_FR"))
let rounded = 123456789.formatted(style) // "123 456 000"
```

Foundation caches identical instances of a customized format style, so you don’t need to pass format style instances around unrelated parts of your app’s source code.

### Accessing static instances

Types that conform to [`FormatStyle`](/documentation/Foundation/FormatStyle) typically extend the base protocol with type properties or type methods to provide convenience instances. These are available for use in a data type’s `formatted(_:)` method when the format style’s input type matches the data type. For example, the various numeric format styles define `number` properties with generic constraints to match the different numeric types (<doc://com.apple.documentation/documentation/Swift/Double>, <doc://com.apple.documentation/documentation/Swift/Int>, <doc://com.apple.documentation/documentation/Swift/Float16>, and so on).

To see how this works, consider this example of a default formatter for an <doc://com.apple.documentation/documentation/Swift/Int> value. Because `123456789` is a <doc://com.apple.documentation/documentation/Swift/BinaryInteger>, its <doc://com.apple.documentation/documentation/Swift/BinaryInteger/formatted(_:)-4qd73> method accepts an [`IntegerFormatStyle`](/documentation/Foundation/IntegerFormatStyle) parameter. The following example shows the style’s default behavior in the `en_US` locale.

```swift
let formatted = 123456789.formatted(IntegerFormatStyle()) // "123,456,789"
```

[`IntegerFormatStyle`](/documentation/Foundation/IntegerFormatStyle) extends [`FormatStyle`](/documentation/Foundation/FormatStyle) with multiple type properties called `number`, each of which is an [`IntegerFormatStyle`](/documentation/Foundation/IntegerFormatStyle) instance; these properties differ by which <doc://com.apple.documentation/documentation/Swift/BinaryInteger>-conforming type they take as input. Since one of these statically-defined properties ([`number`](/documentation/Foundation/FormatStyle/number-7fxvo)) takes <doc://com.apple.documentation/documentation/Swift/Int> as its input, you can use this type property instead of instantiating a new format style instance. Using dot notation to access this property on the inferred [`FormatStyle`](/documentation/Foundation/FormatStyle) makes the call point much easier to read, as seen here:

```swift
let formatted = 123456789.formatted( .number) // "123,456,789"
```

Furthermore, since you can customize these statically-accessed format style instances, you can rewrite the example from the previous section without instantiating a new [`IntegerFormatStyle`](/documentation/Foundation/IntegerFormatStyle), like this:

```swift
let rounded = 123456789.formatted( .number
    .rounded(rule: .down, increment: 1000)
    .locale(Locale(identifier: "fr_FR"))) // "123 456 000"
```

### Parsing with a format style

To perform the opposite conversion — from formatted output type to input data type — some format styles provide a corresponding [`ParseStrategy`](/documentation/Foundation/ParseStrategy) type. These format styles typically expose an instance of this type as a variable, called `parseStrategy`.

You can use a [`ParseStrategy`](/documentation/Foundation/ParseStrategy) one of two ways:

- Initialize the data type by calling an initializer of that type that takes a formatted instance and a parse strategy as parameters. For example, you can create a [`Decimal`](/documentation/Foundation/Decimal) from a formatted string with the initializer [`init(_:format:lenient:)`](/documentation/Foundation/Decimal/init(_:format:lenient:)-6fk71).
- Create a parse strategy and call its [`parse(_:)`](/documentation/Foundation/ParseStrategy/parse(_:)) method on one or more formatted instances.

## Topics

### Performing formatting

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

Formats a value, using this style.

### Setting style Locale

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

Modifies the format style to use the specified locale.

### Applying numeric styles for integers

[`number`](/documentation/Foundation/FormatStyle/number-7fxvo)

A style for formatting the Swift default integer type.

[`number`](/documentation/Foundation/FormatStyle/number-4ttgp)

A style for formatting the Swift unsigned integer type.

[`number`](/documentation/Foundation/FormatStyle/number-5hzgj)

A style for formatting 8-bit signed integers.

[`number`](/documentation/Foundation/FormatStyle/number-1o8fx)

A style for formatting 16-bit signed integers.

[`number`](/documentation/Foundation/FormatStyle/number-4cj49)

A style for formatting 32-bit signed integers.

[`number`](/documentation/Foundation/FormatStyle/number-3925i)

A style for formatting 64-bit signed integers.

[`number`](/documentation/Foundation/FormatStyle/number-8fms6)

A style for formatting 8-bit unsigned integers.

[`number`](/documentation/Foundation/FormatStyle/number-fak0)

A style for formatting 16-bit unsigned integers.

[`number`](/documentation/Foundation/FormatStyle/number-13mra)

A style for formatting 32-bit unsigned integers.

[`number`](/documentation/Foundation/FormatStyle/number-iyry)

A style for formatting 64-bit unsigned integers.

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

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

### Applying numeric styles for floating-point values

[`number`](/documentation/Foundation/FormatStyle/number-432x3)

A style for formatting the Swift standard single-precision floating-point type.

[`number`](/documentation/Foundation/FormatStyle/number-8c8rj)

A style for formatting the Swift standard double-precision floating-point type.

[`number`](/documentation/Foundation/FormatStyle/number-3qe2o)

A style for formatting 16-bit floating-point values.

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

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

### Applying numeric styles for decimals

[`number`](/documentation/Foundation/FormatStyle/number-3luf2)

A style for formatting decimal values.

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

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

### Applying percentage styles for integers

[`percent`](/documentation/Foundation/FormatStyle/percent-cl9k)

A style for formatting signed integer types in Swift as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-9pj79)

A style for formatting signed integer types in Swift as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-7r4rl)

A style for formatting 8-bit signed integers as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-3qjzh)

A style for formatting 16-bit signed integers as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-1f0q)

A style for formatting 32-bit signed integers as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-934se)

A style for formatting 64-bit signed integers as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-8izzv)

A style for formatting 8-bit unsigned integers as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-4kdme)

A style for formatting 16-bit unsigned integers as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-2f11j)

A style for formatting 32-bit unsigned integers as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-8bxla)

A style for formatting 64-bit unsigned integers as a percent representation.

[`IntegerFormatStyle.Percent`](/documentation/Foundation/IntegerFormatStyle/Percent)

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

### Applying percentage styles for floating-point values

[`percent`](/documentation/Foundation/FormatStyle/percent-2gva1)

A style for formatting the Swift standard single-precision floating-point type as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-6cwuv)

A style for formatting the Swift standard single-precision floating-point type as a percent representation.

[`percent`](/documentation/Foundation/FormatStyle/percent-grss)

A style for formatting 16-bit floating-point values as a percent representation.

[`FloatingPointFormatStyle.Percent`](/documentation/Foundation/FloatingPointFormatStyle/Percent)

A format style that converts between floating-point percentage values and their textual representations.

### Applying percentage styles for decimals

[`percent`](/documentation/Foundation/FormatStyle/percent-4knsm)

A style for formatting decimal values as a percent represntation.

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

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

### Applying date and time styles

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

A style for formatting a date and time.

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

A structure that creates a locale-appropriate string representation of a date instance and converts strings of dates and times into date instances.

[`Date.ISO8601FormatStyle`](/documentation/Foundation/Date/ISO8601FormatStyle)

A type that converts between dates and their ISO-8601 string representations.

[`verbatim(_:locale:timeZone:calendar:)`](/documentation/Foundation/FormatStyle/verbatim(_:locale:timeZone:calendar:))

Returns a style for formatting a date with an explicitly-specified style.

[`Date.VerbatimFormatStyle`](/documentation/Foundation/Date/VerbatimFormatStyle)

A style that formats a date with an explicitly-specified style.

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

A style for formatting a date interval.

[`Date.IntervalFormatStyle`](/documentation/Foundation/Date/IntervalFormatStyle)

A format style that creates string representations of date intervals.

[`relative(presentation:unitsStyle:)`](/documentation/Foundation/FormatStyle/relative(presentation:unitsStyle:))

Returns a style for formatting a date as relative to the current date.

[`Date.RelativeFormatStyle`](/documentation/Foundation/Date/RelativeFormatStyle)

A format style that forms locale-aware string representations of a relative date or time.

[`components(style:fields:)`](/documentation/Foundation/FormatStyle/components(style:fields:))

Returns a style for formatting a date interval in terms of specific date components.

[`Date.ComponentsFormatStyle`](/documentation/Foundation/Date/ComponentsFormatStyle)

A style for formatting a date interval in terms of specific date components.

### Applying duration styles

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

A style for formatting a duration expressed as a range of dates.

[`Date.ComponentsFormatStyle`](/documentation/Foundation/Date/ComponentsFormatStyle)

A style for formatting a date interval in terms of specific date components.

[`time(pattern:)`](/documentation/Foundation/FormatStyle/time(pattern:))

Returns a style for formatting a duration using a provided pattern.

[`units(allowed:width:maximumUnitCount:zeroValueUnits:valueLength:fractionalPart:)`](/documentation/Foundation/FormatStyle/units(allowed:width:maximumUnitCount:zeroValueUnits:valueLength:fractionalPart:))

Returns a style for formatting a duration that uses the specified units.

[`units(allowed:width:maximumUnitCount:zeroValueUnits:valueLengthLimits:fractionalPart:)`](/documentation/Foundation/FormatStyle/units(allowed:width:maximumUnitCount:zeroValueUnits:valueLengthLimits:fractionalPart:))

Returns a style for formatting a duration range that uses the specified units, with padding/truncating behavior defined as a range.

### Applying currency styles

[`currency(code:)`](/documentation/Foundation/FormatStyle/currency(code:)-is0v)

Returns a format style to use integer currency notation.

[`currency(code:)`](/documentation/Foundation/FormatStyle/currency(code:)-1yg68)

Returns a format style to use floating-point currency notation.

[`currency(code:)`](/documentation/Foundation/FormatStyle/currency(code:)-6fhr2)

Returns a format style to use decimal currency notation.

### Applying measurement styles

[`measurement(width:usage:numberFormatStyle:)`](/documentation/Foundation/FormatStyle/measurement(width:usage:numberFormatStyle:))

Returns a format style to format measurement units.

[`measurement(width:usage:hidesScaleName:numberFormatStyle:)`](/documentation/Foundation/FormatStyle/measurement(width:usage:hidesScaleName:numberFormatStyle:))

Returns a format style to format temperature units.

### Applying person name styles

[`name(style:)`](/documentation/Foundation/FormatStyle/name(style:))

Returns a format style to use the given name style for formatting a name from its components.

### Applying list styles

[`list(memberStyle:type:width:)`](/documentation/Foundation/FormatStyle/list(memberStyle:type:width:))

Returns a format style to format a list of items.

[`list(type:width:)`](/documentation/Foundation/FormatStyle/list(type:width:))

Returns a format style to format a list of strings.

### Applying byte-count styles

[`byteCount(style:allowedUnits:spellsOutZero:includesActualByteCount:)`](/documentation/Foundation/FormatStyle/byteCount(style:allowedUnits:spellsOutZero:includesActualByteCount:)-59ep0)

Returns a format style to format a data storage value.

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

A format style that provides string representations of byte counts.

[`byteCount(style:allowedUnits:spellsOutZero:includesActualByteCount:)`](/documentation/Foundation/FormatStyle/byteCount(style:allowedUnits:spellsOutZero:includesActualByteCount:)-ev0u)

Returns a format style to format a data storage value represented with Foundation’s measurement type.

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

A format style that provides string representations of byte counts, expressed as measurements of information storage.

### Applying URL styles

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

A style for formatting a URL.

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

A structure that converts between URL instances and their textual representations.

### Declaring input and output types

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

The type this format style accepts as input.

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

The type this format style produces as output.


---

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)