NSTimeZone

Inherits From: NSObject

Conforms To: NSCoding, NSCopying NSObject (NSObject)

Declared In: Foundation/NSDate.h

Class Description

NSTimeZone is an abstract class that defines the behavior of time-zone objects. By itself, NSDate represents dates as universal time. Universal time treats a date and time value as identical in, for instance, Redwood City and New York City. NSDate has no provision for locale adjustment of time-zone information. Provision for locale is critical for string descriptions and other expressions of conventional dates and times. NSTimeZone is used to affect the apparent value of date objects so that they reflect time zone related locale information.

NSTimeZoneDetail, a public subclass of NSTimeZone, augments the behavior of NSTimeZone by providing the commonly known attributes of a time zone in effect for a date within a time zone geopolitical area. These attributes are abbreviation, the offset from GMT (universal time), and an indication of whether Daylight Savings Time is in effect.

Time-zone objects represent geopolitical regions and use names to denote the various regions. For example, US/Pacific identifies the geopolitical time zone for San Francisco and Los Angeles, which falls in the same general latitude as that for the time zone Canada/Pacific. The US/Pacific time-zone has specific NSTimeZoneDetail instances that specify PST (Pacific Standard Time) and PDT (Pacific Daylight Time), which have slightly different offsets from GMT.

You typically associate the objects returned by NSTimeZone (and, by extension, NSTimeZoneDetail) with date objects to affect their behavior. Time-zone objects can be of various types:

. time zones with hour and minute offsets from Greenwich Mean Time (GMT)

. time zones with a single abbreviation and offset

. time zones that vary according to Standard Time and Daylight Savings Time

The system should supply the various choices for time zones along with time-zone information. These choices should be restricted to subsets based on latitude. You can access these choices through the timeZoneArray class method. Another restriction is the choice of time zone available when there is an ambiguous abbreviation; these choices are available through the class method abbreviationDictionary. Despite these restrictions, you can obtain an NSTimeZone object from an arbitrary file through the class method timeZoneWithName.

Note: By itself, the NSTimeZone class only names a time zone. It does not associate an abbreviation or a temporal offset with a time zone; that is done by NSTimeZoneDetail. An instance of NSTimeZone, however, knows about the set of time-zone detail objects related to it.

NSTimeZone provides several class methods to get time-zone objects, with or without detail: timeZoneWithName:, timeZoneWithAbbreviation:, and timeZoneForSecondsFromGMT:. The class also permits you to set the default time zone used by your application for your locale (setDefaultTimeZone:) You can access this default time zone at any time by the defaultTimeZone method, and, with the localTimeZone class method, you can also get a relative time-zone object that will decode itself to become the default time zone for any locale in which it finds itself.

NSCalendarDate methods return date objects that are automatically bound with time-zone detail objects. These date objects use the functionality of NSTimeZone to adjust dates for the proper locale. Unless you specify otherwise, objects returned from NSCalendarDate are bound to the default time zone for the current locale. A useful instance method is timeZoneDetailForDate:, which returns a time-zone detail object associated with a specific date.

Creating and Initializing an NSTimeZone

• + (NSTimeZoneDetail *)defaultTimeZone Returns the default time zone as set for the current locale.
• + (NSTimeZone *)localTimeZone Returns an NSTimeZone that behaves as the current default time zone in any given locale.
• + (NSTimeZone *)timeZoneForSecondsFromGMT:(int)seconds Returns an NSTimeZone representing the time zone with seconds offset from Greenwich Mean Time. If there is no object matching the offset, this method creates and returns a new NSTimeZone bearing the value seconds as a name.
• + (NSTimeZoneDetail *)timeZoneWithAbbreviation:(NSString *)abbreviation Returns the time-zone object identified by the abbreviation abbreviation. If there's no match, this method returns nil.
• + (NSTimeZone *)timeZoneWithName:(NSString *)aTimeZoneName Returns the time-zone object with the name that corresponds to the geopolitical region aTimeZoneName. It searches the regions dictionary for matching names. If there is no match on the name, this method returns nil.
• - (NSTimeZoneDetail *)timeZoneDetailForDate:(NSDate *)date Returns the correct time-zone detail object associated with a date object. You invoke this method when a region's time zone (that is, its offset value from GMT) varies over the year, as happens between Standard Time and Daylight Savings Time.

• + (void)setDefaultTimeZone:(NSTimeZone *)aTimeZone Sets aTimeZone as the time zone appropriate for the current locale. This new time zone replaces the previous default time zone.

• + (NSDictionary *)abbreviationDictionary Returns a dictionary that maps abbreviations to region names, for example PST is the key for US/Pacific. If you know a region name for a key, you can obtain a valid abbreviation from the dictionary and use it to obtain a detail time-zone object using timeZoneWithAbbreviation:.
• - (NSString *)timeZoneName Returns the geopolitical name of the time zone.

• + (NSArray *)timeZoneArray Returns an array of string object arrays, each containing strings that show current geopolitical names for each time zone. The subarrays are grouped by latitudinal region.
• - (NSArray *)timeZoneDetailArray Returns an array of NSTimeZoneDetail objects that are associated with the receiving NSTimeZone object.