---

CFTimeZone Reference

Overview

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

CFTimeZone provides several functions to create time zone objects: CFTimeZoneCreateWithName and CFTimeZoneCreateWithTimeIntervalFromGMT. CFTimeZone also permits you to set the default time zone within your application using the CFTimeZoneSetDefault function. You can access this default time zone at any time with the CFTimeZoneCopyDefault function.

CFTimeZone is “toll-free bridged” with its Cocoa Foundation counterpart, NSTimeZone. 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 in a CFTimeZoneRef, and in a function where you see a CFTimeZoneRef parameter, you can pass in an NSTimeZone instance. This fact also applies to concrete subclasses of NSTimeZone. See Interchangeable Data Types for more information on toll-free bridging.

Functions by Task

Creating a Time Zone

• CFTimeZoneCreateWithName
• CFTimeZoneCreateWithTimeIntervalFromGMT
• CFTimeZoneCreate

System and Default Time Zones and Information

• CFTimeZoneCopyAbbreviationDictionary
• CFTimeZoneCopyAbbreviation
• CFTimeZoneCopyDefault
• CFTimeZoneCopySystem
• CFTimeZoneSetDefault
• CFTimeZoneCopyKnownNames
• CFTimeZoneResetSystem
• CFTimeZoneSetAbbreviationDictionary

Getting Information About Time Zones

• CFTimeZoneGetName
• CFTimeZoneCopyLocalizedName
• CFTimeZoneGetSecondsFromGMT
• CFTimeZoneGetData

Getting Daylight Savings Time Information

• CFTimeZoneIsDaylightSavingTime
• CFTimeZoneGetDaylightSavingTimeOffset
• CFTimeZoneGetNextDaylightSavingTimeTransition

Getting the CFTimeZone Type ID

• CFTimeZoneGetTypeID

Functions

CFTimeZoneCopyAbbreviation

Returns the abbreviation of a time zone at a specified date.

