NSTimeZone Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSTimeZone.h
Related sample code

Overview

NSTimeZone is an abstract class that defines the behavior of time zone objects. Time zone objects represent geopolitical regions. Consequently, these objects have names for these regions. Time zone objects also represent a temporal offset, either plus or minus, from Greenwich Mean Time (GMT) and an abbreviation (such as PST for Pacific Standard Time).

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

Note that, strictly, time zone database entries such as “America/Los_Angeles” are IDs not names. An example of a time zone name is “Pacific Daylight Time”. Although many NSTimeZone method names include the word “name”, they refer to IDs.

Cocoa does not provide any API to change the time zone of the computer, or of other applications.

NSTimeZone is “toll-free bridged” with its Core Foundation counterpart, CFTimeZoneRef. See “Toll-Free Bridging” for more information on toll-free bridging.

Tasks

Creating and Initializing Time Zone Objects

Working with System Time Zones

Getting Time Zone Information

Getting Information About a Specific Time Zone

Comparing Time Zones

Describing a Time Zone

Getting Information About Daylight Saving

Class Methods

abbreviationDictionary

Returns a dictionary holding the mappings of time zone abbreviations to time zone names.

+ (NSDictionary *)abbreviationDictionary
Return Value

A dictionary holding the mappings of time zone abbreviations to time zone names.

Discussion

Note that more than one time zone may have the same abbreviation—for example, US/Pacific and Canada/Pacific both use the abbreviation “PST.” In these cases, abbreviationDictionary chooses a single name to map the abbreviation to.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

defaultTimeZone

Returns the default time zone for the current application.

+ (NSTimeZone *)defaultTimeZone
Return Value

The default time zone for the current application. If no default time zone has been set, this method invokes systemTimeZone and returns the system time zone.

Discussion

The default time zone is the one that the application is running with, which you can change (so you can make the application run as if it were in a different time zone).

If you get the default time zone and hold onto the returned object, it does not change if a subsequent invocation of setDefaultTimeZone: changes the default time zone—you still have the specific time zone you originally got. Contrast this behavior with the object returned by localTimeZone.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

knownTimeZoneNames

Returns an array of strings listing the IDs of all the time zones known to the system.

+ (NSArray *)knownTimeZoneNames
Return Value

An array of strings listing the IDs of all the time zones known to the system.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

localTimeZone

Returns an object that forwards all messages to the default time zone for the current application.

+ (NSTimeZone *)localTimeZone
Return Value

An object that forwards all messages to the default time zone for the current application.

Discussion

The local time zone represents the current state of the default time zone at all times. If you get the default time zone (using defaultTimeZone) and hold onto the returned object, it does not change if a subsequent invocation of setDefaultTimeZone: changes the default time zone—you still have the specific time zone you originally got. The local time zone adds a level of indirection, it acts as if it were the current default time zone whenever you invoke a method on it.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSTimeZone.h

resetSystemTimeZone

Resets the system time zone object cached by the application, if any.

+ (void)resetSystemTimeZone
Discussion

If the application has cached the system time zone, this method clears that cached object. If you subsequently invoke systemTimeZone, NSTimeZone will attempt to redetermine the system time zone and a new object will be created and cached (see systemTimeZone).

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

setAbbreviationDictionary:

Sets the abbreviation dictionary to the specified dictionary.

+ (void)setAbbreviationDictionary:(NSDictionary *)dict
Parameters
dict

A dictionary containing key-value pairs for looking up time zone names given their abbreviations. The keys should be NSString objects containing the abbreviations; the values should be NSString objects containing their corresponding geopolitical region names.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSTimeZone.h

setDefaultTimeZone:

Sets the default time zone for the current application to a given time zone.

+ (void)setDefaultTimeZone:(NSTimeZone *)aTimeZone
Parameters
aTimeZone

The new default time zone for the current application.

Discussion

There can be only one default time zone, so by setting a new default time zone, you lose the previous one.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

systemTimeZone

Returns the time zone currently used by the system.

+ (NSTimeZone *)systemTimeZone
Return Value

The time zone currently used by the system. If the current time zone cannot be determined, returns the GMT time zone.

Special Considerations

If you get the system time zone, it is cached by the application and does not change if the user subsequently changes the system time zone. The next time you invoke systemTimeZone, you get back the same time zone you originally got. You have to invoke resetSystemTimeZone to clear the cached object.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

timeZoneDataVersion

Returns the time zone data version.

+ (NSString *)timeZoneDataVersion
Return Value

