One of the most common usage scenarios for NSData is the loading and writing of data via these calls:

func writeToURL(_ url: NSURL, atomically atomically: Bool) -> Bool
func writeToURL(_ url: NSURL, options writeOptionsMask: NSDataWritingOptions) throws
// ... (implementations for file: String instead of NSURL)
init?(contentsOfURL url: NSURL)
init(contentsOfURL url: NSURL, options readOptionsMask: NSDataReadingOptions) throws
// ... (implementations for file: String instead of NSURL)

For those basic usages, very little changed. The new Data type offers these methods:

init(contentsOf: URL, options: ReadingOptions)
func write(to: URL, options: WritingOptions)

Note that Data simplifies the various ways of reading and writing data from the file system into two calls while NSData offers multiple different methods.

Another difference can be observed when comparing the methods on NSData with those on Data. While NSData offers 30 methods & properties, Data offers 130. This huge difference is easily explained via Swift's formidable Protocol Extensions. Data obtains many of those methods from the following protocols:

• CustomStringConvertible
• Equatable
• Hashable
• MutableCollection
• RandomAccessCollection
• RangeReplaceableCollection
• ReferenceConvertible

This adds functionality to Data which did not exist in NSData. Here's a small sample:

func distance(from: Int, to: Int)
func dropFirst(Int)
func dropLast(Int)
func filter((UInt8) -> Bool)
func flatMap<ElementOfResult>((UInt8) -> ElementOfResult?)
func forEach((UInt8) -> Void)
func index(Int, offsetBy: Int, limitedBy: Int)
func map<T>((UInt8) -> T)
func max()
func min()
func partition()
func prefix(Int)
func reversed()
func sort()
func sorted()
func split(separator: UInt8, maxSplits: Int, omittingEmptySubsequences: Bool)
func reduce<Result>(Result, (partialResult: Result, UInt8) -> Result)

As you can see, many functional approaches, such as mapping or filtering can now be done on the byte contents of Data types. This, to me, is a huge improvement over NSData. An example of the benefits this brings is how easily you can now subscript and compare data:

var data = Data(bytes: [0x00, 0x01, 0x02, 0x03])  
print(data[2]) // 2
data[2] = 0x09
print (data == Data(bytes: [0x00, 0x01, 0x09, 0x03])) // true  

2
true

Data also offers several new initializers which specifically handle other common Swift data types:

init(bytes: Array<UInt8>)
init<SourceType>(buffer: UnsafeMutableBufferPointer<SourceType>)
init(repeating: UInt8, count: Int)

Another difference which you will run into if you're using Data to interact with lower level code such as C libraries is the distinct lack of the NSData getBytes method:

// NSData
func getBytes(_ buffer: UnsafeMutablePointer<Void>, length length: Int)

There're many different usage scenarious for getBytes. One of the most common is when you need to parse a file and read the bytes into data types / variables. A common example: Say you want to read a binary file which encodes a list of items. The file is encoded as follows:

The file contains a 4 byte string "ABCD" tagging it as the correct file type. The next 4 bytes define the start of the actual data (i.e. where the header ends and the items begin), the final 4 bytes in the header define the amount of items stored in this file.

Parsing this data with NSData is pretty straight forward:

let data = ...
var length: UInt32 = 0
var start: UInt32 = 0
data.getBytes(&start, range: NSRange(location: 4, length: 4))
data.getBytes(&length, range: NSRange(location: 8, length: 4))

This will return the correct result³. If your data does not contain C strings, there's an even easier way of doing this, you can simply define a struct with the correct fields and read the bytes directly into the struct:

let data = ...
struct Header { 
  let start: UInt32
  let length: UInt32
}
var header = Header(start: 0, length: 0)
data.getBytes(&header, range: NSRange(location: 0, length: 8))

However, if you're using Data this functionality is not available anymore. Instead, Data offers a new method:

// Access the bytes in the data.
func withUnsafeBytes<ResultType, ContentType>((UnsafePointer<ContentType>) -> ResultType)

This method allows direct access of the our data's bytes from within a closure. Let's see a simple example:

let data = Data(bytes: [0x01, 0x02, 0x03])
data.withUnsafeBytes { (pointer: UnsafePointer<UInt8>) -> Void in
    print(pointer)
    print(pointer.pointee)
}
// Prints: 
// : 0x00007f8dcb77cc50
// : 1

