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

func CMTimeRangeMake(CMTime, CMTime)

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

func CMTimeRangeMakeFromDictionary(CFDictionary)

Reconstitutes a CMTimeRange struct from a CFDictionary previously created by CMTimeRangeCopyAsDictionary(_:_:).

func CMTimeRangeFromTimeToTime(CMTime, CMTime)

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

Comparing Time Ranges

func CMTimeRangeEqual(CMTimeRange, CMTimeRange)

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

func CMTimeRangeContainsTime(CMTimeRange, CMTime)

Indicates whether a time is contained within a time range.

func CMTimeRangeContainsTimeRange(CMTimeRange, CMTimeRange)

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

Utility Functions

func CMTimeClampToRange(CMTime, CMTimeRange)

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

func CMTimeMapDurationFromRangeToRange(CMTime, CMTimeRange, CMTimeRange)

Translates a duration through a mapping from CMTimeRange to CMTimeRange.

func CMTimeMapTimeFromRangeToRange(CMTime, CMTimeRange, CMTimeRange)

Translates a time through a mapping from CMTimeRange to CMTimeRange.

func CMTimeRangeCopyAsDictionary(CMTimeRange, CFAllocator?)

Returns a CFDictionary version of a CMTimeRange.

func CMTimeRangeCopyDescription(CFAllocator?, CMTimeRange)

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

func CMTimeRangeShow(CMTimeRange)

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

Data Types

struct 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.