A string containing the time zone data version.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSTimeZone.h

timeZoneForSecondsFromGMT:

Returns a time zone object offset from Greenwich Mean Time by a given number of seconds.

+ (id)timeZoneForSecondsFromGMT:(NSInteger)seconds
Parameters
seconds

The number of seconds by which the new time zone is offset from GMT.

Return Value

A time zone object offset from Greenwich Mean Time by seconds.

Discussion

The name of the new time zone is GMT +/– the offset, in hours and minutes. Time zones created with this method never have daylight savings, and the offset is constant no matter the date.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

timeZoneWithAbbreviation:

Returns the time zone object identified by a given abbreviation.

+ (id)timeZoneWithAbbreviation:(NSString *)abbreviation
Parameters
abbreviation

An abbreviation for a time zone.

Return Value

The time zone object identified by abbreviation determined by resolving the abbreviation to a name using the abbreviation dictionary and then returning the time zone for that name. Returns nil if there is no match for abbreviation.

Discussion

In general, you are discouraged from using abbreviations except for unique instances such as “UTC” or “GMT”. Time Zone abbreviations are not standardized and so a given abbreviation may have multiple meanings—for example, “EST” refers to Eastern Time in both the United States and Australia

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

timeZoneWithName:

Returns the time zone object identified by a given ID.

+ (id)timeZoneWithName:(NSString *)tzName
Parameters
tzName

The ID for the time zone.

Return Value

The time zone in the information directory with a name matching tzName. Returns nil if there is no match for the name.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

timeZoneWithName:data:

Returns the time zone with a given ID whose data has been initialized using given data,

+ (id)timeZoneWithName:(NSString *)tzName data:(NSData *)data
Parameters
tzName

The ID for the time zone.

data

The data from the time-zone files located at /usr/share/zoneinfo.

Return Value

The time zone with the ID tzName whose data has been initialized using the contents of data.

Discussion

You should not call this method directly—use timeZoneWithName: to get the time zone object for a given name.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

Instance Methods

abbreviation

Returns the abbreviation for the receiver.

- (NSString *)abbreviation
Return Value

The abbreviation for the receiver, such as “EDT” (Eastern Daylight Time).

Discussion

Invokes abbreviationForDate: with the current date as the argument.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

abbreviationForDate:

Returns the abbreviation for the receiver at a given date.

- (NSString *)abbreviationForDate:(NSDate *)aDate
Parameters
aDate

The date for which to get the abbreviation for the receiver.

Return Value

The abbreviation for the receiver at aDate.

Discussion

Note that the abbreviation may be different at different dates. For example, during daylight savings time the US/Eastern time zone has an abbreviation of “EDT.” At other times, its abbreviation is “EST.”

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

data

Returns the data that stores the information used by the receiver.

- (NSData *)data
Return Value

The data that stores the information used by the receiver.

Discussion

This data should be treated as an opaque object.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

daylightSavingTimeOffset

Returns the current daylight saving time offset of the receiver.

- (NSTimeInterval)daylightSavingTimeOffset
Return Value

The daylight current saving time offset of the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

daylightSavingTimeOffsetForDate:

Returns the daylight saving time offset for a given date.

- (NSTimeInterval)daylightSavingTimeOffsetForDate:(NSDate *)aDate
Parameters
aDate

A date.

Return Value

The daylight saving time offset for aDate.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

description

Returns the description of the receiver.

- (NSString *)description
Return Value

The description of the receiver, including the name, abbreviation, offset from GMT, and whether or not daylight savings time is currently in effect.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

initWithName:

Returns a time zone initialized with a given ID.

- (id)initWithName:(NSString *)tzName
Parameters
tzName

The ID for the time zone. Must not be nil.

Return Value

A time zone object initialized with the ID tzName.

Discussion

If tzName is a known ID, this method calls initWithName:data: with the appropriate data object.

In OS X v10.4 and earlier providing nil for the parameter would have caused a crash. In OS X v10.5 and later, this now raises an invalid argument exception.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

initWithName:data:

Initializes a time zone with a given ID and time zone data.

- (id)initWithName:(NSString *)tzName data:(NSData *)data
Parameters
tzName

The ID for the time zone. Must not be nil.

data

The data from the time-zone files located at /usr/share/zoneinfo.

Discussion

You should not call this method directly—use initWithName: to get a time zone object.

In OS X v10.4 and earlier providing nil for the tzName parameter would have caused a crash. In OS X v10.5 and later, this now raises an invalid argument exception.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

