CFTimeZone Reference

Derived from
Framework
CoreFoundation/CoreFoundation.h
Companion guide
Declared in
CFDate.h
CFTimeZone.h

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 “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a Time Zone

System and Default Time Zones and Information

Getting Information About Time Zones

Getting Daylight Savings Time Information

Getting the CFTimeZone Type ID

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 “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 iOS 2.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 “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 iOS 2.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 “The Create Rule”.

Discussion

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

Availability
  • Available in iOS 2.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 “The Create Rule”.

Availability
  • Available in iOS 2.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 “The Create Rule”.

Availability
  • Available in iOS 2.0 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 “The Create Rule”.

Availability
  • Available in iOS 2.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 “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 iOS 2.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 “The Create Rule”.

Availability
  • Available in iOS 2.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 “The Create Rule”.

Availability
  • Available in iOS 2.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 “The Get Rule”. May be NULL if the timezone does not have any data or use Olson data for its information.

Availability
  • Available in iOS 2.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 iOS 2.0 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 “The Get Rule”.

Availability
  • Available in iOS 2.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 iOS 2.0 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 iOS 2.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 iOS 2.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 iOS 2.0 and later.
Declared In
CFTimeZone.h

CFTimeZoneResetSystem

Clears the previously determined system time zone, if any.

void CFTimeZoneResetSystem (
   void
);
Discussion

If the default time zone is set to the same value as the system time zone or has not been explicitly set, this function clears it as well.

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

Availability
  • Available in iOS 2.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 iOS 2.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 iOS 2.0 and later.
Declared In
CFTimeZone.h

Data Types

CFTimeZoneNameStyle

Index type for constants used to specify styles of time zone names.

typedef CFIndex CFTimeZoneNameStyle;
Discussion

For values, see “Time Zone Name Styles.”

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

CFTimeZoneRef

A reference to a CFTimeZone object.

typedef const struct __CFTimeZone *CFTimeZoneRef;
Availability
  • Available in iOS 2.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 iOS 2.0 and later.

Declared in CFTimeZone.h.

Declared In
CFTimeZone.h

Time Zone Name Styles

Constants to specify styles for time zone names.

typedef enum : CFIndex {
   kCFTimeZoneNameStyleStandard,
   kCFTimeZoneNameStyleShortStandard,
   kCFTimeZoneNameStyleDaylightSaving,
   kCFTimeZoneNameStyleShortDaylightSaving,
   kCFTimeZoneNameStyleGeneric,
   kCFTimeZoneNameStyleShortGeneric
} CFTimeZoneNameStyle;
Constants
kCFTimeZoneNameStyleStandard

Specifies the standard name style; for example, “Central Standard Time” for the Central time zone.

Available in iOS 2.0 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleShortStandard

Specifies the short standard name style; for example, “CST” for the Central time zone.

Available in iOS 2.0 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleDaylightSaving

Specifies the daylight saving name style; for example, “Central Daylight Time” for the Central time zone.

Available in iOS 2.0 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleShortDaylightSaving

Specifies the short daylight saving name style; for example, “CDT” for the Central time zone.

Available in iOS 2.0 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleGeneric

Specifies the generic name style, which does not distinguish between daylight saving and standard time; for example, “Central Time” for the Central time zone.

Available in iOS 4.0 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleShortGeneric

Specifies the short generic name style, which does not distinguish between daylight saving and standard time; for example, “CT” for the Central time zone.

Available in iOS 4.0 and later.

Declared in CFTimeZone.h.

Discussion

These constants are used with the function CFTimeZoneCopyLocalizedName.

Declared In
CFTimeZone.h