CFStringRef CFTimeZoneCopyAbbreviation (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

Parameters

tz

The time zone to use.

at

The absolute time at which to obtain the abbreviation.

Return Value

A string containing the time zone abbreviation of at. Ownership follows the Create Rule.

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 Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneCopyAbbreviationDictionary

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

CFDictionaryRef CFTimeZoneCopyAbbreviationDictionary (
   void
);

Return Value

A dictionary containing the mappings of time zone abbreviations to time zone names. Ownership follows the Create Rule.

Discussion

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 this function chooses a single name to map the abbreviation to.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneCopyDefault

Returns the default time zone set for your application.

CFTimeZoneRef CFTimeZoneCopyDefault (
   void
);

Return Value

A time zone representing the default time zone set for your application, or the system time zone if no default is set. Ownership follows the Create Rule.

Discussion

If no default time zone is set, this function simply returns the result of the CFTimeZoneCopySystem function.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneCopyKnownNames

Returns an array of strings containing the names of all the time zones known to the system.

CFArrayRef CFTimeZoneCopyKnownNames (
   void
);

Return Value

An array containing CFString objects representing all the known time zone names. Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneCopyLocalizedName

Returns the localized name of a given time zone.

CFStringRef CFTimeZoneCopyLocalizedName (
   CFTimeZoneRef tz,
   CFTimeZoneNameStyle style,
   CFLocaleRef locale
);

Parameters

tz

The time zone to analyze.

style

The style for the returned name.

locale

The locale for which to localize the returned name.

Return Value

The name of tz localized for locale.Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CFTimeZone.h

CFTimeZoneCopySystem

Returns the time zone currently used by the system.

CFTimeZoneRef CFTimeZoneCopySystem (
   void
);

Return Value

A time zone representing the time zone currently used by the system, or the GMT time zone if the current zone cannot be determined. Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneCreate

Creates a time zone with a given name and data.

CFTimeZoneRef CFTimeZoneCreate (
   CFAllocatorRef allocator,
   CFStringRef name,
   CFDataRef data
);

Parameters

allocator

The allocator object to use to allocate memory for the new time zone. Pass NULL or kCFAllocatorDefault to use the current default allocator.

name

The name of the time zone to create.

data

The data to use to initialize the time zone. The contents of the data should be the same as that found within the time-zone files located at /usr/share/zoneinfo.

Return Value

A time zone corresponding to name and data. Ownership follows the Create Rule.

Discussion

You typically do not call this function directly. Use the CFTimeZoneCreateWithName function to obtain a time zone given its name.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneCreateWithName

Returns the time zone object identified by a given name or abbreviation.

CFTimeZoneRef CFTimeZoneCreateWithName (
   CFAllocatorRef allocator,
   CFStringRef name,
   Boolean tryAbbrev
);

Parameters

allocator

The allocator object to use to allocate memory for the new time zone. Pass NULL or kCFAllocatorDefault to use the current default allocator.

name

The name or abbreviation of the time zone to obtain. The name may be in any of the formats understood by the system, for example "EST", "Etc/GMT-2", "America/Argentina/Buenos_Aires", "Europe/Monaco", "US/Pacific", or "posixrules". For a complete list of system names, you can see the output of CFTimeZoneCopyKnownNames.

tryAbbrev

If false, assumes name is not an abbreviation and searches the time zone information directory for a matching name. If true, tries to resolve name using the abbreviation dictionary first before searching the information dictionary.

Return Value

A time zone corresponding to name, or NULL if no match was found. Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneCreateWithTimeIntervalFromGMT

Returns a time zone object for the specified time interval offset from Greenwich Mean Time (GMT).

CFTimeZoneRef CFTimeZoneCreateWithTimeIntervalFromGMT (
   CFAllocatorRef allocator,
   CFTimeInterval ti
);

Parameters

allocator

The allocator object to use to allocate memory for the new time zone. Pass NULL or kCFAllocatorDefault to use the current default allocator.

ti

The offset, from GMT, of the new time zone.

Return Value

A new time zone whose offset from GMT is given by the interval ti. The name of the new time zone is GMT +/- the offset, in hours and minutes. Time zones created with this function never have daylight savings, and the offset is constant no matter what the date. Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneGetData

Returns the data that stores the information used by a time zone.

CFDataRef CFTimeZoneGetData (
   CFTimeZoneRef tz
);

Parameters

tz

The time zone to analyze.

Return Value

The data used to store tz. Ownership follows the Get Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneGetDaylightSavingTimeOffset

Returns the daylight saving time offset for a time zone at a given time.

CFTimeInterval CFTimeZoneGetDaylightSavingTimeOffset (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

Parameters

tz

The time zone to analyze.

at

The time in tz to test for daylight saving time offset.

Return Value

The daylight saving time offset for tz at at.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CFTimeZone.h

CFTimeZoneGetName

Returns the geopolitical region name that identifies a given time zone.

CFStringRef CFTimeZoneGetName (
   CFTimeZoneRef tz
);

Parameters

tz

The time zone to analyze.

Return Value

A string containing the geopolitical region name that identifies tz. Ownership follows the Get Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneGetNextDaylightSavingTimeTransition

Returns the time in a given time zone of the next daylight saving time transition after a given time.

CFAbsoluteTime CFTimeZoneGetNextDaylightSavingTimeTransition (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

Parameters

tz

The time zone to analyze.

at

A time in tz.

Return Value

The time in tz of the next daylight saving time transition after at.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CFTimeZone.h

CFTimeZoneGetSecondsFromGMT

Returns the difference in seconds between the receiver and Greenwich Mean Time (GMT) at the specified date.

CFTimeInterval CFTimeZoneGetSecondsFromGMT (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

Parameters

tz

The time zone to analyze.

at

The date at which the interval is to be computed.

Return Value

The difference in seconds between tz and GMT at the specified date, at.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneGetTypeID

Returns the type identifier for the CFTimeZone opaque type.

CFTypeID CFTimeZoneGetTypeID (
   void
);

Return Value

The type identifier for the CFTimeZone opaque type.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneIsDaylightSavingTime

Returns whether or not a time zone is in daylight savings time at a specified date.

Boolean CFTimeZoneIsDaylightSavingTime (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

Parameters

tz

The time zone to analyze.

at

The date in tz to test for daylight savings.

Return Value

true if tz is in daylight savings time at at, otherwise false.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneResetSystem

Clears the previously determined system time zone, if any.

void CFTimeZoneResetSystem (
   void
);

Discussion

This function also resets the default time zone if it is the same as the system time zone.

Subsequent calls to CFTimeZoneCopySystem will attempt to re-determine the system time zone.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneSetAbbreviationDictionary

Sets the abbreviation dictionary to a given dictionary.

void CFTimeZoneSetAbbreviationDictionary (
   CFDictionaryRef dict
);

Parameters

dict

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

CFTimeZoneSetDefault

Sets the default time zone for your application the given time zone.

void CFTimeZoneSetDefault (
   CFTimeZoneRef tz
);

Parameters

tz

The time zone to use as default.

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 Mac OS X v10.0 and later.

Declared In

CFTimeZone.h

Data Types

CFTimeZoneNameStyle

Para

typedef CFIndex CFTimeZoneNameStyle;

Discussion

For values, see “Time Zone Name Styles.”

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CFTimeZone.h

CFTimeZoneRef

A reference to a CFTimeZone object.

typedef const struct __CFTimeZone *CFTimeZoneRef;

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFDate.h

Constants

Notification Name

Name of the notification posted when the time zone changes.

const CFStringRef kCFTimeZoneSystemTimeZoneDidChangeNotification;

Constants

kCFTimeZoneSystemTimeZoneDidChangeNotification

Name of the notification posted when the system time zone changes.

The object of the notification is the previous system time zone object. This notification carries no user info.

Keep in mind that there is no order in how notifications are delivered to observers; frameworks or other parts of your code may also be observing this notification to take their own actions, and these may not have occurred by the time you receive the notification.

Available in Mac OS X v10.5 and later.

Declared in CFTimeZone.h

Declared In

CFTimeZone.h

Time Zone Name Styles

Constants to specify styles for time zone names.

enum {
   kCFTimeZoneNameStyleStandard,
   kCFTimeZoneNameStyleShortStandard,
   kCFTimeZoneNameStyleDaylightSaving,
   kCFTimeZoneNameStyleShortDaylightSaving
};

Constants

kCFTimeZoneNameStyleStandard

Specifies the standard name style for a time zone.

Available in Mac OS X v10.5 and later.

Declared in CFTimeZone.h

kCFTimeZoneNameStyleShortStandard

Specifies the short standard name style for a time zone.

Available in Mac OS X v10.5 and later.

Declared in CFTimeZone.h

kCFTimeZoneNameStyleDaylightSaving

Specifies the daylight saving name style for a time zone.

Available in Mac OS X v10.5 and later.

Declared in CFTimeZone.h

kCFTimeZoneNameStyleShortDaylightSaving

Specifies the short daylight saving name style for a time zone.

Available in Mac OS X v10.5 and later.

Declared in CFTimeZone.h

Discussion

These constants are used with the function CFTimeZoneCopyLocalizedName.

Declared In

CFTimeZone.h

---