isDaylightSavingTime

Returns a Boolean value that indicates whether the receiver is currently using daylight saving time.

- (BOOL)isDaylightSavingTime
Return Value

YES if the receiver is currently using daylight savings time, otherwise NO.

Discussion

This method invokes isDaylightSavingTimeForDate: with the current date as the argument.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

isDaylightSavingTimeForDate:

Returns a Boolean value that indicates whether the receiver uses daylight savings time at a given date.

- (BOOL)isDaylightSavingTimeForDate:(NSDate *)aDate
Parameters
aDate

The date against which to test the receiver.

Return Value

YES if the receiver uses daylight savings time at aDate, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

isEqualToTimeZone:

Returns a Boolean value that indicates whether the receiver has the same name and data as another given time zone.

- (BOOL)isEqualToTimeZone:(NSTimeZone *)aTimeZone
Parameters
aTimeZone

The time zone to compare with the receiver.

Return Value

YES if aTimeZone and the receiver have the same name and data, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

localizedName:locale:

Returns the name of the receiver localized for a given locale.

- (NSString *)localizedName:(NSTimeZoneNameStyle)style locale:(NSLocale *)locale
Parameters
style

The format style for the returned string.

locale

The locale for which to format the name.

Return Value

The name of the receiver localized for locale using style.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

name

Returns the geopolitical region ID that identifies the receiver.

- (NSString *)name
Return Value

The geopolitical region ID that identifies the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

nextDaylightSavingTimeTransition

Returns the date of the next daylight saving time transition for the receiver.

- (NSDate *)nextDaylightSavingTimeTransition
Return Value

The date of the next (after the current instant) daylight saving time transition for the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

nextDaylightSavingTimeTransitionAfterDate:

Returns the next daylight saving time transition after a given date.

- (NSDate *)nextDaylightSavingTimeTransitionAfterDate:(NSDate *)aDate
Parameters
aDate

A date.

Return Value

The next daylight saving time transition after aDate.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

secondsFromGMT

Returns the current difference in seconds between the receiver and Greenwich Mean Time.

- (NSInteger)secondsFromGMT
Return Value

The current difference in seconds between the receiver and Greenwich Mean Time.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

secondsFromGMTForDate:

Returns the difference in seconds between the receiver and Greenwich Mean Time at a given date.

- (NSInteger)secondsFromGMTForDate:(NSDate *)aDate
Parameters
aDate

The date against which to test the receiver.

Return Value

The difference in seconds between the receiver and Greenwich Mean Time at aDate.

Discussion

The difference may be different from the current difference if the time zone changes its offset from GMT at different points in the year—for example, the U.S. time zones change with daylight savings time.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSTimeZone.h

Constants

Time Zone Name Styles

Specify styles for presenting time zone names.

typedef enum : NSInteger {
   NSTimeZoneNameStyleStandard,
   NSTimeZoneNameStyleShortStandard,
   NSTimeZoneNameStyleDaylightSaving,
   NSTimeZoneNameStyleShortDaylightSaving,
   NSTimeZoneNameStyleGeneric,
   NSTimeZoneNameStyleShortGeneric
} NSTimeZoneNameStyle;
Constants
NSTimeZoneNameStyleStandard

Specifies a standard name style. For example, “Central Standard Time” for Central Time.

Available in iOS 2.0 and later.

Declared in NSTimeZone.h.

NSTimeZoneNameStyleShortStandard

Specifies a short name style. For example, “CST” for Central Time.

Available in iOS 2.0 and later.

Declared in NSTimeZone.h.

NSTimeZoneNameStyleDaylightSaving

Specifies a daylight saving name style. For example, “Central Daylight Time” for Central Time.

Available in iOS 2.0 and later.

Declared in NSTimeZone.h.

NSTimeZoneNameStyleShortDaylightSaving

Specifies a short daylight saving name style. For example, “CDT” for Central Time.

Available in iOS 2.0 and later.

Declared in NSTimeZone.h.

NSTimeZoneNameStyleGeneric

Specifies a generic name style. For example, “Central Time” for Central Time.

Available in iOS 4.0 and later.

Declared in NSTimeZone.h.

NSTimeZoneNameStyleShortGeneric

Specifies a generic time zone name. For example, “CT” for Central Time.

Available in iOS 4.0 and later.

Declared in NSTimeZone.h.

Notifications

NSSystemTimeZoneDidChangeNotification

Sent when the time zone changed.
Availability
Declared In
NSTimeZone.h