Structure

Data

A byte buffer in memory.

Overview

The Data value type allows simple byte buffers to take on the behavior of Foundation objects. You can create empty or pre-populated buffers from a variety of sources and later add or remove bytes. You can filter and sort the content, or compare against other buffers. You can manipulate subranges of bytes and iterate over some or all of them.

Data bridges to the NSData class and its mutable subclass, NSMutableData. You can use these interchangeably in code that interacts with Objective-C APIs.

Topics

Creating Empty Data

init()

Creates an empty data buffer.

init(capacity: Int)

Creates an empty data buffer of a specified size.

init(count: Int)

Creates a new data buffer with the specified count of zeroed bytes.

func resetBytes(in: Range<Data.Index>)

Sets a region of the data buffer to 0.

Creating Populated Data

init()

Creates an empty data buffer.

init<S>(S)

Creates a new instance of a collection containing the elements of a sequence.

init?(base64Encoded: Data, options: Data.Base64DecodingOptions)

Creates a new data buffer from Base-64, UTF-8 encoded data.

init?(base64Encoded: String, options: Data.Base64DecodingOptions)

Creates a new data buffer from a Base-64 encoded string using the given options.

init<SourceType>(buffer: UnsafeBufferPointer<SourceType>)

Creates a data buffer with copied memory content using a buffer pointer.

init<SourceType>(buffer: UnsafeMutableBufferPointer<SourceType>)

Creates a data buffer with copied memory content using a mutable buffer pointer.

init(bytes: Array<UInt8>)

Creates a new data buffer with the contents of an array.

init(bytes: ArraySlice<UInt8>)

Creates a new data buffer with the contents of an array slice.

init(bytes: UnsafeRawPointer, count: Int)

Creates data with copied memory content.

init(bytesNoCopy: UnsafeMutableRawPointer, count: Int, deallocator: Data.Deallocator)

Creates a data buffer with memory content without copying the bytes.

init(capacity: Int)

Creates an empty data buffer of a specified size.

init(contentsOf: URL, options: Data.ReadingOptions)

Creates a data buffer with the contents of a URL.

init(count: Int)

Creates a new data buffer with the specified count of zeroed bytes.

init(referencing: NSData)

Creates a new data buffer by adopting a reference type.

init(repeating: UInt8, count: Int)

Creates a new collection containing the specified number of a single, repeated value.

Creating Data from Raw Memory

init(bytes: UnsafeRawPointer, count: Int)

Creates data with copied memory content.

init<SourceType>(buffer: UnsafeBufferPointer<SourceType>)

Creates a data buffer with copied memory content using a buffer pointer.

init<SourceType>(buffer: UnsafeMutableBufferPointer<SourceType>)

Creates a data buffer with copied memory content using a mutable buffer pointer.

init(bytesNoCopy: UnsafeMutableRawPointer, count: Int, deallocator: Data.Deallocator)

Creates a data buffer with memory content without copying the bytes.

enum Data.Deallocator

A deallocator you use to customize how the backing store is deallocated for data created with the no-copy initializer.

Reading and Writing Data

init(contentsOf: URL, options: Data.ReadingOptions)

Creates a data buffer with the contents of a URL.

func write(to: URL, options: Data.WritingOptions)

Writes the contents of the data buffer to a location.

typealias Data.ReadingOptions

Options to control the reading of data from a URL.

typealias Data.WritingOptions

Options to control the writing of data to a URL.

Base-64 Encoding

init?(base64Encoded: Data, options: Data.Base64DecodingOptions)

Creates a new data buffer from Base-64, UTF-8 encoded data.

init?(base64Encoded: String, options: Data.Base64DecodingOptions)

Creates a new data buffer from a Base-64 encoded string using the given options.

typealias Data.Base64DecodingOptions

Options to use when decoding data.

typealias Data.Base64EncodingOptions

Options to use when encoding data.

Counting Bytes

var isEmpty: Bool

A Boolean value indicating whether the collection is empty.

Accessing Bytes

subscript(Range<Data.Index>)

Accesses the bytes at the specified range of indexes.

subscript(Data.Index)

Accesses the byte at the specified index.

subscript(Range<Int>)

Accesses a contiguous subrange of the collection’s elements.

Adding Bytes

func append(UInt8)

Adds an element to the end of the collection.

func append(Data)

Appends the specified data to the end of this data.

func append(UnsafePointer<UInt8>, count: Int)

Appends the specified bytes from memory to the end of the data.

func append(contentsOf: [UInt8])

Appends the bytes in the specified array to the end of the data.

func insert(UInt8, at: Int)

Inserts a new element into the collection at the specified position.

func insert<C>(contentsOf: C, at: Int)

Inserts the elements of a sequence into the collection at the specified position.

