iOS Developer Library

Developer

CoreFoundation Framework Reference Time Utilities Reference

Options
Deployment Target:

On This Page
Language:

Time Utilities Reference

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

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

    Declaration

    Swift

    func CFAbsoluteTimeAddGregorianUnits(_ at: CFAbsoluteTime, _ tz: CFTimeZone!, _ units: CFGregorianUnits) -> CFAbsoluteTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

  • Returns the current system absolute time.

    Declaration

    Swift

    func CFAbsoluteTimeGetCurrent() -> CFAbsoluteTime

    Objective-C

    CFAbsoluteTime CFAbsoluteTimeGetCurrent ( void );

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFAbsoluteTimeGetDayOfWeek(_ at: CFAbsoluteTime, _ tz: CFTimeZone!) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

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

    Declaration

    Swift

    func CFAbsoluteTimeGetDayOfYear(_ at: CFAbsoluteTime, _ tz: CFTimeZone!) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

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

    Declaration

    Swift

    func CFAbsoluteTimeGetDifferenceAsGregorianUnits(_ at1: CFAbsoluteTime, _ at2: CFAbsoluteTime, _ tz: CFTimeZone!, _ unitFlags: CFOptionFlags) -> CFGregorianUnits

    Objective-C

    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);

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

  • Converts an absolute time value into a Gregorian date.

    Declaration

    Swift

    func CFAbsoluteTimeGetGregorianDate(_ at: CFAbsoluteTime, _ tz: CFTimeZone!) -> CFGregorianDate

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

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

    Declaration

    Swift

    func CFAbsoluteTimeGetWeekOfYear(_ at: CFAbsoluteTime, _ tz: CFTimeZone!) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

  • Converts a Gregorian date value into an absolute time value.

    Declaration

    Swift

    func CFGregorianDateGetAbsoluteTime(_ gdate: CFGregorianDate, _ tz: CFTimeZone!) -> CFAbsoluteTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

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

    Declaration

    Swift

    func CFGregorianDateIsValid(_ gdate: CFGregorianDate, _ unitFlags: CFOptionFlags) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

Data Types

Miscellaneous

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

    Declaration

    Swift

    typealias CFAbsoluteTime = CFTimeInterval

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    struct CFGregorianDate { var year: Int32 var month: Int8 var day: Int8 var hour: Int8 var minute: Int8 var second: Double }

    Objective-C

    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.

    Deprecated in iOS 8.0.

  • Structure used to represent a time interval in Gregorian units.

    Declaration

    Swift

    struct CFGregorianUnits { var years: Int32 var months: Int32 var days: Int32 var hours: Int32 var minutes: Int32 var seconds: Double }

    Objective-C

    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.

    Deprecated in iOS 8.0.

  • Type used to represent elapsed time in seconds.

    Declaration

    Swift

    typealias CFTimeInterval = Double

    Objective-C

    typedef double CFTimeInterval;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Constants

Miscellaneous

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

    Declaration

    Swift

    struct CFGregorianUnitFlags : RawOptionSetType { init(_ rawValue: CFOptionFlags) init(rawValue rawValue: CFOptionFlags) static var UnitsYears: CFGregorianUnitFlags { get } static var UnitsMonths: CFGregorianUnitFlags { get } static var UnitsDays: CFGregorianUnitFlags { get } static var UnitsHours: CFGregorianUnitFlags { get } static var UnitsMinutes: CFGregorianUnitFlags { get } static var UnitsSeconds: CFGregorianUnitFlags { get } static var AllUnits: CFGregorianUnitFlags { get } }

    Objective-C

    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

    • UnitsYears

      kCFGregorianUnitsYears

      Specifies the year field.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • UnitsMonths

      kCFGregorianUnitsMonths

      Specifies the month field.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • UnitsDays

      kCFGregorianUnitsDays

      Specifies the day field.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • UnitsHours

      kCFGregorianUnitsHours

      Specifies the hours field.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • UnitsMinutes

      kCFGregorianUnitsMinutes

      Specifies the minutes field.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • UnitsSeconds

      kCFGregorianUnitsSeconds

      Specifies the seconds field.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • AllUnits

      kCFGregorianAllUnits

      Specifies all fields.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    let kCFAbsoluteTimeIntervalSince1970: CFTimeInterval let kCFAbsoluteTimeIntervalSince1904: CFTimeInterval

    Objective-C

    const CFTimeInterval kCFAbsoluteTimeIntervalSince1970; const CFTimeInterval kCFAbsoluteTimeIntervalSince1904;

    Constants

    • kCFAbsoluteTimeIntervalSince1970

      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.

    • kCFAbsoluteTimeIntervalSince1904

      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.