Vinh Nguyen's Blog

How to ignore/hide changes from Git

Wed, 17 Mar 2021 00:00:00 +0000

Git is a popular distributed version control system, which helps keeping track of changes less hassle. In some scenarios, we might want Git to ignore some changes or hide them from Git. In this post, we’ll explore a couple of ways to do so.

Basics

Let’s go back basics first. There’re 3 states in Git, namely modified, staged and committed. These states apply to files on which Git has an eye. For those Git doesn’t track yet, we have another state named untracked—they are listed under Untracked files when git status. Files are either modified, staged or committed can be seen as tracked ones.

We human only see working directory and files in it just like what we see when ls. Working directory is nothing but a directory created when we clone a Git repo, it’s an ordinary directory in a filesystem. Whenever we modify, add or remove files in working directory, we see only one version of them at that moment. If another person looks at working directory later, they can’t tell what changes we made. That another person is Git. Git wouldn’t be so useful, if it sorely relied on working directory. Therefore, Git adds another place called index which aids in detecting differences. Index is a version of working directory, any changes we make in working directory are compared to index, and from there Git can keep track of changes.

Connect this to states above, we can think of tracked files are indexed files—files are added to index—and vice versa.

Untracked files

A common example for untracked files—if you’re using macOS—is the metadata file .DS_Store. We usually put this file in .gitignore. .gitingore is used when we want to share ignored files with other people since it’s always committed in a Git repo.

How about if we want to ignore some locally only, and not to share or modify .gitignore? $GIT_DIR/info/exclude has the same effect as .gitignore, except it’s only applicable locally in a specific repo. $GIT_DIR is actually .git folder in a working directory after we clone from a Git repo. All things behind the scene of Git are stored in this folder, and we can call it the Git repo itself.

To make these files observable again from Git, we simply remove them from .gitignore or $GIT_DIR/info/exclude.

Tracked files

Now the fun part comes. How do we temporarily hide tracked files from Git? A use case for it could be a shared configuration file. Usually, it’s committed and shared among people, but we need to change some of its values while tinkering and also don’t want the noise when git status—the file will be listed in Changes not staged for commit. We can use git update-index --skip-worktree <files> for this purpose. git update-index is a low-level command, a plumbing one in Git parlance, which allows us to manipulate Git index. --skip-worktree option tells Git to pretend that a file in working directory isn’t changed—even it’s in fact—so that the file is treated as unmodified on comparing to index. As a result, we won’t see the file in Changes not staged for commit.

To undo, we use git update-index --no-skip-worktree <files>. It’s straightforward if we remember files, otherwise it would be not so obvious to find out. Luckily, git ls-files -v comes to rescue. Files start S tag are ones we skipped.

Summary

For untracked files, .gitignore or $GIT_DIR/info/exclude depends on whether or not we want to shared these ignore files respectively.

For tracked files, git update-index --skip-worktree <files> will do the job, and git ls-files-v is nice to help when we need to undo.

The Essentials of Essential Front-end Tools, ESLint

Sat, 03 Aug 2019 00:00:00 +0000

Recently, I’ve been getting more involved in front-end development. The more I do, the more my mind and my soul get lost in its chaotic world. Even a simple To–Do–List app can easily require a bunch of tools—ESLint, Babel, Webpack, to name a few—and packages just to get started. Fortunately, there’re many starter kits out there so we don’t have to do from the ground up. With them, everything is already set up so we can start writing the first line of code right away. It saves time on repetitive, boring tasks, which can be great for experienced developers. However, this benefit comes with a price for beginners. Since everything works out of the box, it seems like magic, and they might not know what’s really happening under the hood, which is important to understand at some level. Although the learning curve is not as steep as others—try to compare with some tools you’ve been learning and using, you’ll get what I mean—in the chaotic world, we need a survival guide for the journey.

This series will cover fundamental tools of front-end development and what essential we need to know—to rule the tools instead of being controlled by them. In it, we’ll focus on the developer experience of each one of these tools so the goal of this series is to act as a survival guide and to give a high-level overview of each tool, not to serve as a documentation.

What will be included:

ESLint <- We are here
Babel
Webpack
Flow
TypesScript
Jest.

Enough of preface, let’s get started with the first tool, ESLint.

What is ESLint and Why?

ESLint is, as the name implies, a linter for ECMAScript. And, the definition of a linter is:

a machine for removing the short fibers from cotton seeds after ginning.

Although code and cotton seeds don’t have any relationship, regardless of code or cotton seeds, a linter will help make things cleaner and more consistent. We don’t want to see the code like this:

const count = 1;
const message = "Hello, ESLint";
count += 1;

It both looks ugly and has a mistake. Here’s when ESLint steps in to help with that. Instead of letting the error be dumped out to the browser console when we run the code, ESLint will catch it as we’re typing—not really, we’ll need editor or IDE extensions for this, which will be covered later. Obviously, this error isn’t difficult to figure out, but wouldn’t it be nicer to have an assistant reminding us every time we’re about to make a mistake and perhaps auto-correcting it for us? Although ESLint can’t catch all kinds of errors, it at least spares us some effort so we can spend on other things that matter and need human attention.

How does ESLint work?

Now that we know what ESLint is and why we need it, let’s go a bit deeper and check out how it works. In essence, we can break it down to three big steps.

Parser

The code that we write is nothing more than a sequence of characters. However, this sequence isn’t just random characters, they need to follow a set of rules or conventions that is the grammar forming a language. For a human, going from reading text or code to understanding it conceptually takes us little effort. For a computer, this is much more difficult to accomplish. For example:

const tool = "ESLint"; // 1
const tool = "ESLint"; // 2

As we read the two lines above, we immediately know that they are identical, and can be read as “there’s a constant named tool with the value of ESLint”. For a computer, which doesn’t understand the meaning, these two lines look quite different. As a result, if we feed in raw code to ESLint, it’s nearly impossible to do anything. When things get complicated and hard to communicate—think of how we can have a computer to understand what we do—abstraction can be an escape. By abstracting a thing, we hide all unnecessary details, reduce noise, and keep everyone on the same page, which eases the communication. In the above example, one space or two spaces don’t matter, neither do single quotes or double quotes.

In other words, that’s what a parser does. It converts raw code to an Abstract Syntax Tree (AST), and this AST is used as the medium for lint rules to base on. There are still many steps a parser need to do in order to create an AST—if you’re interested in learning more about how an AST is generated, this tutorial has a good overview.

Rules

The next step in the process is to run the AST through a list of rules. A rule is a logic of how to figure out potential existing issues in the code from the AST. Issues here aren’t necessary syntactic or semantic errors but might be stylistic ones as well. The output given out from a rule will include some useful information for later use like lines of code, positions, and informative messages about the issue.

In addition to catching issues, a rule can even auto-correct code if possible. For example, when no-multi-spaces is applied to the code above, it will trim all redundant spaces, which makes the code look clean and consistent.

const tool = "ESLint"; // 2
// becomes
const tool = "ESLint"; // 2

In different scenarios, a rule can be used at different levels—opted-out, warning only, or strict error—and have various options, which gives us control on how to use the rule.

Result

Here comes the end of the process. With the output from a rule, it’s just the matter of how we display it in a human friendly manner, thanks to all the useful information we mentioned earlier. Then from the result, we can quickly point out the issue, where it is, and make a fix, or maybe not.

Integration

ESLint can be used as a standalone tool with its robust CLI, but that’s a bare-bones way to use ESLint. We don’t want to type in a command every time we want to lint code, especially in a development environment. The solution for this is to integrate ESLint into our development environment so we can write code and see issues caught by ESLint all in one place.

This kind of integration comes from extensions specific to IDEs or editors. These extensions require ESLint to work since they run ESLint behind the scene—no wonder that we still need to install ESLint along with them, they are nothing without ESLint. This principle applies to other IDE or editor extensions we are using daily.

Remember the output from a rule we talked above? An extension will use it to display in the IDE or editor. How exactly the output is displayed depends on how the extension is implemented and how the IDE or editor is open to its extensions. Some extensions also take advantage of the abilities of issue correction from rules to change code on save if we enable it.

Configuration

Configuration is the main power that gives the versatility to a tool. ESLint is not different from that, except it has the most comprehensive configuration among other tools. In general, we need a file or a place to put the configuration, and there’s a couple of options of us. All of them boil down to two main ways, either we have a separate configuration file for each tool or bundle them all in package.json. .eslintrc.js is one of the files that ESLint will be looking for its configuration, and also the one with the highest priority.

