Class

DateComponentsFormatter

A formatter that creates string representations of quantities of time.

Overview

An DateComponentsFormatter object takes quantities of time and formats them as a user-readable string. Use a date components formatter to create strings for your app’s interface. The formatter object has many options for creating both abbreviated and expanded strings. The formatter takes the current user’s locale and language into account when generating strings.

To use this class, create an instance, configure its properties, and call one of its methods to generate an appropriate string. The properties of this class let you configure the calendar and specify the date and time units you want displayed in the resulting string. Listing 1 shows how to configure a formatter to create the string “About 5 minutes remaining”.

Listing 1

Configuring a formatter object

let formatter = NSDateComponentsFormatter()
formatter.unitsStyle = .Full
formatter.includesApproximationPhrase = true
formatter.includesTimeRemainingPhrase = true
formatter.allowedUnits = [.Minute]
 
// Use the configured formatter to generate the string.
let outputString = formatter.stringFromTimeInterval(300.0)

The methods of this class may be called safely from any thread of your app. It is also safe to share a single instance of this class from multiple threads, with the caveat that you should not change the configuration of the object while another thread is using it to generate a string.

Topics

Formatting Values

func string(from: DateComponents)

Returns a formatted string based on the specified date component information.

func string(for: Any?)

Returns a formatted string based on the date information in the specified object.

func string(from: Date, to: Date)

Returns a formatted string based on the time difference between two dates.

func string(from: TimeInterval)

Returns a formatted string based on the specified number of seconds.

class func localizedString(from: DateComponents, unitsStyle: DateComponentsFormatter.UnitsStyle)

Returns a localized string based on the specified date components and style option.

Configuring the Formatter Options

var allowedUnits: NSCalendar.Unit

The bitmask of calendrical units such as day and month to include in the output string.

var allowsFractionalUnits: Bool

A Boolean indicating whether non-integer units may be used for values.

var calendar: Calendar?

The default calendar to use when formatting date components.

var collapsesLargestUnit: Bool

A Boolean value indicating whether to collapse the largest unit into smaller units when a certain threshold is met.

var includesApproximationPhrase: Bool

A Boolean value indicating whether the resulting phrase reflects an inexact time value.

var includesTimeRemainingPhrase: Bool

A Boolean value indicating whether output strings reflect the amount of time remaining.

var maximumUnitCount: Int

The maximum number of time units to include in the output string.

var unitsStyle: DateComponentsFormatter.UnitsStyle

The formatting style for unit names.

Constants

enum DateComponentsFormatter.UnitsStyle

Constants for specifying how to spell out unit names.

struct DateComponentsFormatter.ZeroFormattingBehavior

Formatting constants for when values contain zeroes.

Relationships

Inherits From

Conforms To

See Also

Date Formatting

class DateFormatter

A formatter that converts between dates and their textual representations.

class DateIntervalFormatter

A formatter that creates string representations of time intervals.

class ISO8601DateFormatter

A formatter that converts between dates and their IOS 8601 string representations.