func reserveCapacity(Int)

Prepares the collection to store the specified number of elements, when doing so is appropriate for the underlying type.

Removing Bytes

func remove(at: Int)

Removes and returns the element at the specified position.

func removeAll(keepingCapacity: Bool)

Removes all elements from the collection.

func removeFirst(Int)

Removes the specified number of elements from the beginning of the collection.

func removeLast(Int)

Removes the specified number of elements from the end of the collection.

func removeSubrange(Range<Int>)

Removes the elements in the specified subrange from the collection.

Replacing a Range of Bytes

func replaceSubrange(Range<Data.Index>, with: Data)

Replaces a region of bytes in the data with new data.

func replaceSubrange<ByteCollection>(Range<Data.Index>, with: ByteCollection)

Replaces a region of bytes in the data with new bytes from a collection.

func replaceSubrange<SourceType>(Range<Data.Index>, with: UnsafeBufferPointer<SourceType>)

Replaces a region of bytes in the data with new bytes from a buffer.

func replaceSubrange(Range<Data.Index>, with: UnsafeRawPointer, count: Int)

Replaces a region of bytes in the data with bytes from memory.

Finding Bytes

func first(where: (UInt8) -> Bool)

Returns the first element of the sequence that satisfies the given predicate.

func index(of: UInt8)

Returns the first index where the specified value appears in the collection.

func index(where: (UInt8) -> Bool)

Returns the first index in which an element of the collection satisfies the given predicate.

func max()

Returns the maximum element in the sequence.

func max(by: (UInt8, UInt8) -> Bool)

Returns the maximum element in the sequence, using the given predicate as the comparison between elements.

func min()

Returns the minimum element in the sequence.

func min(by: (UInt8, UInt8) -> Bool)

Returns the minimum element in the sequence, using the given predicate as the comparison between elements.

func range(of: Data, options: Data.SearchOptions, in: Range<Data.Index>?)

Finds the range of the specified data as a subsequence of this data, if it exists.

typealias Data.SearchOptions

Options that control a data search operation.

Selecting Bytes

func filter((UInt8) -> Bool)

Returns a new collection of the same type containing, in order, the elements of the original collection that satisfy the given predicate.

func prefix(Int)

Returns a subsequence, up to the specified maximum length, containing the initial elements of the collection.

func prefix(through: Int)

Returns a subsequence from the start of the collection through the specified position.

func prefix(upTo: Int)

Returns a subsequence from the start of the collection up to, but not including, the specified position.

func prefix(while: (UInt8) -> Bool)

Returns a subsequence containing the initial elements until predicate returns false and skipping the remaining elements.

func suffix(Int)

Returns a subsequence, up to the given maximum length, containing the final elements of the collection.

func suffix(from: Int)

Returns a subsequence from the specified position to the end of the collection.

Excluding Bytes

func dropLast()

Returns a subsequence containing all but the last element of the sequence.

func dropLast(Int)

Returns a subsequence containing all but the specified number of final elements.

func dropFirst()

Returns a subsequence containing all but the first element of the sequence.

func dropFirst(Int)

Returns a subsequence containing all but the given number of initial elements.

func drop(while: (UInt8) -> Bool)

Returns a subsequence by skipping elements while predicate returns true and returning the remaining elements.

func advanced(by: Int)

Returns a new data buffer created by removing the given number of bytes from the front of the original buffer.

Transforming Data

func reduce<Result>(Result, (Result, UInt8) -> Result)

Returns the result of combining the elements of the sequence using the given closure.

var lazy: LazyBidirectionalCollection<Data>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

var lazy: LazyCollection<Data>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

var lazy: LazySequence<Data>

A sequence containing the same elements as this sequence, but on which some operations, such as map and filter, are implemented lazily.

var lazy: LazyRandomAccessCollection<Data>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

Iterating Over Bytes

func forEach((UInt8) -> Void)

Calls the given closure on each element in the sequence in the same order as a for-in loop.

func enumerated()

Returns a sequence of pairs (n, x), where n represents a consecutive integer starting at zero, and x represents an element of the sequence.

func makeIterator()

Returns an iterator over the contents of the data.

struct Data.Iterator

An iterator that operates over the contents of data.

Sorting Bytes

func sort(by: (UInt8, UInt8) -> Bool)

Sorts the collection in place, using the given predicate as the comparison between elements.

func sorted()

Returns the elements of the collection, sorted.

func sorted(by: (UInt8, UInt8) -> Bool)

Returns the elements of the collection, sorted using the given predicate as the comparison between elements.

func reversed()

Returns a view presenting the elements of the collection in reverse order.

Splitting the Buffer

func subdata(in: Range<Data.Index>)

Returns a new copy of the data in a specified range.