Ok, now that we have an unsafe UInt8 pointer into our data, how does this help us? First of fall, we obviously need a different data type, and we're sure (we have to be!) that the data is indeed of this particular data type. We know that this data contains a Int32 type, so how do we decode it correctly?

As we already have a unsafe pointer (of type UInt8) it is easy to move this into an unsafe pointer of our target type. UnsafePointer has a pointee property which returns the type that the pointer is pointing to as the correct type:

let data = Data(bytes: [0x00, 0x01, 0x00, 0x00])
let result = data.withUnsafeBytes { (pointer: UnsafePointer<Int32>) -> Int32 in
      return pointer.pointee
}
print(result)
//: 256

256

As you can see, we created a byte Data instance, and returned the data as Int32 by defining an UnsafePointer<Int32> in the closure. You can shorten this code if the compiler is able to infer the result type from the context:

let result: Int32 = data.withUnsafeBytes { $0.pointee }

One important consideration of using withUnsafeBytes (apart from the fact that the whole operation is unsafe) is that the lifetime of the pointer you're accessing is limited to the lifetime of your closure. As the documentation notes:

Warning The byte pointer argument should not be stored and used outside of the lifetime of the call to the closure.

Now that we have a way of accessing raw bytes and casting them to the correct type, we ought to create a generic solution that allows us to perform this operation easily without the syntactical overhead. Also, we still did not account for the fact that we need to perform the operation on a subsequence of our data and not the whole Data instance. A generic solution would look like this:

extension Data {
    func scanValue<T>(start: Int, length: Int) -> T {
        return self.subdata(in: start..<start+length).withUnsafeBytes { $0.pointee }
    }
}
let data = Data(bytes: [0x01, 0x02, 0x01, 0x02])
let a: Int16 = data.scanValue(start: 0, length: 1)
print(a)
// : 1

2

Compared to our earlier code, this has a couple of notable differences:

• We're using subdata to only scan the bytes of a specific slice of our Data.
• We're using generics to support different possible data types for extraction

The opposite case, taking an existing variable and getting a Data buffer to the content, is not relevant for the Doom example below, but easy enough to implement:

var variable = 256
let data = Data(buffer: UnsafeBufferPointer(start: &variable, count: 1))
print(data) // : <00010000 00000000>

<00010000 00000000 00000000 00000000>

I've played a lot of Doom in my youth. I loved the game. I also created a lot of Doom levels and modified the WAD file to incorporate new sprites, textures, and more. So when I thought about a nice (and simple) example of how to parse a binary file, I remembered the layout of the WAD file which is pretty straightforward and easy to implement. So I wrote a simple app that reads a WAD file and lists the names of all the floor textures stored in the WAD⁴.

The source code for this application is available on Github.

The Doom WAD file layout is described in these two documents:

• http://doom.wikia.com/wiki/WAD
• http://doomlegacy.sourceforge.net/hosted/doomspec1666.txt

However, for our simple example, we only need to understand a subset of the format. First, each WAD file begins with a header:

The first 4 bytes are spend to identify the file format. IWAD are official Doom WAD files, PWAD are patches containing additional information patched at runtime into the main WAD file. Our application will only read IWAD files. The next 4 bytes define the number of lumps in the WAD. Lumps are the individual items that the Doom engine operates with: Textures, Sprite-Frames, Text blocks, Models, etc. Each texture is a distinct lump. The final 4 bytes define the location of the directory. We'll explain the directory below, once we start parsing it. First, lets parse the header.

I find the new Data easier to work with than NSData. Nevertheless, if you need NSData or if you need to use the getBytes method, there's an easy way to convert Data to NSData. The Swift documentation writes:

This type provides “copy-on-write” behavior, and is also bridged to the Objective-C NSData class. You can wrap an instance of a custom subclass of NSData in struct Data by converting it using myData as Data.

// Create a new Data Struct
let aDataStruct = Data()
// Get the underlying reference type NSData
let aDataReference = aDataStruct as NSData

Whenever you feel that what you're trying to do seems to be really hard with the Data type, it is easy to go back to NSData to use the well known tried and trusted methods. However, in general you should strive to use the new Data type whenever possible (except if you need reference semantics):