The next thing we need to know about configuration is its hierarchy and cascading behavior. Thanks to these features, we don’t need to have a configuration file in every single folder in the project. If a configuration file doesn’t exist in a folder, ESLint simply looks up the folder’s parent for one until it can’t find anyone, then it’ll fall back to the user–wide default configuration in ~/.eslintrc. Otherwise, the configuration file will add up or override the ones at upper levels.

There’s, however, a special tweak on this. If we specify root: true in a configuration file, the lookup will stop at that file instead of going up like before. Besides, ESLint will use that configuration file as the root configuration, all child configurations will base on this one.

Not only limited to ESLint, but these things are common for other tools. Let’s talk about ESLint specific configuration.

Parser

The role of parser in ESLint has been discussed above. By default, ESLint uses Espree as its parser. We can change this parser to another compatible one like babel-eslint or @typescript-eslint/parser if we use Babel or Typescript respectively.

To configure the parser, we use parserOptions. Among options supported by Espree, here are some we often use and need to pay attention.

ecmaVersion

We need to specify the appropriate ECMA version to features we want to use. For example, if emcaVersion: 5, the code below will give some errors.

javascript let a = [1, 2, 3, 4] // error due to `let` keyword var b = [...a, 5] // error due to spread syntax

The parser can’t parse the code because both let keyword and spread syntax are just introduced in ES6. Changing emcaVersion to 6 or above will simply resolve the errors.

sourceType

Nowadays, we mostly write everything in modules, then bundle them together so this option, most the time, should be module. Another value we can use—as well as the default—is script. The difference is whether we can use JS modules or not, i.e., use import and export keyword. The next time we get this error message Parsing error: 'import' and 'export' may appear only with 'sourceType: module', we know where to look at.

ecmaFeatures.jsx

There might be additional ES features we want to use, for example JSX syntax. We use ecmaFeatures.jsx: true to enable this feature. Note that, JSX support from Espree isn’t the same as JSX in React so if we want React specific JSX, we should use eslint-plugin-react for better result.

If we use another parser, these options are more or less the same. Some might have fewer options, others might have more, but they’re all defined under parserOptions.

Environment

Depends on where the code is running, there are different predefined global variables, we have window, document in browser for example. It would be irritating if no-undef rule is enabled, and ESLint keeps telling us window or document is not defined.

The env option is here to help. By specifying a list of environments, ESLint will know about global variables in these environments, and let us use them without a word.

There’s a special environment needed to note, es6. It’ll implicitly set parserOptions.ecmaVersion to 6, and enable all ES6 features except for modules which we still need to use parserOptions.sourceType: "module" separately.

Plugins and Shareable Configs

Having the same configuration for rules over and over again across different projects might be tiresome. Luckily, we can reuse a configuration, and only override rules as needed with extends. We call this type of configs, shareable configs, and ESLint already has two for us, eslint:recommended and eslint:all. Conventionally, ESLint’s shareable configs have eslint-config prefix so we can easily find them via NPM with eslint-config keyword. Among hundreds of results, there’re some popular ones, like eslint-config-airbnb or eslint-config-google, you name it.

Out of the box, ESLint has a bunch of rules to serve different purposes from possible errors, best practices, ES6 to stylistic issues. Moreover, to supercharge its ability, ESLint has a great number of 3rd-party rules provided by almost a thousand of plugins. Similar to shareable configs, ESLint’s plugins are prefixed with eslint-plugin, and available on NPM with eslint-plugin keyword.

What a plugin does is to define a set of new rules, and in most cases to expose its own some handy configs. For example, eslint-plugin-react gives us two shareable configs, eslint-plugin-react:recommended and eslint-plugin-react:all just like eslint:recommended and eslint:all. To use one of them, we need to, firstly, define the plugin name, secondly extend the config.

{
  plugins: ["react"],
  extends: "plugin:react/recommended"
}

// Note that we need to prefix the config by `plugin:react`

One common question to ask is what plugins or configs to use. While it largely depends on our needs, we can use Awesome ESLint as a reference to find useful plugins as well as configs.

Prettier

We’re almost there, we almost go to the end. Last but not least, we’ll discuss a popular pair of ESLint, Prettier. In short, Prettier is an opinionated code formatter. Though Prettier can be used alone, integrating it to ESLint enhances the experience a lot, and eslint-plugin-prettier does this job.

The difference between the usage of Prettier alone and Prettier with ESLint can be summarized to code formatting as an issue. Instead of giving format issues separately, running Prettier with ESLint will treat format issues just like other issues. However, these issues are always fixable, which is equivalent to formatting the code. That’s how eslint-plugin-prettier works. It runs Prettier, as a rule, behind the scene and compares the code before and after being run through Prettier. Finally, it reports differences as individual ESLint issues. To fix these issues, the plugin simply uses the formatted code from Prettier.

To have this integration, we need to install both prettier and eslint-plugin-prettier. eslint-plugin-prettier also comes with eslint-plugin-prettier:recommended config—extends eslint-config-prettier, therefore we also need to install eslint-config-prettier—to use.

{
  "plugins": ["prettier"],
  "extends": "plugin:prettier/recommended"
}

Conclusion

Code linter or formatter has become de facto standard in software development in general, and ESLint, specifically in front-end development. Its benefit is far beyond what it does technically, it helps developers focus on more important matters. Thanks to delegating code styling to machine, we can avoid opinionated styles on code review, and use that time instead for more meaningful code review. Code quality also benefits from there, more consistent and less error-prone code.

ReSwift, a weird use case

Sat, 12 Aug 2017 00:00:00 +0000

ReSwift, a weird use case

ReSwift is a library helping you construct unidirectional data flow architecture in your application. If you’ve already known Redux, think of ReSwift as a Swift implementation of it. I’ve tried ReSwift in my project, and I love it. It’s lean, easy to understand and easy to write. As always, however, practical use is far more than theory or the introduction at first glance. The more I use, the more problem I explore and need to deal with them. In this post, I’ll discuss my use case of ReSwift.

ReSwift in brief

Before discussing the use case, let’s give ReSwift a quick rewind. Here, I recall a few principles on which ReSwift relies (from its README):

The Store stores your entire app state in the form of a single data structure. This state can only be modified by dispatching Actions to the store. Whenever the state in the store changes, the store will notify all observers.
Actions are a declarative way of describing a state change. Actions don’t contain any code, they are consumed by the store and forwarded to reducers. Reducers will handle the actions by implementing a different state change for each action.
Reducers provide pure functions, that based on the current action and the current app state, create a new app state.

The above is just high-level description about store, actions, and reducers. In practical use, you might want break one big app state down into many smaller states to work with easily. So are reducers, each reducer will take care of an appropriate state. Action is simply a structure to encapsulate information needed to change the state.

The use case, first introduction

Now, let’s talk about the use case. To keep it short and simple, what I want is visualized below.

There’re 3 main components: canvas, block, and object. The relationship between them is described as: Only one canvas contains one or many blocks; Each block contains one or many objects. Based on this relationship, I can define the appropriate basic state for each.

struct CanvasState: StateType {
    var blockStates: [BlockState]
}

struct BlockState: StateType {
    var frame: CGRect
    var objectStates: [ObjectState]
}

struct ObjectState: StateType {
    var frame: CGRect
}

I have CanvasView, BlockView and ObjectView corresponding these components, and each will display its state.

class CanvasView: StoreSubscriber {
    func newState(state: CanvasState) { }
}

class BlockView: StoreSubscriber {
    func newState(state: BlockState) { }
}

class ObjectView: StoreSubscriber {
    func newState(state: ObjectState) { }
}

So far, I have the skeleton for the project, how about functionalities? Basically, I want to have these ones:

Display components based on their state.
Remove block.
Update object, it can be position, size, or other attributes.
Remove object.

In fact, there are more than this, but for the sake of brevity and simplicity, that’s enough.

Display

In the hierarchy, canvas is the highest level component and manages immediate lower level component, block. Block manages objects in turn. Therefore, to display all components, canvas and block need to traverse their child states, and add them to the view hierarchy.

class CanvasView: StoreSubscriber {
    func newState(state: CanvasState) {
        for blockState in state.blockStates where /* `blockState` isn't yet added */ {
            let blockView = BlockView()
            addSubview(blockView)
        }
    }
}

