We use documents to store and organize data in the apps that we use.
This is a simple description of how and why we use documents with mobile apps built with macOS and iOS. There’s much more than this simple description to consider when you start working with documents, and this chapter goes into the basic details you need to consider. You can find many books and articles dealing with documents, but the key points are described here.
Describing a Document
When you use an app, you sometimes need to store data for the app (that’s the basic description just mentioned). Storing data turns out to be far from simple because when we talk about storing data, we almost always mean storing and retrieving data on demand. For that store-and-retrieve process to be useful to developers and users, you need to be able to identify the data to be stored and retrieved, such as the current temperature.
You need to be able to identify the physical location of the data to be stored and retrieved.
You need to be able to identify the logical characteristics of the data to be stored and retrieved.
Putting this together means that you need to be able to store, retrieve, and identify data by its location and characteristics (such as a name).
Keeping Track of a Document and Its Data
We are accustomed to thinking of documents as static objects: once a document is written or printed, it doesn’t appear to change. You can make changes or edits to documents, but those changes are typically visible in one way or another so that the initial document is modified. In the digital world, changes can be continual, and thinking of a document as a static object is misleading, to say the least.
When you use word processing tools, you can often track changes to documents so that instead of a static document you may have a multitude of changed documents. This multitude of changed documents can proliferate quickly not only with word processing documents but also with changes using tools such as Git or GitHub.
Structuring a Document
Documents can be structured in any way that the developer chooses. As you will see in Chapter 2, you can use structures that you create or common structures that are defined by others. The structure of a document provides a structure (or format) for the data that the document will contain. When you know a document’s structure, you can read or write its data.
At least that is the idea. Document structures can change over time so in practice you need to know not only the structure of a document but the specific variation of the structure in use.
Note
The variation of a document’s structure is often referred to as a version.
Handling Document Versions
A common way of handling the issue of document versions is to create a document structure that has at least two components: one is the version identifier and the second is everything else. For example, a document can start with the version identifier, which might be something as simple as a string or even an integer. In that way, your app will know to read a single integer or a string of X characters from the beginning of a document’s data. That integer or string lets your app identify the version; having done that, your app can read the data for that version. This strategy is commonly used in macOS and iOS using a file manager (described in Chapter 2).
Comparing Documents and Files
Documents store data for an app in a known location from which it can be retrieved (or to which it can be stored). This location is typically a file—an object that is managed by the operating system. Like documents themselves, files can also have versions. A significant difference between a file and a document is that in many cases, the operating system manages a file’s opening, closing, and storage. A document in many cases is inside a file.
Note
This is a simplification and generalization.
Structuring a Document and an App
Apps that are based on data are easy to build or convert to document-based apps. There are two common ways of building such apps. In the first way, developers start from a data structure and add functionality to it. In the other way, developers start from functionality and add data to it.
Summary
In this chapter, you saw an overview of documents, versions, and the differences between documents and files. From here you will move onto the details of documents and how to use them effectively.
Today, JSON (JavaScript Object Notation) and the Codable protocols are commonly used for managing app data. Previously, a technology referred to as coding was commonly used to store and manage data that is internal to an app. The basic process was to convert data that is identified by keys to and from NSData objects. The operating systems support NSData, and you don’t have to worry about the implementation: it is fast and efficient. The only limitation is that not every type of data can be archived.
If you are building an app that needs to manage persistent data, chances are that Codable is the way to go. If you are modifying an existing app, you may want to continue using the archiving code that already exists. (Using both is perfectly feasibly, but it can become a maintenance nightmare.)