func split(maxSplits: Int, omittingEmptySubsequences: Bool, whereSeparator: (UInt8) -> Bool)

Returns the longest possible subsequences of the collection, in order, that don’t contain elements satisfying the given predicate.

func split(separator: UInt8, maxSplits: Int, omittingEmptySubsequences: Bool)

Returns the longest possible subsequences of the collection, in order, around elements equal to the given element.

Comparing Data

static func ==(Data, Data)

Returns a Boolean value indicating whether or not two data buffers are equivalent.

func elementsEqual<OtherSequence>(OtherSequence)

Returns a Boolean value indicating whether this sequence and another sequence contain the same elements in the same order.

func elementsEqual<OtherSequence>(OtherSequence, by: (UInt8, UInt8) -> Bool)

Returns a Boolean value indicating whether this sequence and another sequence contain equivalent elements in the same order, using the given predicate as the equivalence test.

func starts<PossiblePrefix>(with: PossiblePrefix)

Returns a Boolean value indicating whether the initial elements of the sequence are the same as the elements in another sequence.

func starts<PossiblePrefix>(with: PossiblePrefix, by: (UInt8, UInt8) -> Bool)

Returns a Boolean value indicating whether the initial elements of the sequence are equivalent to the elements in another sequence, using the given predicate as the equivalence test.

func lexicographicallyPrecedes<OtherSequence>(OtherSequence)

Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the less-than operator (<) to compare elements.

func lexicographicallyPrecedes<OtherSequence>(OtherSequence, by: (UInt8, UInt8) -> Bool)

Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the given predicate to compare elements.

Manipulating Indexes

typealias Data.Index

A type used to indicate a position in a data's buffer.

var startIndex: Data.Index

The beginning index into the data.

var endIndex: Data.Index

The end index into the data.

func index(Int, offsetBy: Int)

Returns an index that is the specified distance from the given index.

func index(after: Data.Index)

Returns the index that immediately follows the specified index.

func index(before: Data.Index)

Returns the index that immediately precedes the specified index.

Manipulating Index Ranges

typealias Data.Indices

A type used to indicate a range of positions in a data's buffer.

var indices: DefaultRandomAccessIndices<Data>

The indices that are valid for subscripting the collection, in ascending order.

func distance(from: Int, to: Int)

Returns the distance between two indices.

Describing Data

var description: String

A textual description of the data.

var debugDescription: String

A textual description the data suitable for debugging.

var customMirror: Mirror

A mirror that reflects the data.

var hashValue: Int

The hash value for the data.

Using Reference Types

class NSData

A static byte buffer that bridges to Data; use NSData when you need reference semantics or other Foundation-specific behavior.

class NSMutableData

A dynamic byte buffer that bridges to Data; use NSMutableData when you need reference semantics or other Foundation-specific behavior.

typealias Data.ReferenceType

An alias for this value type's equivalent reference type.

Instance Properties

var count: Int

The number of elements in the collection.

var first: UInt8?

The first element of the collection.

var indices: CountableRange<Int>

The indices that are valid for subscripting the collection, in ascending order.

var last: UInt8?

The last element of the collection.

var underestimatedCount: Int

A value less than or equal to the number of elements in the collection.

var underestimatedCount: Int

Returns a value less than or equal to the number of elements in the sequence, nondestructively.

Instance Methods

func append<S>(contentsOf: S)

Adds the elements of a sequence or collection to the end of this collection.

func map<T>((UInt8) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

func map<T>((UInt8) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

func popFirst()

Removes and returns the first element of the collection.

func popLast()

Removes and returns the last element of the collection.

func reduce<Result>(into: Result, (inout Result, UInt8) -> ())

Returns the result of combining the elements of the sequence using the given closure.

func removeFirst()

Removes and returns the first element of the collection.

func removeFirst()

Removes and returns the first element of the collection.

func removeFirst()

Removes and returns the first element of the collection.

func removeFirst(Int)

Removes the specified number of elements from the beginning of the collection.

func removeFirst(Int)

Removes the specified number of elements from the beginning of the collection.

func removeLast()

Removes and returns the last element of the collection.

func removeLast()

Removes and returns the last element of the collection.

func removeLast()

Removes and returns the last element of the collection.

func removeLast(Int)

Removes the specified number of elements from the end of the collection.

func removeLast(Int)

Removes the given number of elements from the end of the collection.

func removeSubrange<R>(R)

Removes the elements in the specified subrange from the collection.

func replaceSubrange<C, R>(R, with: C)

Replaces the specified subrange of elements with the given collection.

func swapAt(Int, Int)

Exchanges the values at the specified indices of the collection.

Subscripts

Operator Functions

static func !=(Data, Data)

Returns a Boolean value indicating whether two values are not equal.