CMTimeRange

A struct representing a range of time.

Overview

This document describes the API for creating and manipulating CMTimeRange structures.

CMTimeRange structs are non-opaque mutable structures that represent time ranges. A CMTimeRange is represented as two CMTime structs, one that specifies the start time of the range and another that specifies the duration of the range. A time range does not include the end time that would be calculated by adding the duration to the start time. The following expression will always evaluate to false:

CMTimeRangeContainsTime(range, CMTimeRangeGetEnd(range))

You can convert CMTimeRanges to and from CFDictionaries (see CFDictionaryRef) using CMTimeRangeCopyAsDictionary and CMTimeRangeMakeFromDictionary, for use in annotations and various Core Foundation containers.

The epoch in a CMTime that represents a duration should always be 0, and the value must be non-negative. The epoch in a CMTime that represents a timestamp may be non-zero, but range operations (such as CMTimeRangeGetUnion) can only be performed on ranges whose start fields have the same epoch. CMTimeRanges cannot span different epochs.

Additional functions for managing dates and times are described in Time Utilities; see also AVFoundation Constants.

Topics

Creating Time Ranges

CMTimeRangeMake

Creates a valid CMTimeRange with the given start time and duration.

CMTimeRangeMakeFromDictionary

Reconstitutes a CMTimeRange struct from a CFDictionary previously created by CMTimeRangeCopyAsDictionary.

CMTimeRangeFromTimeToTime

Creates a valid CMTimeRange from the given start and end time.

Comparing Time Ranges

CMTimeRangeEqual

Returns a Boolean value that indicates whether two CMTimeRanges are identical.

CMTimeRangeContainsTime

Indicates whether a time is contained within a time range.

CMTimeRangeContainsTimeRange

Returns a Boolean that indicates whether a given time range is contained within another time range.

Inspecting Time Ranges

CMTIMERANGE_IS_EMPTY

Returns a Boolean value that indicates whether a given CMTimeRange has a duration of 0.

CMTIMERANGE_IS_INDEFINITE

Returns a Boolean value that indicates whether a given CMTimeRange is indefinite.

CMTIMERANGE_IS_INVALID

Returns a Boolean value that indicates whether a given CMTimeRange is invalid.

CMTIMERANGE_IS_VALID

Returns a Boolean value that indicates whether a given CMTimeRange is valid.

CMTimeRangeGetEnd

Returns a CMTime structure representing the end of a time range.

CMTimeRangeGetIntersection

Returns the intersection of two CMTimeRanges.

CMTimeRangeGetUnion

Returns the union of two CMTimeRanges.

Utility Functions

CMTimeClampToRange

For a given CMTime and CMTimeRange, returns the nearest CMTime inside that time range.

CMTimeMapDurationFromRangeToRange

Translates a duration through a mapping from CMTimeRange to CMTimeRange.

CMTimeMapTimeFromRangeToRange

Translates a time through a mapping from CMTimeRange to CMTimeRange.

CMTimeRangeCopyAsDictionary

Returns a CFDictionary version of a CMTimeRange.

CMTimeRangeCopyDescription

Creates a CFString with a description of a CMTimeRange (similar to CFCopyDescription).

CMTimeRangeShow

Prints a description of the CMTimeRange to stderr (similar to CFShow).

Data Types

CMTimeRange

A time range represented as two CMTime structures.

Constants

CFDictionary Keys

Keys for components in a CFDictionary representation of a CMTimeRange.

Pre-Specified Time Ranges

These constants specify zero and invalid time ranges.

See Also

Time Representation

CMTime

A struct representing a time value such as a timestamp or duration.

CMTimeMapping

A struct used to specify the mapping of a segment of one time line into another.