Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSTimeZone.h |
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.
Cocoa does not provide any API to change the time zone of the computer, or of other applications.
Some NSCalendarDate
methods return date objects that are automatically bound to time zone 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.
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.
NSTimeZone
is “toll-free bridged” with its Core Foundation counterpart, CFTimeZone Reference. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSTimeZone *
parameter, you can pass a CFTimeZoneRef
, and in a function where you see a CFTimeZoneRef
parameter, you can pass an NSTimeZone
instance (you cast one type to the other to suppress compiler warnings). See Interchangeable Data Types for more information on toll-free bridging.
+ timeZoneWithAbbreviation:
+ timeZoneWithName:
+ timeZoneWithName:data:
+ timeZoneForSecondsFromGMT:
– initWithName:
– initWithName:data:
– isDaylightSavingTime
– daylightSavingTimeOffset
– isDaylightSavingTimeForDate:
– daylightSavingTimeOffsetForDate:
– nextDaylightSavingTimeTransition
– nextDaylightSavingTimeTransitionAfterDate:
Returns a dictionary holding the mappings of time zone abbreviations to time zone names.
+ (NSDictionary *)abbreviationDictionary
A dictionary holding the mappings of time zone abbreviations to time zone names.
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.
NSTimeZone.h
Returns the default time zone for the current application.
+ (NSTimeZone *)defaultTimeZone
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.
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
.
NSTimeZone.h
Returns an array of strings listing the IDs of all the time zones known to the system.
+ (NSArray *)knownTimeZoneNames
An array of strings listing the IDs of all the time zones known to the system.
NSTimeZone.h
Returns an object that forwards all messages to the default time zone for the current application.
+ (NSTimeZone *)localTimeZone
An object that forwards all messages to the default time zone for the current application.
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.
NSTimeZone.h
Resets the system time zone object cached by the application, if any.
+ (void)resetSystemTimeZone
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
).
NSTimeZone.h
Sets the default time zone for the current application to a given time zone.
+ (void)setDefaultTimeZone:(NSTimeZone *)aTimeZone
The new default time zone for the current application.
There can be only one default time zone, so by setting a new default time zone, you lose the previous one.
NSTimeZone.h
Returns the time zone currently used by the system.
+ (NSTimeZone *)systemTimeZone
The time zone currently used by the system. If the current time zone cannot be determined, returns the GMT time zone.
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.
NSTimeZone.h
Returns a time zone object offset from Greenwich Mean Time by a given number of seconds.
+ (id)timeZoneForSecondsFromGMT:(NSInteger)seconds
The number of seconds by which the new time zone is offset from GMT.
A time zone object offset from Greenwich Mean Time by seconds.
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.
NSTimeZone.h
Returns the time zone object identified by a given abbreviation.
+ (id)timeZoneWithAbbreviation:(NSString *)abbreviation
An abbreviation for a time zone.
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.
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
NSTimeZone.h
Returns the time zone object identified by a given ID.
+ (id)timeZoneWithName:(NSString *)aTimeZoneName
The ID for the time zone.
The time zone in the information directory with a name matching aName. Returns nil
if there is no match for the name.
NSTimeZone.h
Returns the time zone with a given ID whose data has been initialized using given data,
+ (id)timeZoneWithName:(NSString *)aTimeZoneName data:(NSData *)data
The ID for the time zone.
The data from the time-zone files located at /usr/share/zoneinfo
.
The time zone with the ID aTimeZoneName whose data has been initialized using the contents of data.
You should not call this method directly—use timeZoneWithName:
to get the time zone object for a given name.
NSTimeZone.h
Returns the abbreviation for the receiver.
- (NSString *)abbreviation
The abbreviation for the receiver, such as “EDT” (Eastern Daylight Time).
Invokes abbreviationForDate:
with the current date as the argument.
NSTimeZone.h
Returns the abbreviation for the receiver at a given date.
- (NSString *)abbreviationForDate:(NSDate *)aDate
The date for which to get the abbreviation for the receiver.
The abbreviation for the receiver at aDate.
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.”
NSTimeZone.h
Returns the data that stores the information used by the receiver.
- (NSData *)data
The data that stores the information used by the receiver.
This data should be treated as an opaque object.
NSTimeZone.h
Returns the current daylight saving time offset of the receiver.
- (NSTimeInterval)daylightSavingTimeOffset
The daylight current saving time offset of the receiver.
NSTimeZone.h
Returns the daylight saving time offset for a given date.
- (NSTimeInterval)daylightSavingTimeOffsetForDate:(NSDate *)aDate
A date.
The daylight saving time offset for aDate.
– isDaylightSavingTime
– daylightSavingTimeOffset
– isDaylightSavingTimeForDate:
– nextDaylightSavingTimeTransitionAfterDate:
NSTimeZone.h
Returns the description of the receiver.
- (NSString *)description
The description of the receiver, including the name, abbreviation, offset from GMT, and whether or not daylight savings time is currently in effect.
NSTimeZone.h
Returns a time zone initialized with a given ID.
- (id)initWithName:(NSString *)aName
The ID for the time zone.
A time zone object initialized with the ID aName.
If aName is a known ID, this method calls initWithName:data:
with the appropriate data object.
NSTimeZone.h
Initializes a time zone with a given ID and time zone data.
- (id)initWithName:(NSString *)aName data:(NSData *)data
The ID for the time zone.
The data from the time-zone files located at /usr/share/zoneinfo
.
You should not call this method directly—use initWithName:
to get a time zone object.
NSTimeZone.h
Returns a Boolean value that indicates whether the receiver is currently using daylight saving time.
- (BOOL)isDaylightSavingTime
YES
if the receiver is currently using daylight savings time, otherwise NO
.
This method invokes isDaylightSavingTimeForDate:
with the current date as the argument.
– isDaylightSavingTimeForDate:
– daylightSavingTimeOffset
– daylightSavingTimeOffsetForDate:
– nextDaylightSavingTimeTransition
– nextDaylightSavingTimeTransitionAfterDate:
NSTimeZone.h
Returns a Boolean value that indicates whether the receiver uses daylight savings time at a given date.
- (BOOL)isDaylightSavingTimeForDate:(NSDate *)aDate
The date against which to test the receiver.
YES
if the receiver uses daylight savings time at aDate, otherwise NO
.
– isDaylightSavingTime
– daylightSavingTimeOffset
– daylightSavingTimeOffsetForDate:
– nextDaylightSavingTimeTransitionAfterDate:
NSTimeZone.h
Returns a Boolean value that indicates whether the receiver has the same name and data as another given time zone.
- (BOOL)isEqualToTimeZone:(NSTimeZone *)aTimeZone
The time zone to compare with the receiver.
YES
if aTimeZone and the receiver have the same name and data, otherwise NO
.
NSTimeZone.h
Returns the name of the receiver localized for a given locale.
- (NSString *)localizedName:(NSTimeZoneNameStyle)style locale:(NSLocale *)locale
The format style for the returned string.
The locale for which to format the name.
The name of the receiver localized for locale using style.
NSTimeZone.h
Returns the geopolitical region ID that identifies the receiver.
- (NSString *)name
The geopolitical region ID that identifies the receiver.
NSTimeZone.h
Returns the date of the next daylight saving time transition for the receiver.
- (NSDate *)nextDaylightSavingTimeTransition
The date of the next (after the current instant) daylight saving time transition for the receiver.
NSTimeZone.h
Returns the next daylight saving time transition after a given date.
- (NSDate *)nextDaylightSavingTimeTransitionAfterDate:(NSDate *)aDate
A date.
The next daylight saving time transition after aDate.
NSTimeZone.h
Returns the current difference in seconds between the receiver and Greenwich Mean Time.
- (NSInteger)secondsFromGMT
The current difference in seconds between the receiver and Greenwich Mean Time.
NSTimeZone.h
Returns the difference in seconds between the receiver and Greenwich Mean Time at a given date.
- (NSInteger)secondsFromGMTForDate:(NSDate *)aDate
The date against which to test the receiver.
The difference in seconds between the receiver and Greenwich Mean Time at aDate.
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.
NSTimeZone.h
Defines a type for time zone name styles.
typedef NSInteger NSTimeZoneNameStyle;
See “Time Zone Name Styles” for possible values.
NSTimeZone.h
Specify styles for presenting time zone names.
enum { NSTimeZoneNameStyleStandard, NSTimeZoneNameStyleShortStandard, NSTimeZoneNameStyleDaylightSaving, NSTimeZoneNameStyleShortDaylightSaving };
NSTimeZoneNameStyleStandard
Specifies a standard name style.
Available in Mac OS X v10.5 and later.
Declared in NSTimeZone.h
.
NSTimeZoneNameStyleShortStandard
Specifies a short name style.
Available in Mac OS X v10.5 and later.
Declared in NSTimeZone.h
.
NSTimeZoneNameStyleDaylightSaving
Specifies a daylight saving name style.
Available in Mac OS X v10.5 and later.
Declared in NSTimeZone.h
.
NSTimeZoneNameStyleShortDaylightSaving
Specifies a short daylight saving name style.
Available in Mac OS X v10.5 and later.
Declared in NSTimeZone.h
.
NSTimeZone.h
Sent when the time zone changed.
NSTimeZone.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-02-08)