Time Utilities Reference

Framework
CoreFoundation/CoreFoundation.h
Companion guide
Declared in
CFDate.h

Overview

Core Foundation measures time in units of seconds. The base data type is the CFTimeInterval, which measures the difference in seconds between two times. Fixed times, or dates, are defined by the CFAbsoluteTime data type, which measures the time interval between a particular date and the absolute reference date of Jan 1 2001 00:00:00 GMT.

The CFGregorianDate structure represents absolute times in terms of the Gregorian calendar. Functions such as CFAbsoluteTimeGetGregorianDate use a CFTimeZone object to obtain the local time in a particular time zone.

The CFDate opaque type wraps an absolute time into a CFType-base object, allowing you to put time objects into into collections and property lists and to be handled by other object-oriented parts of Core Foundation.

Functions

CFAbsoluteTimeAddGregorianUnits

Adds a time interval, expressed as Gregorian units, to a given absolute time.

CFAbsoluteTime CFAbsoluteTimeAddGregorianUnits (
   CFAbsoluteTime at,
   CFTimeZoneRef tz,
   CFGregorianUnits units
);
Parameters
at

The absolute time to which the interval is added.

tz

The time zone to use for time correction. Pass NULL for GMT.

units

The time interval to add to at.

Return Value

An absolute time value equal to the sum of at and units.

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

CFAbsoluteTimeGetCurrent

Returns the current system absolute time.

CFAbsoluteTime CFAbsoluteTimeGetCurrent ();
Return Value

The current absolute time.

Discussion

Absolute time is measured in seconds relative to the absolute reference date of Jan 1 2001 00:00:00 GMT. A positive value represents a date after the reference date, a negative value represents a date before it. For example, the absolute time -32940326 is equivalent to December 16th, 1999 at 17:54:34. Repeated calls to this function do not guarantee monotonically increasing results. The system time may decrease due to synchronization with external time references or due to an explicit user change of the clock.

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

CFAbsoluteTimeGetDayOfWeek

Returns an integer representing the day of the week indicated by the specified absolute time.

SInt32 CFAbsoluteTimeGetDayOfWeek (
   CFAbsoluteTime at,
   CFTimeZoneRef tz
);
Parameters
at

The absolute time to convert.

tz

The time zone to use for time correction. Pass NULL for GMT.

Return Value

An integer (1-7) representing the day of the week specified by at. Per ISO-8601, Monday is represented by 1, Tuesday by 2, and so on.

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

CFAbsoluteTimeGetDayOfYear

Returns an integer representing the day of the year indicated by the specified absolute time.

SInt32 CFAbsoluteTimeGetDayOfYear (
   CFAbsoluteTime at,
   CFTimeZoneRef tz
);
Parameters
at

The absolute time to convert.

tz

The time zone to use for time correction. Pass NULL for GMT.

Return Value

An integer (1-366) representing the day of the year specified by at.

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

CFAbsoluteTimeGetDifferenceAsGregorianUnits

Computes the time difference between two specified absolute times and returns the result as an interval in Gregorian units.

CFGregorianUnits CFAbsoluteTimeGetDifferenceAsGregorianUnits (
   CFAbsoluteTime at1,
   CFAbsoluteTime at2,
   CFTimeZoneRef tz,
   CFOptionFlags unitFlags
);
Parameters
at1

An absolute time.

at2

An absolute time.

tz

The time zone to use for time correction. Pass NULL for GMT.

unitFlags

A mask that specifies which Gregorian unit fields to use when converting the absolute time difference into a Gregorian interval. See Gregorian Unit Flags for a list of values from which to construct the mask.

Return Value

The difference between the specified absolute times (as at1 - at2—if at1 is earlier than at2, the result is negative) expressed in the units specified by unitFlags.

Discussion

The temporal difference is expressed as accurately as possible, given the units specified. For example, if you asked for the number of months and hours between 2:30pm on April 8 2005 and 5:45pm September 9 2005, the result would be 5 months and 27 hours.

The following example prints the number of hours and minutes between the current time (now) and the reference date (1 January 2001 00:00:00 GMT).

CFAbsoluteTime now = CFAbsoluteTimeGetCurrent ();
 
CFGregorianUnits units = CFAbsoluteTimeGetDifferenceAsGregorianUnits
    (now, 0, NULL, (kCFGregorianUnitsHours | kCFGregorianUnitsMinutes));
 
CFStringRef output = CFStringCreateWithFormat
    (NULL, 0, CFSTR("hours: %d; minutes: %d"), units.hours, units.minutes);
CFShow(output);
Availability
  • Available in iOS 2.0 and later.
Declared In
CFDate.h

CFAbsoluteTimeGetGregorianDate

Converts an absolute time value into a Gregorian date.

CFGregorianDate CFAbsoluteTimeGetGregorianDate (
   CFAbsoluteTime at,
   CFTimeZoneRef tz
);
Parameters
at

The absolute time value to convert.

tz

The time zone to use for time correction. Pass NULL for GMT.

Return Value

The Gregorian date equivalent for at.

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

CFAbsoluteTimeGetWeekOfYear

Returns an integer representing the week of the year indicated by the specified absolute time.

SInt32 CFAbsoluteTimeGetWeekOfYear (
   CFAbsoluteTime at,
   CFTimeZoneRef tz
);
Parameters
at

The absolute time to convert.

tz