class BlockView: StoreSubscriber {
    func newState(state: BlockState) {
        for objectState in state.objectStates where /* `objectState` isn't yet added */ {
            let objectView = ObjectView()
            addSubview(objectView)
        }
    }
}

class ObjectView: StoreSubscriber {
    func newState(state: ObjectState) {
    }
}

Since newState(state:) is called every time the state changes, and I don’t want to duplicate views if they’re already added, the where condition in the loop does the job. However, the detail implementation won’t be discussed in this post. The display part is straightforward, let’s move to functions.

Functions

Having the advantage of unidirectional flow from state to view, functions can be represented by actions in ReSwift. On the other hand, if I want to have a function, I need to do the following:

Declare an appropriate action which packs information needed by the function. For example, moving a block requires the block index, so there’ll be BlockActionRemove action.

struct BlockActionRemove: Action {
    let index: Int
}

Update the reducer to handle BlockActionRemove action.
Then, whenever I want to remove a block at a particular index, a simple action dispatch call suffices.

store.dispatch(BlockActionRemove(index: index))

Display, revisit

I talked about display and functions, and so far so good, everything’s typical and goes well. However, when the number of objects increases, performance becomes an issue. Since every object subscribes to the store, even a small change in one object causes all get re-displayed. The performance, therefore, is the sum of the display costs of objects. One obvious solution for this is to re-display the only objects with changes, and this leads to diffing the state. There’re few diffing strategies I can consider.

Object level: Still loop through all object states, but only call newState(state:) with ones have been changed. This’s an out-of-box feature in ReSwift 4.
Block level: At this level, the loop is limited to only block states. Block only re-displays its changed objects based on the diff result. This’s equivalent to that subscribers now are just canvas and blocks.
Canvas level: This’s the highest possible level. The principle is identical to block level.

In my use case, the number of objects is far larger than the number of blocks, and the number of blocks is reasonable small for traversing all without overhead. Clearly, diffing at block level is the most suitable choice because it offers the balance between having more control on state delegation and utilizing ReSwift’s. I need to make some updates to accommodate this. Firstly, let’s define diff result.

enum Diff {
    case initial
    case add(indices: [Int])
    case change(indices: [Int])
    case remove(indices: [Int])
}

This diff result needs to be in block state so that when the block view displays its state, it will use the result to display objects.

class BlockView: StoreSubscriber {
    var diffResult: Diff?
    func newState(state: BlockState) {
        switch diffResult {
        case .initial: // Add all objects.
        case .add(let indices): // Add objects with index in `indices`.
        case .change(let indices): // Update objects with index in `indices`.
        case .remove(let indices): // Remove objects with index in `indices`.
        }
    }
}

diffResult will be nil if there’s no change for objects in the block. Note that objects don’t subscribe to the store anymore, but they still have the same interface as a subscriber.

class ObjectView {
    func newState(state: ObjectState) {
    }
}

The weird thing

As for functions, normally, we dispatch an action when the state delegation is settled which means every subscriber gets its new state and update corresponding to the state. What if we disrupt the state delegation, i.e., dispatch an action while the delegation’s happening? Here’s when the weird thing comes. The following diagram will describe best the problem.

Whenever there’s an object dispatching an action during state delegation, i.e., dispatch in newState(state), blocks after the block containing the object don’t update their objects. There’re factors causing this:

The diffing, it helps improve performance, but also increase the complexity when working with ReSwift. However, even if objects are displayed not based on diff result, there’s still another problem, and I’ll talk about it in the next point.
ReSwift works in a synchronous manner and has one single store. If we make store change in newState(state) which equals to calling another newState(state) inside a newState(state), eventually we’ll end up with recursive newState(state) calls or nested state delegation, and that’s another problem I just mentioned earlier. Additionally, because of one single store, regardless iteration of the state delegation, newState(state) always gets the latest state. That’s the reason why block 2 to n don’t have a chance to display State #1 and State #2 in the diagram.

In essence, I have two problems. The first one is that objects don’t get updated under discussed circumstance. The second one is nested state delegation which doesn’t affect the visual result but harms the performance.

Solution

Now I know the causes, finding solutions would be easier. Eliminating the diffing may solve the first problem, but the second problem’s still there, worse it’ll double slow down performance. Taking snapshot of the store so that each iteration of the state delegation has the correct state to display seems promising. Though it’ll break original idea, also philosophy of unidirectional data flow from ReSwift, Redux or even their ancestor, Flux, so let’s move on. I also won’t break synchronous ReSwift, and try to make it asynchronous since the problem isn’t about asynchronous so far. Ideally, what I want is whenever an action dispatched from newState(state), it should be queued in and performed after the state delegation finishes. By that way, I can keep ReSwift works synchronous and make it happy with the diffing. Surprisingly, it’s not a big deal to achieve that.

class ObjectView {
    func newState(state: ObjectState) {
        // If needed to dispatch an action.
        DispatchQueue.main.async {
            store.dispatch(Action())
        }
    }
}

The main is a serial queue and ReSwift already works on it, so it’s the perfect way to synchronize the state delegation and action dispatch in newState(state).

Alternatives

Apart from the above solution, we can use a conductor to orchestrate action dispatch in newState(state). Instead of dispatching directly to the store from object, we delegate the action to the conductor. The conductor, then, will batch actions and dispatch once to the store after all blocks get their new state.

Another option is action creator. Action creator can create either synchronous or asynchronous action, and the latter one is what we need. However, this solution comes with a caveat. Let’s examine two scenarios.

class ObjectView: StoreSubscriber {
    func newState(state: ObjectState) {
        if size == .zero {
            store.dispatch {_, _, callback in
                callback { _, _ in
                    return Action()
                }
            }
        }
    }
}

class ObjectView: StoreSubscriber {
    func newState(state: ObjectState) {
        if size == .zero {
            store.dispatch {_, _, callback in
                self.viewModel.fetch { _ in
                    callback { _, _ in
                        return Action()
                    }
                }
            }
        }
    }
}

The action in the former scenario is created outright if a certain condition is met, i.e., the action is created synchronously. In this case, to use action creator we need to know when the state delegation is done to call callback to create the action, that creates extra work. Maybe, we can call callback in DispatchQueue.main, it turns to the above simpler solution though. In contrast, the latter one fits perfectly to use action creator.

When to go from here?

The discussion on a weird use case of ReSwift is to demonstrate a practical application of ReSwift and overcome obstacles in real world usage. Though mentioned asynchronous action dispatch in newState(state), it’s just the surface of an iceberg. In the consideration of the whole project, there’re many corners to have a look on, improve and deal with, e.g., the diff algorithm, flattening the state, state changes in between of asynchronous action dispatches, etc. Moreover, this post is written limited to abilities and features of ReSwift 3, ReSwift 4 is already out there for few months though. Finally, unidirectional data flow in iOS opens new opportunities and perspectives, and in conjunction with reactive programming, architectures, they’ll create a thriving playground for writing better code.

Concurrent programming with semaphore

Sat, 17 Jun 2017 00:00:00 +0000

Writing an iOS app nowadays is pretty simple, however, a performant one requires more effort in many aspects from algorithm optimization to system related actions. The rule of thumb for most of cases is to keep heavy, time-consuming jobs away from main thread yet ensure that calls to UIKit or UI-related happen in the main thread. That helps the app be responsive and avoid sluggishness while using to bring a better experience to users.

Dispatching jobs to the corresponding thread is actually dealing with concurrent programming, a challenging topic as always. Thanks to supports from high-level programming languages, libraries, and frameworks, it becomes more friendly and less error prone to work with. Depends on the complexity of the app, different techniques are used to solve appropriate problems, and one of them is using semaphore to synchronize asynchronous jobs or orchestrate them among threads. Which will be discussed in detail in this post.

What’s semaphore?

You can see analogies of semaphore in the real world in many places. If you’ve watched a chess contest, you probably know that each player will press a common timer before their turn in a match. There’s only one chess board and only one person can make a move at a given time. Another example is checkout counters in shopping malls. Usually, there’s a limited number of counters. If any of them is free, you can just go check out right away. In most cases, however, they’re all occupied and there’ll be long queues of people waiting to check out. Those two examples have a similarity which is a limited shared resource, the chess board and counters respectively.

