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 data buffer 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.

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 buffer is empty.

Adding Bytes

func append(UInt8)

Adds a byte to the end of the data.

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 data's buffer at the specified position.

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

Inserts the elements of a sequence into the data's buffer at the specified position.

func reserveCapacity(Int)

Reserves enough space to store the specified number of bytes.

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 byte of the buffer that satisfies the given predicate.

func index(of: UInt8)

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

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

Returns the first index in which a byte of the buffer 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 an array containing, in order, the bytes of the buffer that satisfy the given predicate.

func prefix(Int)

Returns a subsequence, up to the specified maximum length, containing the initial bytes of the data's buffer.

func prefix(through: Int)

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

func prefix(upTo: Int)

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

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

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

func suffix(Int)

Returns a subsequence, up to the given maximum length, containing the final bytes of the buffer.

func suffix(from: Int)

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

Excluding Bytes

func dropLast()

Returns a subsequence containing all but the last byte of the buffer.

func dropLast(Int)

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

func dropFirst()

Returns a subsequence containing all but the first byte in the buffer.

func dropFirst(Int)

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

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

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

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 buffer in place, using the given predicate as the comparison between elements.

func sorted()

Returns the elements of the buffer sorted.

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

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

func reversed()

Returns a view presenting the elements of the buffer 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 buffer, 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 buffer, 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 data and another data contain the same elements in the same order.

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

Returns a Boolean value indicating whether this data and another data contain equivalent elements, 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 buffer, 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.

Operator Functions