# Smooth (Bitwise) Operator

One of the wonderful(?) things about Objective-C is that it’s based on C. Part of the power of C is bit-bashing, where you can manipulate individual bits inside of a piece of memory. Have a bunch of boolean values but don’t feel like wasting a byte or two for each one? Represent them as individual bits! Luckily we tend not have to do this a lot of these days given the massive amounts of memory that we have to play with, even on iOS devices. That being said, there are times where bitwise operations appear in the Cocoa APIs, so it’s good to be comfortable with a couple of basic operations.

**TL;DR:**

- Combine bit flags with bitwise-OR, with a single pipe:

`NSRegularExpressionCaseInsensitive | NSRegularExpressionUseUnixLineSeparators`

- Test bit flags with bitwise-AND, with a single ampersand:

`if (regexflags & NSRegularExpressionCaseInsensitive) { ...`

- Clear flags with bitwise-ANDing the complement, using the twiddle ~:

`regexflags = regexflags & ~NSRegularExpressionUseUnixLineSeparators`

### The tools

There are four basic tools in our bit twiddling arsenal

- shifting
- ORing
- ANDing
- NOTing

Shifting lets you slide bits to the left and to the right. This lets you position bits exactly where you want. The `<<`

and `>>`

operators are used to shift bits. We’ll only be looking at `<<`

, the left-shift operator because it’s useful for indicating which particular bit is interesting.

Say you had a bit pattern like this:

`00101010`

. This is hex `0x2A`

, or decimal `42`

.

An expression like

0x2A << 2

Means to take the bits of `0x2A`

and scoot them to the left by two spots, fill in the bottom parts with zeros, and drop the top bits on the floor. The resulting pattern will be:

`10101000`

, which is hex `0xA8`

, or decimal `168`

ORing lets you combine two bit patterns together to form a third pattern.

In a bit pattern, a bit is said to be “set” if it has a value of 1, and “clear if it has a value of zero. With a bitwise OR, resulting pattern has bets set to 1 if **either** of the original patterns have a 1 bit, otherwise the bit is zero if **both** of the original patterns have a zero bit.

Hex `0x2A`

‘s pattern is: `00101010`

, and the pattern `11010010`

is hex `0xD2`

, the resulting bit pattern if they’re OR-d together will be `11111010`

, which is hex `0xFA`

, or decimal `250`

.

The syntax is the single pipe between integers: So, `0x2A | 0xD2 == 0xFA`

OR is a very encompassing, friendly, gregarious operator. It’ll accept one-bits from anywhere. Got two bits set in the same position? No problem, it’s still set in the result.

AND is like OR’s grumpy brother. AND is very discriminating about what bits it lets through. Given two bit patterns, a bit is set in the resulting pattern _only_if_ the bit exists in **both** of the original two patterns.

The syntax is a single ampersand between two integers. Recall `0x2A`

is `00101010`

and `0xD2`

is `11010010`

, the result of `0x2A & 0xD2 `

will be `00000010`

, which is hex `0x02`

, or decimal 2. Notice that only one bit survived the journey:

NOT is the contrarian. Give NOT a single bit pattern, and you’ll get back its inverse. What was set is now clear, and what was clear is now set. (A bitwise koan?)

The bitwise-NOT syntax is a tilde/twiddle before a value: `~0x2A`

says to flip the bits of `0x2A`

(`00101010`

) with a resulting value of `11010101`

, which is hex `0xD5`

:

With these four tools, you can address any particular bit in a chunk of memory, test its value (is it set or not?) and change its value (clear this here bit, or set that there other bit).

### Optional Equipment

Option flags is the main place you’ll see exposed bits in Cocoa. These flags let you pack a lot of parameters into a small piece of memory, without needing to create method calls that take a lot of parameters, or supply a supplemental data structure such as a dictionary.

Consider this declaration from `NSRegularExpression`

:

typedef NS_OPTIONS(NSUInteger, NSRegularExpressionOptions) { NSRegularExpressionCaseInsensitive = 1 << 0, NSRegularExpressionAllowCommentsAndWhitespace = 1 << 1, NSRegularExpressionIgnoreMetacharacters = 1 << 2, NSRegularExpressionDotMatchesLineSeparators = 1 << 3, NSRegularExpressionAnchorsMatchLines = 1 << 4, NSRegularExpressionUseUnixLineSeparators = 1 << 5, NSRegularExpressionUseUnicodeWordBoundaries = 1 << 6 };

(OBTW, what is that `NS_OPTIONS`

in the declaration? It just expands into an enum at compile time. Xcode, though, can look at `NS_OPTIONS`

declarations and know that bit flags are involved, and kick in some extra type checking. Check out NSHipster for more details.)

This `enum`

is composed of a bunch of bit flags. Recall the `<<`

operator, “left shift” takes a starting value and then moves all the bits to the left, filling in the bottom bits with zeros. With an expression like

1 << 0

The value of “1″ (which is a single bit set):

00000001

Gets moved over zero positions, leaving the value unchanged:

00000001

`1 << 1`

says to take the single-bit number one:

00000001

and then move it over by one position, filling in zeros in the bottom position:

00000010

So, `1 << 1`

is another way to say “2″. Or hexadecimal `0x02`

Now `1 << 5`

. This means, take the number one:

00000001

and move it left five positions:

00100000

This value is 32 (decimal),or `0x20`

(hex)

Here is that table of flags, along with their binary and hex representation:

typedef NS_OPTIONS(NSUInteger, NSRegularExpressionOptions) { NSRegularExpressionCaseInsensitive = 1 << 0, 00000001 0x01 NSRegularExpressionAllowCommentsAndWhitespace = 1 << 1, 00000010 0x02 NSRegularExpressionIgnoreMetacharacters = 1 << 2, 00000100 0x04 NSRegularExpressionDotMatchesLineSeparators = 1 << 3, 00001000 0x08 NSRegularExpressionAnchorsMatchLines = 1 << 4, 00010000 0x10 NSRegularExpressionUseUnixLineSeparators = 1 << 5, 00100000 0x20 NSRegularExpressionUseUnicodeWordBoundaries = 1 << 6 01000000 0x40 };

You can see there is an individual bit position for each of these different possible behaviors. By constructing a pattern of bits you can exert a lot of control over your regular expression. Do this stuff long enough, and you can recognize bit patterns just from the hexadecimal values.

These constants are known as “bit masks”. They’re values that have bits set in particularly interesting positions. We can take an individual bit mask, like `NSRegularExpressionCaseInsensitive`

and use it to twiddle that individual bit in some piece of memory, such as a method parameter.

### Using the Options

Great. We have a pile of constants now describe bit positions. What next? You use these bit masks when you create a new regular expression object with `+regularExpressionWithPattern:`

+ (NSRegularExpression *) regularExpressionWithPattern: (NSString *) pattern options: (NSRegularExpressionOptions) options error:(NSError **)error;

You supply the regex pattern string in the first argument, then pick the options that govern the regular expression’s behavior and combine them together. Say you wanted to match things without caring about case. You’d use `NSRegularExpressionCaseInsensitive`

. Pretend that you’re also dealing with a specially formatted text file such that `\n`

characters count as line breaks but not `\r`

. You might have `\r`

characters embedded in strings in a CSV and you’d want to ignore those if you’re processing the file on a line-by-line basis. The flag of interest is `NSRegularExpressionUseUnixLineSeparators`

.

How do you use them? You combine the bit masks together. Bitwise-OR is the tool for combining – remember that OR is friendly and all-encompassing. We’ll get a bit mask with those two bits set by providing these two masks (CaseInsensitive and UnixLineSeparators) in an OR expression:

NSRegularExpression *regex = [NSRegularExpression regularExpressionWithPattern: ... options: NSRegularExpressionCaseInsensitive | NSRegularExpressionUseUnixLineSeparators error:...];

Here’s that expression again:

NSRegularExpressionCaseInsensitive | NSRegularExpressionUseUnixLineSeparators

The preprocessor replaces the human-readable names with their values:

1 << 0 | 1 << 5

And then the compiler precalculates the values, because they’re constants:

00000001 | 00100000

Thanks to C’s operator precedence rules, you don’t need any parentheses in that expression.

Here is the final binary bit mask:

00100001

Which is hex `0x21`

`+regularExpressionWithPattern`

can now look at `0x21`

‘s bit pattern and figure out how you want it to behave.

A common error is to add these flags together rather than bitwise-ORing them. You’ll get the correct value in many cases. `NSRegularExpressionCaseInsensitive + NSRegularExpressionUseUnixLineSeparators`

will also give you the value `0x21`

, but that’s a bad habit to get into because it can lead to subtle bugs. Consider this sequence of operations using NSRegularExpressionCaseInsensitive, which has the value of “1″

NSUInteger bitmask = 0x00; bitmask = bitmask | NSRegularExpressionCaseInsensitive; bitmask = bitmask | NSRegularExpressionCaseInsensitive;

The resulting value is going to be `0x01`

, with a single set bit on the bottom. Setting a bit that’s already set is a no-op.

But, if you use addition:

NSUInteger bit mask = 0x00; bitmask = bitmask + NSRegularExpressionCaseInsensitive; bitmask = bitmask + NSRegularExpressionCaseInsensitive;

The value of `bitmask`

is now `0x02`

, which is `NSRegularExpressionAllowCommentsAndWhitespace`

, and probably not what you want.

This isn’t a big deal when you’re just hard-coding a set of flags in a method call. But it can really bite you if you end up passing a bit mask around and are wanting to set your own bits in it.

### Testing, Testing, 1-2-3

Setting flags is pretty easy. And for the most part, that’s all you have to deal with as Cocoa programmers – assemble the flags for the options you want and pass it into some method. But what if you want to write your own method that can interpret one of these packed-flags values? Similarly, what if you need to dissect a value returned from Cocoa that’s actually a bit pattern such as the current state of a `UIDocument`

?

You test individual flags by using the bitwise-AND operator, which is a single ampersand: `&`

So say you’re handed a bit mask:

NSUInteger bit mask = 0x55;

And you want to see if the `NSRegularExpressionCaseInsensitive`

is set. You would do something like:

if (bitmask & NSRegularExpressionCaseInsensitive) { // ignore case }

Recall that bitwise AND looks at two bit patterns (`0x55`

, which is `01010101`

, and `NSRegularExpressionCaseInsensitive`

, which is `0x01`

, bit pattern `00000001`

) and makes a new, third bit pattern. Bits are set in the new pattern only if the corresponding bits are set in the two bit patterns. Have a diagram:

The resulting value is non-zero, so it’ll evaluate to true in the if statement above.

What about the other case, where that flag isn’t set? Say you started out with another bit mask, `0xFE`

, with a bit pattern of `11111110`

. All the bits are set **except** for `NSRegularExpressionCaseInsensitive`

. The result of the AND expression is zero, which will interpreted as false:

There is not a single bit that exists in both parts of the expression, so the result is zero.

### Clearing Flags

Clearing flags is the last part of this bit flag extravaganza. Say you’re manipulating the accessibility traits on an object in your iOS app. You have a view that can be “adjustable” at times (its value can be manipulated), and static at other times. You’ll want to change your `accessibilityTraits`

(which is a bit pattern) and turn the `UIAccessibilityTraitAdjustable`

flag on and off. Turning it on is easy:

self.accessibilityTraits |= UIAccessibilityTraitAdjustable;

You can combine the bitwise operators with the assignment operator, letting you use something like `|=`

exactly like you’d use `+=`

.

Clearing a bit, though, is more work. It’s actually a two step process. Consider the tools at our disposal. Can bitwise-OR be used to test the flags? Not really. OR combines two bit patterns and forms their union. It’s hard to single someone out when the crowd just keeps getting bigger.

That leaves bitwise-AND. AND works like intersection. Maybe we could intersect the original value with a mask that would let every bit through **except** for the bit we want to clear. How to construct that mask?

Bitwise-NOT to the rescue! Hopping back to regular expressions for a second, NOT-ing a mask like `NSRegularExpressionCaseInsensitive`

gives you a mask that has all bits set, **except** for the magic bit for the `CaseInsensitive`

value:

What happens if you AND this value with another bit mask, like `0x55`

(`01010101`

)

All the set-bits survive, except for `CaseInsenstive`

. You’ve now cleared out the bit specified by the `CaseInsensitive`

mask!

Applying this back to accessibility, you would clear the adjustable bit by doing:

self.accessibilityTraits &= ~UIAccessibilityTraitAdjustable;

If you think that looks weird, you’re right. But after you’ve done this stuff for awhile, you’ll be able to walk up to code like this and immediately grok its semantics: clear that particular bit.

### Playing with this live

One of the best ways to learn this stuff is to play around with it. You can write little one-off programs and print out values. An interesting exercise is printing out the bit pattern for an integer. You can also purchase “computer-science calculators”, such as my beloved HP-16C and their apps that do the same thing.

But don’t forget that you have an interactive bit masher already installed on your machine: lldb and/or gdb. You can run the debugger from the command line and use it like a shell to explore the bitwise operations. The `print` command is the key. It will evaluate expressions, and will also let you decorate the command with a type specifier: `/x`

for hex, `/d`

for decimal, and `/t`

for binary. Want to see the result of a shift?

$ lldb (lldb)print/t 1<<5(int) $1 = 0b00000000000000000000000000100000

That’s an annoying number of zeros. If you want to see just one byte’s worth, cast it to a `char`

:

(lldb)print/t (char)(1<<5)(char) $3 = 0b00100000

Play with bitwise-OR:

(lldb)print 0x2A | 0xD2(int) $4 = 250 (lldb)print/t 0xFA(char) $5 = 0b11111010 (lldb)print/x $5(int) $5 = 0x000000fa

What’s that `$3`

, `$4`

business? Every time you calculate or print a value, it gets assigned to a new variable that you can reference in later expressions.

### That’s all folks

I hope you’ve enjoyed this brief romp through basic bitwise operators. Like them or not, they’re used in Cocoa, so it’s good to be familiar with them. To know why adding bit flags is generally a bad idea, and to know what you need to do (or at least know where to look up) to set and clear bits in a chunk of memory.

## 6 Comments

Mark – Great coverage of the topic. Always wonderful. A few suggestions:

1) The bit pattern for 0xD2 in the paragraph on bitwise-AND starting “The syntax is” is not correct. It shows 11111010 (0xFA) rather than 11010010.

2) The term ‘twiddle’ is overloaded. You present it as an alias for the bitwise-NOT operator (tilde/twiddle) and as a general term to manipulate bits. This is confusing.

3) Your NSHipster reference on NS_OPTIONS is the third paragraph after introducing the subject. I had already left the article to look it up and found the reference on my own. It needs to be closer to the introduction of the example.

Your book, “Advanced Mac OS X Programming” is terrific. I would love to be a first reader for you on any future books.

Thanks for the kind words! I fixed 1, and moved the NSHipster reference up to right after the first use of NS_Options. I left #2 – there needs to be

somethingconfusing when dealing with bitsThanks for the article, Mark!

A few typo nit-picks, if you are interested in fixing them:

1) “such as my beloved HP-16C and there apps that do the same thing.” should be “such as my beloved HP-16C and their apps that do the same thing.”

2) Got some wrong-facing apostrophes when adding possessives to hex numbers, e.g., “Hex 0x2A‘s pattern” and “can now look at 0×21‘s bit pattern”

3) Looks like maybe some errant punctuation: “The resulting value is non-zero, so it’ll evaluate to true in the if statement above.?”

Thanks for the edits! #2 is just a straight quote. Not feeling like wrestling with wordpress to get the correct symbol Fixed the other two.

Excellent article! Any time I had used these was usually just a quick inline OR for params, not understanding the full reasoning and math behind it all. This made perfect sense! Thank you for taking time to write this.

My pleasure! Knowledge is definitely power.