Now thinking of semaphore, semaphore is a mechanism to manage shared resources and guarantee access without congestion. The resource may be a concrete thing like a variable or more abstract one like a job pool. There’re two types of semaphore, binary and counting semaphore. The former can be used to implement a lock since its value is either 0 or 1 representing unlocked or locked state, while the latter allows a resource count which indicates the availability of the resource.

In Grand Central Dispatch (GCD), semaphore is an instance of DispatchSemaphore. Its API is tiny with one initializer init(value:) and two primary methods signal() and wait().

Note: Calls to signal() must be balanced with calls to wait(), otherwise an EXC_BAD_INSTRUCTION exception will be raised.

The value param in init(value:) specifies the starting value for the semaphore, we’ll talk about this later on. The principle of using semaphore is quite simple, wait() will return outright if the value of the semaphore after decrementing is greater than or equal 0, otherwise, it will await a signal. To signal, we use signal() obviously, it will increment the value, then pending wait() callers have the chance to continue execution. The following illustration helps you understand better.

Now we know how to use DispatchSemaphore, let’s apply it in some use cases.

Use case 1

In this use case, we’ll synchronize two asynchronous jobs in a concurrent queue. Besides, we also examine the value param in the initializer with the value of 0.

Context: We have one concurrent queue with two asynchronous jobs, Download Image and Download Frame, dispatched to it. We want to simultaneously download the image and the frame, then combine them in either job, Download Frame for instance.

let queue = DispatchQueue(label: "queue", attributes: .concurrent)
let semaphore = DispatchSemaphore(value: 0)

// Download Image job.
queue.async {
    Thread.sleep(forTimeInterval: 0.5)
    print("Downloaded image.")
    let signal = semaphore.signal()
    print("Signal:", signal)
}

// Download Frame job.
queue.async {
    Thread.sleep(forTimeInterval: 0.9)
    print("Downloaded frame.")
    // Await Download Image job to complete.
    semaphore.wait()
    print("Combine image and frame.")
}

// Downloaded frame.
// Downloaded image.
// Combine image and frame.
// Signal: 1

We created a semaphore with 0 as the initial value which means that for any first wait() call, it’ll hang there until there’s a signal() call. This is useful when you want to use semaphore as a lock or a synchronization flag since you don’t know or have a finite pool of resources. Back to our code above, the two Thread.sleep(forTimeInterval:) are just simulating the download process which may take an arbitrary time to complete. Even though the Download Frame job finishes first, it needs to wait for the Download Image job to be done before doing the next step. semaphore.wait() will decrement the value of the semaphore, from 0 to -1, and start waiting. In contrast, when semaphore.signal() is called, it increments the semaphore back to 0 and signals the Download Frame job to continue its execution.

An interesting thing is if we swap the Thread.sleep(forTimeInterval:) between two jobs to let the Download Image job finishes first, everything will still work well, except a small difference.

// Downloaded image.
// Signal: 0
// Downloaded frame.
// Combine image and frame.

Can you figure it out? It’s the value of signal. In the earlier scenario, the value is 1, whilst 0 in the latter. What does it mean? The order of calls of signal() and wait() doesn’t matter as long as you keep them balanced. If there’s a wait() call before signal() and there’s something waiting for a signal, signal() will return a non-zero value to indicate that. In reverse, it just returns zero so that you understand there’s no job waiting to execute, then the corresponding wait() call returns immediately.

Again illustration is the best way to explain.

Use case 2

In some cases, we want to limit the number of concurrent jobs. For example, we need to download a bunch of images but want only 2 of them at the same time. This actually can be done by using higher level API OperationQueue. Here is when we use semaphore as a resource pool.

Context: We have one concurrent queue. We dispatch many Download Image jobs to that queue and maximum 2 of them should be run simultaneously.

let queue = DispatchQueue(label: "queue", attributes: .concurrent)
let semaphore = DispatchSemaphore(value: 2)

for i in 0 ..< 10 {
    queue.async {
        semaphore.wait()
        print("Downloading image", i)
        let timeInterval: TimeInterval = 0.5 + (arc4random_uniform(2) == 0 ? 1.0 : -1.0) * 1.0 / Double(arc4random_uniform(10) + 1)
        Thread.sleep(forTimeInterval: timeInterval)
        print("Downloaded image", i)
        semaphore.signal()
    }
}

// Downloading image 0
// Downloading image 1
// Downloaded image 0
// Downloading image 2
// Downloaded image 2
// Downloading image 3
// Downloaded image 1
// Downloading image 4
// Downloaded image 4
// Downloading image 5
// Downloaded image 3
// Downloading image 6
// Downloaded image 5
// Downloading image 7
// Downloaded image 6
// Downloading image 8
// Downloaded image 7
// Downloading image 9
// Downloaded image 9
// Downloaded image 8

In this example, I randomized the timeInterval to simulate the download time. Looking at the log, you’ll see that initial only the image 0 and 1 are downloaded simultaneously. When image 0 is done, image 2 gets started, and the number of concurrent downloads still stays at 2. It keeps doing so until all images are downloaded.

Conclusion

Semaphore is a simple yet useful tool to solve concurrency problems. In conjunction with other APIs in GCD, and higher level APIs like OperationQueue, you can create solutions for more complex problems.

Bullet list on iOS with TextKit

Sun, 16 Apr 2017 00:00:00 +0000

In a recent project, I needed to display and edit bullet lists on iOS, i.e. as part of a rich text editor. After rounds of searching on Google and Stack Overflow, I could not find any satisfying answers. The most common solution is adding a bullet character right in front of each item in the list, which is good enough in most of cases, but not in mine. So what exactly are my requirements? Quite straightforward, just few things:

First, of course, display a bullet list.
When changing text alignment, bullets are still aligned nicely on the left side, regardless of the alignment which can be left, center or right.
Last but not least, the ability to edit the list, i.e. edit, add or remove list items without the hassle of handling characters manually.

With that in mind, I will go from the common solution mentioned earlier to the final one in this post.

The common solution

To be fair, this solution is simple yet efficient in simple use cases. The idea is prepending a bullet character (•) to every new item which leads to the following.

To display the above list, the string underneath would be:

• Bullet list\n• on iOS\n• with TextKit

This looks great when left aligned and easy to make, so no complaints at the moment. Let’s go ahead and change to center alignment.

And right alignment.

Wait, the bullets should vertically align each other, shouldn’t they? Nice catch, and they should keep intact on the left side as well. Because we include the bullet in the item and treat it as the item’s content, no wonder why this happens. Another problem that does not show itself visually: when we edit an item, we can actually remove the bullet character and the space between it and the text. Moreover, when we add an item, the bullet does not come for free, we need to prepend it again to the new item’s content. That being said, it is solvable by manually handling the editing action, both for adding a new item and removing an item, which does not appeal to me. There must be a better way.

So far, we have a nice way to display a bullet list on left alignment, with limitations on other alignments and tedious editing approach.

First attempt, draw bullets

Usually, we should address problems one by one, divide and conquer. However, in this situation, we can kill two birds with one stone as they boil down to one actual problem. Should we consider the bullet character as the item’s content? That is the root question for this problem. Undoubtedly, the answer would be a big no. Since we analyzed it earlier, if the bullet character is a part of an item’s content, more effort is needed to handle it properly and this process is error-prone. Better to let the system do its job unless we have a really special need. With that said, we have already eliminated one problem which is to manually handling editing, and direct all focus to the other problem.

You might think: too many words, too much explanation, where is the code, how to use TextKit?

Wait for it, here we go. For the sake of brevity, I will not introduce TextKit and its components, but will explain it with usage and only the parts used to solve the problem. However, it is worth to quote the following statement from Apple’s documentation to understand the concept of TextKit.

In Text Kit, an NSTextStorage object stores the text that is displayed by a UITextView object and laid out by an NSLayoutManager object into an area defined by NSTextContainer object. And here is the relationship between them.

What we are trying to do is drawing a bullet in each item. We have three candidates to look into: UITextView, NSLayoutManager and NSTextContainer. Among these, NSLayoutManager is the most promising one. We pass on NSTextStorage because its name implies its job is related to text storage and we do not touch the text in any way. There are a bunch of methods in NSLayoutManager, we do not know which one to use to achieve our goal. Most of them have glyph or line fragment in their name. In typography, a glyph is an elemental symbol within an agreed set of symbols, intended to represent a readable character for the purposes of writing (Wikipedia). Line fragment is the extent in which a line is drawn. To draw our bullets, we need to know where to draw it and line fragment could be a hint. We will draw it on the left side of each line fragment. Fortunately, NSLayoutManager allows us to do both of these, doing custom drawing and obtaining line fragments via.

