Configuring Date and Time Mapping

RestKit is capable of parsing string representations containing dates and times and mapping them into local NSDate attributes as well as serializing local NSDate properties into strings for transport over HTTP. This document details the specifics of configuring this support for your application.

NSDateFormatter objects are known to be expensive to setup and tear down. For this reason, RestKit maintains an internal collection of date formatters that are used across all object mapping operations. By default, RestKit defines date formatters for you that will parse dates with the following configurations:

1. yyyy-MM-dd'T'HH:mm:ss'Z' in the UTC Time Zone
2. MM/dd/yyyy in the UTC Time Zone

Global date formatters are configured via static methods on the RKObjectMapping class:

• + defaultDateFormatters - Returns the currently configured collection date formatters to consult when mapping strings into dates.
• + setDefaultDateFormatters: - Sets a new default collection of date formatters. Expects dateFormatters to be an array of NSDateFormatter objects.
• + addDefaultDateFormatter: - Adds a NSDateFormatter to the end of the list of date formatters to use when parsing dates from strings.
• + addDefaultDateFormatterForString:inTimeZone: - Constructs a new NSDateFormatter for you configured with the specified date format string and time zone. If a nil time zone is provided, the formatter will be configured for UTC time.
• + preferredDateFormatter - Returns the preferred date formatter for use when transforming NSDate attributes into NSString representations. The preferred formatter is used when serializing into form encoded and JSON representations. Changing the preferred formatter will change how dates are sent to your remote backend for processing. Defaults to @"yyyy-MM-dd HH:mm:ss Z" in the UTC time zone.
• + setPreferredDateFormatter: - Sets the preferred date formatter to a new NSDateFormatter object. This formatter will be used during serialization.

You can also configured how dates and times are handled on a per-object mapping basis via properties on instances of RKObjectMapping:

• dateFormatters property - An array of NSDateFormatter objects to apply to any strings being mapped into NSDate attributes. Defaults to RKObjectMapping defaultDateFormatters if not configured.
• preferredDateFormatter property - An NSDateFormatter to use when transforming NSDate attributes into string representations when this object mapping instance is being sued. Defaults to RKObjectMapping preferredDateFormatter