Mac Developer Library

Developer

Foundation Framework Reference NSTimeZone Class Reference

Options
Deployment Target:

On This Page
Language:

NSTimeZone

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). More...

Inheritance


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns the time zone object identified by a given abbreviation.

    Declaration

    Swift

    convenience init?(abbreviation abbreviation: String)

    Objective-C

    + (instancetype)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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the time zone object identified by a given ID.

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    convenience init(forSecondsFromGMT seconds: Int)

    Objective-C

    + (instancetype)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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a time zone initialized with a given ID.

    Declaration

    Swift

    init?(name tzName: String)

    Objective-C

    - (instancetype)initWithName:(NSString *)tzName

    Parameters

    tzName

    The ID for the time zone. Providing nil for this parameter raises an invalid argument exception.

    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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init?(name tzName: String, data data: NSData?)

    Objective-C

    - (instancetype)initWithName:(NSString *)tzName data:(NSData *)data

    Parameters

    tzName

    The ID for the time zone. Providing nil for this parameter raises an invalid argument exception.

    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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the time zone data version.

    Declaration

    Swift

    class func timeZoneDataVersion() -> String

    Objective-C

    + (NSString *)timeZoneDataVersion

    Return Value

    A string containing the time zone data version.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    class func localTimeZone() -> NSTimeZone

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the default time zone for the current application.

    Declaration

    Swift

    class func defaultTimeZone() -> NSTimeZone

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func setDefaultTimeZone(_ aTimeZone: NSTimeZone)

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func resetSystemTimeZone()

    Objective-C

    + (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).

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the time zone currently used by the system.

    Declaration

    Swift

    class func systemTimeZone() -> NSTimeZone

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func abbreviationDictionary() -> [NSObject : AnyObject]

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func knownTimeZoneNames() -> [AnyObject]

    Objective-C

    + (NSArray *)knownTimeZoneNames

    Return Value

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the abbreviation dictionary to the specified dictionary.

    Declaration

    Swift

    class func setAbbreviationDictionary(_ dict: [NSObject : AnyObject])

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    var abbreviation: String? { get }

    Objective-C

    @property(readonly, copy) NSString *abbreviation

    Discussion

    Invokes abbreviationForDate: with the current date as the argument.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the abbreviation for the receiver at a given date.

    Declaration

    Swift

    func abbreviationForDate(_ aDate: NSDate) -> String?

    Objective-C

    - (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 saving time the US/Eastern time zone has an abbreviation of “EDT.” At other times, its abbreviation is “EST.”

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • name name Property

    The geopolitical region ID that identifies the receiver. (read-only)

    Declaration

    Swift

    var name: String { get }

    Objective-C

    @property(readonly, copy) NSString *name

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The current difference in seconds between the receiver and Greenwich Mean Time. (read-only)

    Declaration

    Swift

    var secondsFromGMT: Int { get }

    Objective-C

    @property(readonly) NSInteger secondsFromGMT

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func secondsFromGMTForDate(_ aDate: NSDate) -> Int

    Objective-C

    - (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 saving time.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • data data Property

    The data that stores the information used by the receiver. (read-only)

    Declaration

    Swift

    @NSCopying var data: NSData { get }

    Objective-C

    @property(readonly, copy) NSData *data

    Discussion

    This data should be treated as an opaque object.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func isEqualToTimeZone(_ aTimeZone: NSTimeZone) -> Bool

    Objective-C

    - (BOOL)isEqualToTimeZone:(NSTimeZone *)aTimeZone

    Parameters

    aTimeZone

    The time zone to compare with the receiver.

    Return Value

    YEStrue if aTimeZone and the receiver have the same name and data, otherwise NOfalse.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The description of the receiver, including the name, abbreviation, offset from GMT, and whether or not daylight saving time is currently in effect. (read-only)

    Declaration

    Swift

    var description: String { get }

    Objective-C

    @property(readonly, copy) NSString *description

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func localizedName(_ style: NSTimeZoneNameStyle, locale locale: NSLocale?) -> String?

    Objective-C

    - (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Specify styles for presenting time zone names.

    Declaration

    Swift

    enum NSTimeZoneNameStyle : Int { case Standard case ShortStandard case DaylightSaving case ShortDaylightSaving case Generic case ShortGeneric }

    Objective-C

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

    Constants

    • Standard

      NSTimeZoneNameStyleStandard

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

      Available in OS X v10.5 and later.

    • ShortStandard

      NSTimeZoneNameStyleShortStandard

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

      Available in OS X v10.5 and later.

    • DaylightSaving

      NSTimeZoneNameStyleDaylightSaving

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

      Available in OS X v10.5 and later.

    • ShortDaylightSaving

      NSTimeZoneNameStyleShortDaylightSaving

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

      Available in OS X v10.5 and later.

    • Generic

      NSTimeZoneNameStyleGeneric

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

      Available in OS X v10.6 and later.

    • ShortGeneric

      NSTimeZoneNameStyleShortGeneric

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

      Available in OS X v10.6 and later.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.5 and later.