drawGlyphs(forGlyphRange:at:)

Draws the glyphs in the given glyph range, which must lie completely within a single text container.

enumerateLineFragments(forGlyphRange:using:)

Enumerates line fragments intersecting with the given glyph range.

We will subclass NSLayoutManager to override these two methods and bring the bullets to life.

class BulletListLayoutManager: NSLayoutManager {
    let bulletSize = CGSize(width: 10, height: 10)
    let bulletColor = UIColor(red:0.14, green:0.48, blue:0.63, alpha:1.0)

    override func drawGlyphs(forGlyphRange glyphsToShow: NSRange, at origin: CGPoint) {
        super.drawGlyphs(forGlyphRange: glyphsToShow, at: origin)

        enumerateLineFragments(forGlyphRange: glyphsToShow) { (rect, usedRect, textContainer, glyphRange, _) in
            let origin = CGPoint(x: 0, y: usedRect.origin.y + (usedRect.size.height - self.bulletSize.height) / 2)

            self.bulletColor.set()
            UIBezierPath(ovalIn: CGRect(origin: origin,
                                        size: self.bulletSize)).fill()
        }
    }
}

Pretty simple, right? One thing to note here is the calculation of y of the bullet since we want it vertically aligned to the item’s content. Another thing worth mentioning is super.drawGlyphs(forGlyphRange: glyphsToShow, at: origin), make sure we do not forget to call it or nothing gets drawn at all.

Now we create NSTextView with BulletListLayoutManager instead of default NSLayoutManager.

let textStorage = NSTextStorage()
let layoutManager = BulletListLayoutManager()
textStorage.addLayoutManager(layoutManager)
let textContainer = NSTextContainer(size: .zero)
layoutManager.addTextContainer(textContainer)
let textView = UITextView(frame: CGRect(x: 0, y: 0, width: 400, height: 200),
                          textContainer: textContainer)

The relationship between these components guides us to create and assemble them to create an NSTextView with the underlying BulletListLayoutManager which again is used to draw bullets. Up to this point, we have our first result.

Indentation

We have drawn bullets and have them beautifully in place without any additional characters added to the item’s content, but we are not done yet. Look at the result above, you will probably notice that the bullets are overlapping the item’s content, not what we want. On the bright side, just a small adjustment can fix this. Did you know that we have control of the indent of the first line and other lines in a same paragraph by just using attributedText of UITextView? With this great support from TextKit, it is easy to shift the right item’s content and leave a consistent space between it and the bullet.

let style = NSMutableParagraphStyle()
let string = "Bullet list\non iOS\nwith TextKit. Bullet list on iOS with TextKit."
let attributedString = NSMutableAttributedString(string: string)
let range = NSRange(location: 0, length: attributedString.length)
style.firstLineHeadIndent = 20
style.headIndent = 20
attributedString.addAttribute(NSParagraphStyleAttributeName,
                              value: style,
                              range: range)
textView.attributedText = attributedString

Here we set the same indent for the first line and other lines onwards, and apply this style to the whole list to ensure we have all lines left aligned.

Let’s test with center and right alignment.

Wrapped item

We are almost there, just one final step. Again, look at the result we have previously, could you find anything weird? Hint: We have only three items in the list. “So where is the fourth bullet come from?”, you asked. Bingo, you got it. The thing is the last item is wrapped to two lines and due to the way we draw bullets, there is one corresponding bullet for each line. Ideally, each item should only have one bullet, regardless how many lines it contains, thus we only have to draw one bullet for the first line, a.k.a the line fragment of each item. Sounds simple but how do we determine whether or not a line is the first one or second in an item? Hint: Using the new line character. Let me recall the underlying string of the list.

Bullet list\non iOS\nwith TextKit. Bullet list on iOS with TextKit.

From the second item, its first line is the one with the new line character \n immediately before its content. Now we can update the previous code to adapt to this scenario.

class BulletListLayoutManager: NSLayoutManager {
    let bulletSize = CGSize(width: 8, height: 8)
    let bulletColor = UIColor(red:0.14, green:0.48, blue:0.63, alpha:1.0)

    override func drawGlyphs(forGlyphRange glyphsToShow: NSRange, at origin: CGPoint) {
        super.drawGlyphs(forGlyphRange: glyphsToShow, at: origin)
        guard let textStorage = self.textStorage else { return }
        enumerateLineFragments(forGlyphRange: glyphsToShow) { (rect, usedRect, textContainer, glyphRange, _) in
            let origin = CGPoint(x: 0, y: usedRect.origin.y + (usedRect.size.height - self.bulletSize.height) / 2)
            var newLineRange = NSRange(location: 0, length: 0)
            if glyphRange.location > 0 {
                newLineRange.location = glyphRange.location - 1
                newLineRange.length = 1
            }
            var isNewLine = true
            if newLineRange.length > 0 {
                isNewLine = textStorage.string.substring(with: newLineRange) == "\n"
            }
            if isNewLine {
                self.bulletColor.set()
                UIBezierPath(ovalIn: CGRect(origin: origin,
                                            size: self.bulletSize)).fill()
            }
        }
    }
}

We treat the first line fragment as a new line by default. For the rest lines, we get the character right in front of the content of that line, then check if it is \n. Here we are, our final result.

Conclusion

I have walked you through the whole process, from thinking, making decision to implementation that was exactly in my mind while I was doing it. This is, however, just the beginning, there are still lots of room for you explore TextKit, tweak it and make it your own solution to your problem. I can name some remaining things to improve and leave them as exercises for you.

Change bullets size according to font size.
When we change line height, content does not align to the bullet anymore, we need a fix for this.
Instead of black dot bullets, can we make other types of bullet?

Behind the scene

I obscured some of the code to keep the post focused on what matters. However, it is a two-bladed knife, while it is short, it may perplex you, so it is better to uncover everything. There are two things I did not mention throughout the post. The first one is the text view and the style have been preconfigured as below to simplify the implementation of BulletListLayoutManager.

textView.textContainerInset = .zero
textView.textContainer.lineFragmentPadding = 0
textView.layoutManager.usesFontLeading = false
style.minimumLineHeight = fontSize
style.maximumLineHeight = fontSize

And if you notice, string.substring() only accepts Range<String.Index> as parameter, not NSRange. I created an extension of String with NSRange support so that the method works seamlessly with NSRange.

extension String {

    func substring(with range: NSRange) -> String {
        let startIndex = index(self.startIndex, offsetBy: range.location)
        let endIndex = index(startIndex, offsetBy: range.length)
        return substring(with: startIndex ..< endIndex)
    }
}

References

I recommend you to go through the following references, they are great resources, talks and libraries that helped me a lot to realize this idea.

Bump version with PlistBuddy

Sun, 26 Feb 2017 00:00:00 +0000

Either you are an iOS, macOS developer or developing something in Apple ecosystem, you must be familiar with one file called Info.plist. At some point in development, for sure you want to release a new version of your app and increase that version number. With the recent find of the existence of PlistBuddy, it would be interesting to give it a try and also a small exercise for my shell scripting skill. As so this post will be about to create a simple shell script to bump version with help PlistBuddy. Let’s kick started.

What’s plist?

In short, plist is filename extension of property list files. Usually, these files are used to store settings, they may be either user’s settings or all kinds of settings you need. In iOS, Info.plist stores some information like bundle identifier, version, supported orientation and more.

In a nutshell, plist file is a XML file, on the other hand, it is stored in XML format with a specific document type definition (DTD) defined by Apple. As described in http://www.apple.com/DTDs/PropertyList-1.0.dtd,

<!ENTITY % plistObject "(array | data | date | dict | real | integer | string | true | false )" >
<!ELEMENT plist %plistObject;>
<!ATTLIST plist version CDATA "1.0" >

