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(_:allocator:) 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(_:otherRange:)) 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(start: CMTime, duration: CMTime) -> CMTimeRange

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

func CMTimeRangeMakeFromDictionary(CFDictionary) -> CMTimeRange

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

func CMTimeRangeFromTimeToTime(start: CMTime, end: CMTime) -> CMTimeRange

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

Comparing Time Ranges

func CMTimeRangeEqual(CMTimeRange, CMTimeRange) -> Bool

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

func CMTimeRangeContainsTime(CMTimeRange, time: CMTime) -> Bool

Indicates whether a time is contained within a time range.

func CMTimeRangeContainsTimeRange(CMTimeRange, otherRange: CMTimeRange) -> Bool

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

Utility Functions

func CMTimeClampToRange(CMTime, range: CMTimeRange) -> CMTime

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

func CMTimeMapDurationFromRangeToRange(CMTime, fromRange: CMTimeRange, toRange: CMTimeRange) -> CMTime

Translates a duration through a mapping from CMTimeRange to CMTimeRange.

func CMTimeMapTimeFromRangeToRange(CMTime, fromRange: CMTimeRange, toRange: CMTimeRange) -> CMTime

Translates a time through a mapping from CMTimeRange to CMTimeRange.

func CMTimeRangeCopyDescription(allocator: CFAllocator?, range: CMTimeRange) -> CFString?

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.