The time zone to use for time correction. Pass NULL for GMT.

Return Value

An integer (1-53) representing the week of the year specified by at. The numbering follows the ISO 8601 definition of week.

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

CFGregorianDateGetAbsoluteTime

Converts a Gregorian date value into an absolute time value.

CFAbsoluteTime CFGregorianDateGetAbsoluteTime (
   CFGregorianDate gdate,
   CFTimeZoneRef tz
);
Parameters
gdate

The Gregorian date to convert.

tz

The time zone to use for time correction. Pass NULL for GMT.

Return Value

The absolute time equivalent of gdate.

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

CFGregorianDateIsValid

Checks the specified fields of a CFGregorianDate structure for valid values.

Boolean CFGregorianDateIsValid (
   CFGregorianDate gdate,
   CFOptionFlags unitFlags
);
Parameters
gdate

The CFGregorianDate structure whose fields to validate.

unitFlags

A mask that specifies which Gregorian unit fields to validate. See Gregorian Unit Flags for a list of values from which to construct the mask.

Return Value

true if the specified fields are valid, otherwise false.

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

Data Types

CFAbsoluteTime

Type used to represent a specific point in time relative to the absolute reference date of 1 Jan 2001 00:00:00 GMT.

typedef CFTimeInterval CFAbsoluteTime;
Discussion

Absolute time is measured by the number of seconds between the reference date and the specified date. Negative values indicate dates/times before the reference date. Positive values indicate dates/times after the reference date.

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

CFGregorianDate

Structure used to represent a point in time using the Gregorian calendar.

struct CFGregorianDate {
   SInt32 year;
   SInt8 month;
   SInt8 day;
   SInt8 hour;
   SInt8 minute;
   double second;
};
typedef struct CFGregorianDate CFGregorianDate;
Discussion

CFGregorianDate is implemented using the smallest data type appropriate for the range of possible values. For example, there are only 12 months in the Gregorian year, so there is no need to use an integer type larger than 8 bits. To represent a time interval in Gregorian units, use a CFGregorianUnits.

The month and day units are 1-based: the index for January is 1, and the index for the first day of the month is 1.

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

CFGregorianUnits

Structure used to represent a time interval in Gregorian units.

struct CFGregorianUnits {
   SInt32 years;
   SInt32 months;
   SInt32 days;
   SInt32 hours;
   SInt32 minutes;
   double seconds;
};
typedef struct CFGregorianUnits CFGregorianUnits;
Discussion

A CFGregorianUnits is used to represent arbitrary time intervals (to represent a point in time using Gregorian units, use a CFGregorianDate). Each field can take values up to the maximum possible for its data type. Negative values are also valid.

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

CFTimeInterval

Type used to represent elapsed time in seconds.

typedef double CFTimeInterval;
Availability
  • Available in iOS 2.0 and later.
Declared In
CFDate.h

Constants

CFGregorianUnitFlags

These option flags are used as a mask to indicate a specific set of fields in the CFGregorianDate or CFGregorianUnits structures.

enum CFGregorianUnitFlags {
   kCFGregorianUnitsYears = (1 << 0),
   kCFGregorianUnitsMonths = (1 << 1),
   kCFGregorianUnitsDays = (1 << 2),
   kCFGregorianUnitsHours = (1 << 3),
   kCFGregorianUnitsMinutes = (1 << 4),
   kCFGregorianUnitsSeconds = (1 << 5),
   kCFGregorianAllUnits = 0x00FFFFFF
};
typedef enum CFGregorianUnitFlags CFGregorianUnitFlags;
Constants
kCFGregorianUnitsYears

Specifies the year field.

Available in iOS 2.0 and later.

Declared in CFDate.h.

kCFGregorianUnitsMonths

Specifies the month field.

Available in iOS 2.0 and later.

Declared in CFDate.h.

kCFGregorianUnitsDays

Specifies the day field.

Available in iOS 2.0 and later.

Declared in CFDate.h.

kCFGregorianUnitsHours

Specifies the hours field.

Available in iOS 2.0 and later.

Declared in CFDate.h.

kCFGregorianUnitsMinutes

Specifies the minutes field.

Available in iOS 2.0 and later.

Declared in CFDate.h.

kCFGregorianUnitsSeconds

Specifies the seconds field.

Available in iOS 2.0 and later.

Declared in CFDate.h.

kCFGregorianAllUnits

Specifies all fields.

Available in iOS 2.0 and later.

Declared in CFDate.h.

Discussion

These flags are used with functions such as CFGregorianDateIsValid and CFAbsoluteTimeGetDifferenceAsGregorianUnits which operate on a CFGregorianDate or CFGregorianUnits structure. For more details, see the discussion of those functions.

Declared In
CFDate.h

Predefined Time Interval Values

Time intervals between the absolute reference date and certain other dates.

const CFTimeInterval kCFAbsoluteTimeIntervalSince1970;
const CFTimeInterval kCFAbsoluteTimeIntervalSince1904;
Constants
kCFAbsoluteTimeIntervalSince1970

The time interval between 1 January 1970 and the reference date 1 January 2001 00:00:00 GMT.

Available in iOS 2.0 and later.

Declared in CFDate.h.

kCFAbsoluteTimeIntervalSince1904

The time interval between 1 January 1904 and the reference date 1 January 2001 00:00:00 GMT.

Available in iOS 2.0 and later.

Declared in CFDate.h.