Class

NSDateComponentsFormatter

A formatter that creates string representations of quantities of time.

Declaration

@interface NSDateComponentsFormatter : NSFormatter

Overview

An NSDateComponentsFormatter 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

NSDateComponentsFormatter *formatter = [[NSDateComponentsFormatter alloc] init];
formatter.unitsStyle = NSDateComponentsFormatterUnitsStyleFull;
formatter.includesApproximationPhrase = YES;
formatter.includesTimeRemainingPhrase = YES;
formatter.allowedUnits = NSCalendarUnitMinute;
 
// Use the configured formatter to generate the string.
NSString* 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

- stringFromDateComponents:

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

- stringForObjectValue:

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

- stringFromDate:toDate:

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

- stringFromTimeInterval:

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

+ localizedStringFromDateComponents:unitsStyle:

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

Configuring the Formatter Options

allowedUnits

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

allowsFractionalUnits

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

calendar

The default calendar to use when formatting date components.

collapsesLargestUnit

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

includesApproximationPhrase

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

includesTimeRemainingPhrase

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

maximumUnitCount

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

unitsStyle

The formatting style for unit names.

zeroFormattingBehavior

The formatting style for units whose value is 0.

Constants

NSDateComponentsFormatterUnitsStyle

Constants for specifying how to represent quantities of time.

NSDateComponentsFormatterZeroFormattingBehavior

Formatting constants for when values contain zeroes.

Relationships

Inherits From

See Also

Date Formatting

NSDateFormatter

A formatter that converts between dates and their textual representations.

NSDateIntervalFormatter

A formatter that creates string representations of time intervals.

NSISO8601DateFormatter

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