<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/Formatter",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSFormatter"
  },
  "title" : "Formatter"
}
-->

# Formatter

An abstract class that declares an interface for objects that create, interpret, and validate the textual representation of values.

```
class Formatter
```

## Overview

The Foundation framework provides several concrete subclasses of [`Formatter`](/documentation/Foundation/Formatter), including [`ByteCountFormatter`](/documentation/Foundation/ByteCountFormatter), [`DateFormatter`](/documentation/Foundation/DateFormatter), [`DateComponentsFormatter`](/documentation/Foundation/DateComponentsFormatter), [`DateIntervalFormatter`](/documentation/Foundation/DateIntervalFormatter), [`MeasurementFormatter`](/documentation/Foundation/MeasurementFormatter), [`NumberFormatter`](/documentation/Foundation/NumberFormatter), and [`PersonNameComponentsFormatter`](/documentation/Foundation/PersonNameComponentsFormatter).

> Tip:
> In Swift, you can use implementations of ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` rather than ``doc://com.apple.foundation/documentation/Foundation/Formatter``. The ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` instances, so you don’t need to pass them around your app, or risk wasting memory with duplicate formatters.

### Subclassing Notes

[`Formatter`](/documentation/Foundation/Formatter) is intended for subclassing. A custom formatter can restrict the input and enhance the display of data in novel ways. For example, you could have a custom formatter that ensures that serial numbers entered by a user conform to predefined formats. Before you decide to create a custom formatter, make sure that you cannot configure the public subclasses to satisfy your requirements.

For instructions on how to create your own custom formatter, see [Creating a Custom Formatter](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DataFormatting/Articles/CreatingACustomFormatter.html#//apple_ref/doc/uid/20000196).

## Topics

### Creating Formatters

[Displaying Human-Friendly Content](/documentation/Foundation/displaying-human-friendly-content)

Convert data into readable strings or Swift objects using formatters.

### Getting Textual Representations of Object Values

[`string(for:)`](/documentation/Foundation/Formatter/string(for:))

The default implementation of this method raises an exception.

[`attributedString(for:withDefaultAttributes:)`](/documentation/Foundation/Formatter/attributedString(for:withDefaultAttributes:))

The default implementation returns `nil` to indicate that the formatter object does not provide an attributed string.

[`editingString(for:)`](/documentation/Foundation/Formatter/editingString(for:))

The default implementation of this method invokes [`string(for:)`](/documentation/Foundation/Formatter/string(for:)).

### Getting Object Values for Textual Representations

[`getObjectValue(_:for:errorDescription:)`](/documentation/Foundation/Formatter/getObjectValue(_:for:errorDescription:))

The default implementation of this method raises an exception.

### Validating Partial Strings

[`isPartialStringValid(_:newEditingString:errorDescription:)`](/documentation/Foundation/Formatter/isPartialStringValid(_:newEditingString:errorDescription:))

Returns a Boolean value that indicates whether a partial string is valid.

[`isPartialStringValid(_:proposedSelectedRange:originalString:originalSelectedRange:errorDescription:)`](/documentation/Foundation/Formatter/isPartialStringValid(_:proposedSelectedRange:originalString:originalSelectedRange:errorDescription:))

This method should be implemented in subclasses that want to validate user changes to a string in a field, where the user changes are not necessarily at the end of the string, and preserve the selection (or set a different one, such as selecting the erroneous part of the string the user has typed).

### Constants

[`Formatter.Context`](/documentation/Foundation/Formatter/Context)

The formatting context for a formatter.

[`Formatter.UnitStyle`](/documentation/Foundation/Formatter/UnitStyle)

Specifies the width of the unit, determining the textual representation.


---

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)