<!-- Collections -->
<!ELEMENT array (%plistObject;)*>
<!ELEMENT dict (key, %plistObject;)*>
<!ELEMENT key (#PCDATA)>

<!--- Primitive types -->
<!ELEMENT string (#PCDATA)>
<!ELEMENT data (#PCDATA)> <!-- Contents interpreted as Base-64 encoded -->
<!ELEMENT date (#PCDATA)> <!-- Contents should conform to a subset of ISO 8601 (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'.  Smaller units may be omitted with a loss of precision) -->

<!-- Numerical primitives -->
<!ELEMENT true EMPTY>  <!-- Boolean constant true -->
<!ELEMENT false EMPTY> <!-- Boolean constant false -->
<!ELEMENT real (#PCDATA)> <!-- Contents should represent a floating point number matching ("+" | "-")? d+ ("."d*)? ("E" ("+" | "-") d+)? where d is a digit 0-9.  -->
<!ELEMENT integer (#PCDATA)> <!-- Contents should represent a (possibly signed) integer number in base 10 -->

plist defines 10 elements, they are plist, array, data, date, dict, real, integer, string, true and false, corresponding to 9 supported data types. The plist, in fact, is a special one, used as the root element of a document, and follow by plist, it must be one of the rest elements. In case of Info.plist, we often see it is followed by a dict, for example.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
</dict>

The dict receives pairs of key of other elements as its children and we can interpret it as key and value. Obviously, we can have multiple nested dict elements, just need to follow its definition <!ELEMENT dict (key, %plistObject;)*>.

The array is another one that needs to take note. Unlike dict, array does not require key, it allows any other elements, include itself but except plist to be its children instead. It can be nested as well as dict.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>UISupportedInterfaceOrientations</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
</dict>

In the combination of 9 elements and nested ability of dict and array, we can create complex data structures to persist almost necessary settings and information.

What’s PlistBuddy?

PlistBuddy is a command line tool to manipulate plist file. It can be run in interactive mode or execute and exit mode. In interactive mode, we can write commands and their parameters, then save our work with Save command. Likewise, in execute and exit mode, we stringifies commands and parameters, and pass these strings as values of option -c. For example, we want to read the version in Info.plist, the complete command will look like this.

/usr/libexec/PlistBuddy -c 'Print CFBundleShortVersionString' Info.plist

Note: PlistBuddy is not in the path like /usr/bin, therefore we need to use the full path or we need to add /usr/libexec/ to the environment variable PATH.

Bump version

Bump version is action to update the version of an app, a library or anything having a version tagged to it, to a higher number. If you are using semver, the version number will consist of 3 components: major, minor and patch, in the format of <major>.<minor>.<patch>.

We do bump version quite frequently so it is a good idea to automate this action instead of manually changing it, through Xcode for example.

You might be thinking of using Fastlane to do this. Yeah, it is a great tool for automation and if you haven’t heard or used it, I highly recommend to give it a try, it is worth and would save you plenty of time. agvtool is an another alternative to do this. Version-related actions in Fastlane, like increment_version_number, get_version_number, boil down to use avgtool themselves.

However, for the sake of shell script exercise, I will walk you through everything from ground, of course, with the use of PlistBuddy I have just introduced above.

The idea is pretty simple, we will go step by step as below:

Read the current version from Info.plist.
Extract the version component.
Increase the version.
Write the new version to Info.plist.

Read the current version

Actually, this step is already revealed so here I just recall and modify it a bit to store the result in a variable.

version=$(/usr/libexec/PlistBuddy -c 'Print CFBundleShortVersionString' Info.plist)

Now we have the current version stored in version.

Extract the version component

Next step is to separate the version to components and increase them according to our need.

As mentioned earlier, we have 3 components: major, minor and patch. Except for patch, change of major or minor will reset its subsidiary component(s) to zero. For instance, we have 1.0.5 and we want to increase the minor so the result will be 1.1.0, the patch is reset to zero.

To break out the version, we can simply use read and change the internal field separator (IFS) to dot character ..

IFS="." read major minor patch <<< "$version"

_Note: An alternative is to replace . by space character ` , doing so, we do not need to change IFS`.

With the major, minor and patch in hand, we proceed to the next step.

Increase the version

To increase the version, firstly, we need to know which component to increase, it may be either major, minor or patch. We use an argument to determine this by introducing three ones: major, minor and patch to change the major, minor and patch respectively.

component=$1
if [[ "$component" = 'major' ]]; then
    // Increase major
    // Reset minor and patch
elif [[ "$component" = 'minor' ]]; then
    // Increase minor
    // Reset patch
elif [[ "$component" = 'patch' ]]; then
    // Increase patch
fi

That is the boilerplate for checking the argument, and if the argument is other than major, minor or patch, we do nothing.

The rest of work in this step is just doing simple mathematics.

if [[ "$component" = 'major' ]]; then
    major=$((major + 1))
    minor=0
    patch=0
elif [[ "$component" = 'minor' ]]; then
    minor=$((minor + 1))
    patch=0
elif [[ "$component" = 'patch' ]]; then
    patch=$((patch + 1))
fi

Now, compose the major, minor and patch to create the new version.

version="${major}.${minor}.${patch}"

Write the new version

We are almost there. The final step is to write back the new version to Info.plist.

/usr/libexec/PlistBuddy -c "Set CFBundleShortVersionString ${version}" NVActivityIndicatorView/Info.plist

Sum up

Assemble everything, we have the complete shell script to bump version according which component we pass in. The gist of this complete script is also available here.

#!/bin/bash

component=$1

version=$(/usr/libexec/PlistBuddy -c 'Print CFBundleShortVersionString' Info.plist)
IFS="." read major minor patch <<< "$version"

echo "$version"

if [[ "$component" = 'major' ]]; then
    major=$((major + 1))
    minor=0
    patch=0
elif [[ "$component" = 'minor' ]]; then
    minor=$((minor + 1))
    patch=0
elif [[ "$component" = 'patch' ]]; then
    patch=$((patch + 1))
fi

version="${major}.${minor}.${patch}"

echo "$version"

/usr/libexec/PlistBuddy -c "Set CFBundleShortVersionString ${version}" Info.plist

You can add things like to create a new commit after bump version, tag the commit with the new version, it is totally open to your requirements.

Bump version is just one simple example what we can do with PlistBuddy. Now we can add PlistBuddy to our toolbelt and use it anytime we need to manipulate a plist file.

Reference

I recommend to read Xcode - xcworkspace and xcodeproj to understand the structure of xcworkspace and xcodeproj, it is especially helpful when you need to do complex tasks. In the article, you can find other resources to dig deeper as you want.

Should I use struct in Swift?

Fri, 28 Oct 2016 00:00:00 +0000

“Should I use struct or class?” is a common question of Swift developer. There may be something you also hear over and over again like: struct is value-semantic, struct is faster. Is it really as it being said or is there anything hidden behind? Let’s find out!

Value-semantic

It is obvious to say that struct is a value type. That means you don’t need to worry about unintended changes of value when passing around variables. For example:

struct Backpack {
    var numberOfCompartments: Int
}

let myBackpack = Backpack(numberOfCompartments: 4)
var yourBackpack = myBackpack
assert(myBackpack.numberOfCompartments == 4)
yourBackpack.numberOfCompartments = 3
assert(myBackpack.numberOfCompartments == 4)
assert(yourBackpack.numberOfCompartments == 3)

Why will this help? Well, passing objects around is very common and so is mutating objects. Speaking of immutability and mutability, it is another discussion and I won’t cover it in this post. Changes on other instances in the result of changes on one is good sometimes as that may be what you want. However, more often, it is not your intention and it causes much more hassle than help. By assuring these accidental changes not happen, you are free of worry and save time for development.

Even with reference type data inside struct, it will behave the same.

class Compartment { 
  var object: AnyObject?
}

struct Backpack {
    var compartment: Compartment
}

let myBackpack = Backpack(compartment: Compartment())
var yourBackpack = myBackpack
yourBackpack.compartment == Compartment()
assert(myBackpack.compartment !== yourBackpack.compartment)

If we change from struct to class, after changing compartment property, myBackpack.compartment and yourBackpack.compartment both still point to the same instance.

class Backpack {
    var compartment: Compartment
    // Assume that we already have proper initializer
}

let myBackpack = Backpack(compartment: Compartment())
var yourBackpack = myBackpack
yourBackpack.compartment == Compartment()
assert(myBackpack.compartment === yourBackpack.compartment)

Copy-on-write

However, one question comes up with reference type data in struct, do changes on a property of yourBackpack.compartment cause changes on myBackpack.compartment? Yes, it does, for short answer. It is easy to understand because as mentioned above, yourBackpack.compartment and myBackpack.compartment are referencing to the same instance. But wait, it violates value-semantic, doesn’t it? It does surely. Luckily, there is a solution for this, or just call as a workaround.

The idea is that for any change on a property of reference type data, make a copy of it first then do the change. For reading, it is not needed to do anything. If doing so, other issue raises, that is every time you change reference type data, a new copy of it will be created, this is overhead and should be avoided. Swift standard library provides a function called isKnownUniquelyReferenced(_:) to check whether the given object is a class instance known to have a single strong reference. By using this, you can get rid of creating redundancy.

extension Compartment: NSCopying {
    public func copy(with zone: NSZone? = nil) -> Any {
        return Compartment() // Just for demo purpose
    }
}

struct Backpack {
    private var _compartment: Compartment
    var identity: Int
    var compartmentForReading: Compartment { return _compartment }
    var compartmentForWriting: Compartment {
        mutating get {
            if !isKnownUniquelyReferenced(&_compartment) {
                _compartment = _compartment.copy() as! Compartment
                print("copying", _compartment)
            }
            return _compartment
        }
        mutating set {
            _compartment = newValue
        }
    }
    
    init(compartment: Compartment, identity: Int) {
        self._compartment = compartment
        self.identity = identity
    }
}

let myBackpack = Backpack(compartment: Compartment(), identity: 10)
var yourBackpack = myBackpack
assert(myBackpack.compartmentForReading === yourBackpack.compartmentForReading)
(yourBackpack.compartmentForWriting).object = banana
yourBackpack.identity = 20
assert(myBackpack.compartmentForReading !== yourBackpack.compartmentForReading)
assert(myBackpack.compartmentForReading.object != yourBackpack.compartmentForReading.object)

The indirect storage called _compartment is used to actually store reference type data, other two computed properties compartmentForReading and compartmentForWriting are for reading and writing purpose respectively. compartmentForReading simply returns the indirect storage. On the other hand, compartmentForWriting’s job is more complex. On getting, it checks if _compartment is uniquely referenced, otherwise, it creates a new copy of the indirect storage then assign back to itself. On setting, straightforwardly, it sets a new value to the indirect storage. The consequence of this is we have separate instances and prevent unintended changes.

Note: You may ask why (yourBackpack.compartmentForWriting).object instead of yourBackpack.compartmentForWriting.object? Using the later invokes getter twice and I still don’t understand this behavior in Swift, will update if finding anything. This happened because I ran it on playground. I also asked on StackOverflow and found a reasonable explanation for this.

Caution: This code doesn’t work as I expected. In fact, isKnownUniquelyReferenced(&_compartment) always returns false, that results in copying every time there is a change on _compartment’s property and it is inefficient. Same as above, will update if finding anything.

Faster

There are two factors, also myths, that impacts the performance of struct, they are memory allocation and reference counting. Let’s talk about memory allocation first.

Memory allocation

Because struct is a value type, it is stored in stack. Storing in stack is fast as stack is simple data structure with only one end to push and pop data to and from. To keep track of these actions, only one pointer is needed and it is incremented or decremented according to the action.

On the contrary, storing in heap requires more effort. At first, it needs to look up for sufficient space in memory, then stores data in there. However, the whole process is not that simple, to deal with multiple access, it also needs to do lock mechanism to make it thread-safe. As a result, storing in heap is more expensive than in stack.

Hmm, it seems to be true, especially when struct contains all value type data. In real world, things are more complicated and you want not only value type data but also reference type. How does struct handle this? Look at this example.

class Weapon { }

struct Unicorn {
    let weapon: Weapon
    let numberOfHorns: Int
}

numberOfHorns is stored in stack and it is fast. However, as weapon is reference-type, only its pointer is stored in stack but its actual data is stored in heap and it is not as fast as numberOfHorns. Therefore, struct is not really as fast as it looks at the first glare in memory allocation manner. Okay, one myth is demystified, let’s move onto the next one.

Reference counting

Working with heap requires more effort and consciousness in comparison with stack. You need to manually deallocate everything after use if memory leak is not your friend, unless there is a garbage collector or other mechanism lifting it for you under the hood. Fortunately, you don’t have to do it yourself in iOS, macOS development, the OS is smart enough to detect unused chunk of data in memory and deallocate it and the OS does that by counting references to an instance. Every time a new reference created, the reference count of corresponding instance increments, the similar thing happens on removing a reference, the count decrements. When the count is zero, the OS knows this instance is not used anymore, then deallocates it from heap and save memory for later use. No wonder, this whole process is costly.

Taking advantage of not using reference counting, pure value type struct, i.e. struct has only value type data, has better performance than class. It won’t be true anymore in case of reference type struct, i.e. struct has reference type data.

Let’s add few more to the above example.

class Shield { }

struct Unicorn {
    let weapon: Weapon
    let shield: Shield
    let numberOfHorns: Int
}

let tom = Unicorn(weapon: Weapon(), shield: Shield(), numberOfHorns: 1)

There are two reference counts in the example above, one of weapon instance and one of shield instance, each is set to 1. Now we will create a new variable jerry, then assign tom to this new one.

let jerry = tom

The number of references here is 4. What? Because there are 2 references to each of weapon and shield instance, the reference count of each is set to 2. Better understand by looking at the following illustration.

            stack

   tom +----------------+
       | weapon         +------+
       +----------------+      |       heap
       | shield         +---+  |
       +----------------+   |  |  +-------------+
       | numberOfHorns  |   |  +--+ weapon      +--+
       +----------------+   |     +-------------+  |
                            +-----+ shield      +-----+
 jerry +----------------+         +-------------+  |  |
       | weapon         +--------------------------+  |
       +----------------+                             |
       | shield         +-----------------------------+
       +----------------+
       | numberOfHorns  |
       +----------------+

You may notice something turning not good. Let’s examine the same use case with class.

class Unicorn {
    let weapon: Weapon
    let shield: Shield
    let numberOfHorns: Int
    // Assume that we already have proper initializer
}

let tom = Unicorn(weapon: Weapon(), shield: Shield(), numberOfHorns: 1)
let jerry = tom

Now see the graph.

     stack                    heap

+-------------+          +----------------+
| tom         +----------+ weapon         |
+-------------+          +----------------+
| jerry       +----------+ shield         |
+-------------+          +----------------+
                         | numberOfHorns  |
                         +----------------+

There are only 2 references and clearly, class outperforms in this scenario. Myth number 2, solved!

With new things introduced in Foundation framework, using proper data type will help avoid these problems whilst taking advantage of struct.

Conclusion

At the first glare, we all seem to be dazzled by struct. Only after having a closer look, we discover many things hidden behind, these don’t discourage us from using struct but give us better understanding and help make better decision. Ultimately, there is no silver bullet at all, everything is devised with purpose and should be used with awareness.

It’s not the fault of the tool, it’s he doesn’t learn it more.

Reference

Understanding UIView’s transform property (final)

Sat, 27 Aug 2016 00:00:00 +0000

In previous part, we talked about 4 properties of UIView and relationships between them. This part we cover operations with transform and how to persist UIView information. Let’s go!

`transform` operations

transform is type of CGAffineTransform and it represents a matrix used for affine transformation. Speaking of the matrix and and affine transformation, it is beyond context of this article, but if you wonder and want to learn more, this wiki would be a good start.

In brief, transform includes 6 matter values a, b, c, d, x and y as the figure below.

a and d are for scale, x and y are for translation and a, b, c and d are for rotation. However, usually, we use only scale and rotation of transform as for translation, we can simply use center property to position a view in its superview.

When transform is used for only one transformation, it is straightforward to extract that information, e.g. factor of scale or angle of rotation. In most of cases, however, we use combination of scale and rotation, that makes transformation extraction more tangled. Thanks to mathematics, we already have equations for this and only need to convert to code.

Extract

Right below is snippet for scale extraction

func scaleOf(transform: CGAffineTransform) -> CGPoint {
    let xScale = sqrt(transform.a * transform.a + transform.c * transform.c)
    let yScale = sqrt(transform.b * transform.b + transform.d * transform.d)
    
    return CGPoint(x: xScale, y: yScale)
}

and for rotation.

func rotationOf(transform: CGAffineTransform) -> CGFloat {
    return CGFloat(atan2(transform.b, transform.a))
}

Restore

In reverse, CoreGraphics provides handy functions to create CGAffineTransform from transformation information.

view.transform = CGAffineTransformMakeRotation(angle_in_radian) // Create CGAffineTransform of rotation transformation 

view.transform = CGAffineTransformMakeScale(xScale, yScale) // Create CGAffineTransform of scale transformation

Because order of transformation matters, in case of combination of scale and rotation, we should persist the whole transform, i.e., a, b, c, d, x and y values, and use it to restore itself.

view.transform = CGAffineTransform(a: a, b: b, c: c, d: d, tx: x, ty: y);

Persistence

When comes with UIView information persistence, especially with transform is applied, note following things:

frame is invalid so we shouldn’t use it to position or measure view.
Though frame is invalid, there is way to calculate actual values and use them for positioning or sizing of view.
center is recommended to position view.
bounds.size is recommended to measure view.

So what information we need to persist? They are position in superview, size and transformation. With transformation, we can persist transform as a whole or individual one.

Position

The best way is to persist center, as center is independent of transform, it is safe to position view regardless of transform.

let persistedCenter = view.center

However, in some scenarios, frame.origin may be useful, then we need calculation on restoration to convert frame.origin back to center. It will be there later.

let persistedPosition = frame.origin

Size

Both bounds.size and frame.size cannot be used for size persistence, because they do not reflect correct view’s size. bounds.size is original value before transformation. And frame.size is size of boundary view, not actual view.

So how? The answer is to use bounds.size and scale transformation and it is pretty simple.

let scale = scaleOf(view.transform)
let persistedSize = CGSize(width: view.bounds.size.width * scale.x, height: view.bounds.size.height * scale.y)

If we count actual view’s size in persistence, transform we persist should contain only rotation transformation. This is due of restore phrase later. Otherwise, restoration will get unnecessary calculation, now or later is of your choice. Then I choose now and it also makes more sense to persist real view’s size than its original one.

Transformation

How to persist position and size affects how to do with transformation, actually, only size does. As stated right above, if we persist actual view’s size, rotation is the only thing we need for transformation.

let persistedRotation = rotationOf(view.transform)

How about original view’s size? So we have to persist the whole transform by using its values.

let a = view.transform.a
let b = view.transform.b
let c = view.transform.c
let d = view.transform.d

With these values, it is easy to restore transform as talked above.

Restore

Make assumption that we are persisting actual view’s size, its rotation and center, now it is time to restore the view from that.

let view = UIView(frame: CGRect(x: 0, y: 0, width: persistedSize.width, height: persistedSize.height))
view.transform = CGAffineTransformMakeRotation(persistedRotation)
view.center = persistedCenter

How about frame.origin for position? Here we are.

let view = UIView(frame: CGRect(x: 0, y: 0, width: persistedSize.width, height: persistedSize.height))
view.transform = CGAffineTransformMakeRotation(persistedRotation)
view.center = CGPoint(x: persistedPosition.x + view.frame.size.width / 2, y: persistedPosition.y + view.frame.size.height / 2)

Conclusion

There are still many more to talk about UIView, however, with this article, transform property is not scary anymore, huh? From here, we can keep learning layer.anchorPoint which is also relevant to transform, animation with transform and other 3 properties, etc. Happy learning!

Understanding UIView’s transform property (part 1)

Tue, 23 Aug 2016 00:00:00 +0000

Working with transform property of UIView might be frustrated at the first time. Confusion of using transform leads to difficulty in controlling UIView as well as persisting UIView information. This article helps demystify this.

Basics

Before going clarify transform property and how it works, let’s remind some basics. With a bunch of properties and methods in UIView, there are only four that we need in context of this article and the rest of it focuses only these four properties to try to explain how transform works.

frame: The frame rectangle, which describes the view’s location and size in its superview’s coordinate system.
bounds: The bounds rectangle, which describes the view’s location and size in its own coordinate system.
center: The center of the frame, i.e., it is location of the view’s center point in its superview’s coordinate system.
transform: Specifies the transform applied to the receiver, relative to the center of its bounds.

WARNING If this property is not the identity transform, the value of the frame property is undefined and therefore should be ignored.

These four properties have binding of each other, changes on one cause changes mostly on others. Simplest, for example, changes on center modify frame, and vise versa. We talk more about these relationships right below.

Relationships

`frame` changes

When frame changes, obviously, it causes change of bounds and center but remains transform. Changes on frame.origin and frame.size result in changes on center and bounds.size respectively.

frame.origin changes center frame.size changes bounds.size

`bounds` changes

As bounds.size changes, the whole frame changes, I mean both frame.origin and frame.size. The reason is this change is relative to the view’s center point, the center point keeps the same while 4 corners move inward or outward depending on decreasing or increasing the size. System now reflects these changes to the view’s superview’s coordinate by change the view’s frame.

bounds.size changes frame.origin and frame.size

frame.size is always equal to bounds.size on the other hand.

How about bounds.origin? It does not affect frame at all. It just shifts the view’s content, like the way you see in UIScrollView.

`center` changes

Because center and frame are both determined in superview ‘s coordinate system, i.e., they are in the same coordinate system, no wonder that they affect each other.

center changes frame.origin

`transform` changes

Now here is the most confusing of 4 properties. Don’t panic. It is purely mathematics. What, mathematics? It is even more scary. No, even if you are not math genius, understanding it must not be hard.

The idea is that transform is, simplified-explanation, a calculation being applied to a view to convert every single point inside the view to new position in the same coordinate system of the view’s superview. Keeping superview’s coordinate system untouched helps diminish effort to work with other views that do not use transform, i.e., transform is identity.

transform: input [some calculations happen here]=> output

As superview needs a straight rectangle to determine position and size of its child view, in case child view does not have one, e.g. it is rotated, superview uses a boundary to do this job. The boundary is the smallest straight rectangle that encloses completely the view.

Scale

Now let’s scale up and down a view. Recall the earlier explanation of transform, when scaling a view, in fact transform does not change real view’s size but only do conversion the size to new size in view’s superview and display it. This conversion, easy to guess, has effect on view’s frame.

transform changes frame

What if we change frame after applied scale? Good question. Remember frame.size is always equal to bounds.size said earlier? New frame.size comes from old frame.size, actually comes from bounds.size. On forward way, bounds.size is as input and new frame.size is as output. And frame.size is as input and bounds.size is as output in reverse.

It is supposed to be but it is not unfortunately. As warning in transform, frame should be ignored. In fact, we still can use it to new frame value after scaled, as well as frame of boundary being mentioned right below, but it is not recommended to set value, even with frame.origin.

Therefore the answer is shouldn’t do.

Rotation

Now it is time for rotation. As in earlier figure, when a view is rotated, it does not longer have a straight rectangle to represent in its superview. This comes to superview needs a boundary to position and measure the view. The view’s frame now is actually the boundary’s frame and it does not literally reflect view’s position and size anymore.

transform changes frame

Combination

In combination of scale and rotation, the same principle is applied.

In this part, we have better idea of 4 properties and their relationship. In the next one, we will talk more about transform, how to use it and applications, especially on persistence.

Vinh Nguyen's Blog

How to ignore/hide changes from Git

Basics

Untracked files

Tracked files

Summary

The Essentials of Essential Front-end Tools, ESLint

What is ESLint and Why?

How does ESLint work?

Parser

Rules

Result

Integration

Configuration

Parser

Environment

Plugins and Shareable Configs

Prettier

Conclusion

ReSwift, a weird use case

ReSwift, a weird use case

ReSwift in brief

The use case, first introduction

Display

Functions

Display, revisit

The weird thing

Solution

Alternatives

When to go from here?

Concurrent programming with semaphore

What’s semaphore?

Use case 1

Use case 2

Conclusion

Bullet list on iOS with TextKit

The common solution

First attempt, draw bullets

Indentation

Wrapped item

Conclusion

Behind the scene

References

Bump version with PlistBuddy

What’s plist?

What’s PlistBuddy?

Bump version

Read the current version

Extract the version component

Increase the version

Write the new version

Sum up

Reference

Should I use struct in Swift?

Value-semantic

Copy-on-write

Faster

Memory allocation

Reference counting

Conclusion

Reference

Understanding UIView’s transform property (final)

transform operations

Extract

Restore

Persistence

Position

Size

Transformation

Restore

Conclusion

Understanding UIView’s transform property (part 1)

Basics

Relationships

frame changes

bounds changes

center changes

transform changes

Scale

Rotation

`transform` operations

`frame` changes

`bounds` changes

`center` changes

`transform` changes