Common Cocoa Coding Patterns

There are 7 entries in this Category.

Auto Layout: How to do percentage-based layouts

I recently had to implement a two-directional slider (I.e. a box with an indicator that can go anywhere). I wanted to do it using modern auto layout, and I needed it to resize properly on rotation without me having to change internal variables.

That meant that the position of the slider knob would have to be specified as a percentage (well, fraction) in the multiplier of the constraints, so that whatever size the slider UIView had, it would adapt.

My first attempt was to simply specify the position as a multiple of the height. So [self.indicatorView.centerXAnchor.constrainToAnchor: self.widthAnchor multiplier: 0.0].active = YES would be left, and multiplier: 1.0 would be right (and analogously for the Y direction).

That worked fine, but had the problem that the indicator could end up “tucked under” the left or right edges. I tried using UIView‘s layoutInsets, but that didn’t work either. In the end, I would have to manually add the fraction that my indicator’s width corresponded to to the ends to avoid that from happening. Might as well use pixels, then.

The autolayout margin guides

Then I remembered I could just add additional UILayoutGuides (MacOS has NSLayoutGuides) to define the margins I wanted to keep clear, then define another layout guide relative to those for the actual draggable area, relative to which I could constrain my indicator.

So first I built 4 guides that were pinned to the edges, had a width (resp. height) of 0.5 × indicatorView.widthAnchor (resp. heightAnchor) and a height/position (resp. width/position) same as the slider view.

Now we had the margins. Then I added a 5th guide that covered the draggable area inside those guides. Then took the old constraints and made them relative to this guide instead of the entire view.

That didn’t work. The height starts at 0, so if used as a position, it would always end up in the upper left. And if I added a constant the size of the margins, I’d have something that wouldn’t update when the view resized again. Might as well use pixels, then.

Drag area and indicator position layout guide (in blue)

Then it struck me: Why not just add another guide? The guide is pinned to the upper left of the draggable area, and its width/height are percentages of the draggable area’s height. I can now set the multiplier on the width/height constraints to my slider percentages, and the lower right corner of this 6th “indicator position” guide would be exactly where I want the indicator to be.

So I just change this guide’s multipliers when the indicator moves, and bind the indicator view’s center to the bottom and right anchors of the indicator position guide, and it all works!

Note

You may note that I keep talking about changing the multiplier on constraints. Yeah, that’s not really possible, the only thing on a constraint that can change is the constant (well, and the identifier, but that would ruin the joke).

So yeah, wherever you read that, what I do is remove and recreate the constraint. Sadly, constraints do not have a -removeFromSuperview method, so what I really have to do is walk from a constraint’s firstItem and secondItem property up to their common ancestor and tell it to remove the constraint (if they are views … if they are guides, that means they’re constraints on self or one of its superviews).

Cocoa and the Builder Pattern

There’s been a nice discussion about the Builder pattern on Twitter today. The Builder pattern is a nice tool to have, particularly because it addresses a few common problems.

What Builder Pattern?

In short, the Builder pattern is a pattern where you have one object that you configure that then creates another object based on that configuration. The nice thing here is that you can first build your object step by step, like you’d e.g. do with NSMutableString, but then the actual construction of the object happens in one go. Very handy for immutable objects.

Usually, a setter for a Builder object returns self, like retain or autorelease do. That way, you can create something in Java or C++ that almost looks like Objective C:

Image theImage = (new Image.Builder)->SetWidth(100)->SetHeight(80)->SetDepth(8)->Build();

Where the Build() method releases the builder and returns the actual, immutable Image object.

Extending init methods

When you add a parameter to an initializer in Objective-C, it is annoying. You usually add the parameter to the initializer, then create a compatibility version with the old method’s name that calls the newer version with a default value for the extra parameter.

Java and C++ have solved that problem by allowing you to specify default values for parameters, but they don’t maintain binary stability that way. If you add a parameter, you still have to recompile, but at least you don’t need to change your code.

I guess one fix would be if ObjC supported default arguments to a parameter that would simply result in the creation of a second version of this initializer with the label and parameter removed:

-(id) initWithBanana: (NSBanana*)theBanana curvature: (CGFloat)curvature = 5
{
    // magic happens here
}

Would be the same as writing:

-(id) initWithBanana: (NSBanana*)theBanana curvature: (CGFloat)curvature
{
    // magic happens here
}


-(id) initWithBanana: (NSBanana*)theBanana
{
    return [self initWithBanana: theBanana curvature: 5];
}

Of course, you’d still need at least one parameter, because ObjC has no way of knowing what part of the message is the name, and what is the label for the second (for init there could be special code, I guess, but what for a -exfoliateCow:withSpeed: method?). And defaulting to -initWithBanana if the first parameter has a default is obviously not always desirable either. It would solve the annoyance of telescoping constructors, at the least.

The Builder pattern doesn’t have this problem. Each parameter has a setter that you use to set it. A new builder could have defaults for all parameters when it is created. Then you change the ones you want to customize, and call -build on it to get the new object. If a new setter is added, that’s fine. You don’t call it, you get the default. The maintainers only add the one setter, no compatibility method needed.

Thread safety and immutable objects

The easiest way to get thread safety is to prohibit data from changing. If data is immutable, there is nothing to be synchronized between threads,and no need for one thread to wait for the other. However, immutable objects are also annoying, as they need to be fully specified in their init method.

A case where this is a problem in Cocoa is NSImage. NSImage is an immutable object by convention, but not actually. It is an object that has its own builder built in. You are expected to know that, for an NSImage to be thread safe, you are expected to create it, set its attributes, draw something in it, and then stop messing with it, treating it as an immutable, read-only object from then on.

The problem is, nobody enforces it. NSImage is a perfectly mutable object, with setters and getters. There is no exception thrown when you violate this verbal contract. Of course Apple could have added a “makeImmutable” method to NSImage that causes those exceptions to happen when you try to edit an instance. But then they’d have to add code to each setter that errors (Or at the least use some aspect-oriented-programming mechanism to inject code before every setter that performs this check automatically).

The Builder pattern would solve that: They can have a huge, private constructor on NSImage that changes with every release to add new parameters and initialize that immutable object, while the Builder would present a stable and convenient API to all clients. There would not be any setters on NSImage.

But it is ugly…

Admittedly, it feels a bit inelegant to build an object that builds an object. The way NSImage works is so much nicer. But Mike Lee actually offers a neat approach that works almost as well:

Just pass in a list of properties. This could be a dictionary of properties, or even just a variadic argument list like -dictionaryWithObjectsAndKeys: takes it. You’d define a constant for each possible property (that way if you mis-type the parameter name the compiler tells you, which you don’t get from a raw string). Internally, this constant could even hold the actual name of the property, even if it is never exposed as a method in the public header. So, all your constructor would do is call [self setValue: properties[key] forKey: key] in a loop, once for every element.

You get the same effect as labeled parameters (if you put the keys first, even more so). You also get the same effect as optional parameters. The binary ABI never changes, so that’s good, too. The only downside is you need to pass every parameter as an object, and you lose compile-time type checks. OTOH you gain compile-time errors when you try to change the object after creating it (because it declares no setters).

Is it worth all that work?

Admittedly, I haven’t had to add parameters to the init method of a public class that often. Nonetheless, I think Mike’s approach and the Builder pattern both are useful things to keep in mind if you ever come up with a class that can be created in numerous configurations (and is likely to gain new properties in the future) but should then be immutable. Class clusters and plug-in classes seem like a typical place where you might need this.

Are your rectangles blurry, pale and have rounded corners?

One common problem with drawing code in Cocoa (iOS and Mac OS X) is that people have trouble getting crisp, sharp lines. Often this problem ends up as a question like “How do I get a 1-pixel line from NSBezierPath” or “Why are my UIBezierPath lines fuzzy and transparent” or “Why are there little black dots at the corners of my NSRect”.

The problem here is that coordinates in Quartz are not pixels. They are actually “virtual” coordinates that form a grid. At 1x resolution (i.e. non-Retina), these coordinates, using a unit commonly referred to as “points” to distinguish them from act pixels on a screen (or on a printer!), lie at the intersections between pixels. This is fine when filling a rectangle, because every pixel that lies inside the coordinates gets filled:

filled_rectangle_between_pixels

But lines are technically (mathematically!) invisible. To draw them, Quartz has to actually draw a rectangle with the given line width. This rectangle is centered over the coordinates:

coordinates_between_pixels

So when you ask Quartz to stroke a rectangle with integral coordinates, it has the problem that it can only draw whole pixels. But here you see that we have half pixels. So what it does is it averages the color. For a 50% black (the line color) and 50% white (the background) line, it simply draws each pixel in 50% grey. For the corner pixels, which are 1/4th black and 3/4ths black, you get lighter/darker shades accordingly:

line_drawing_between_pixels

This is where your washed-out drawings, half-transparent and too-wide lines come from. The fix is now obvious: Don’t draw between pixels, and you achieve that by moving your points by half a pixel, so your coordinate is centered over the desired pixel:

coordinates_on_pixels

Now of course just offsetting may not be what you wanted. Because if you compare the filled variant to the stroked one, the stroke is one pixel larger towards the lower right. If you’re e.g. clipping to the rectangle, this will cut off the lower right:

coordinates_on_pixels_cut_off

Since people usually expect the rectangle to stroke inside the specified rectangle, what you usually do is that you offset by 0.5 towards the center, so the lower right effectively moves up one pixel. Alternately, many drawing apps offset by 0.5 away from the center, to avoid overlap between the border and the fill (which can look odd when you’re drawing with transparency).

Note that this only holds true for 1x screens. 2x Retina screens exhibit this problem differently, because each of the pixels below is actually drawn by 4 Retina pixels, which means they can actually draw the half-pixels needed for a 1 point wide line:

coordinates_between_pixels_retina

However, you still have this problem if you want to draw a line that is even thinner (e.g. 0.5 points or 1 device pixel). Also, since Apple may in the future introduce other Retina screens where e.g. every pixel could be made up of 9 Retina pixels (3x), you should really not rely on fixed numbers. Instead, there are now API calls to convert rectangles to “backing aligned”, which do this for you, no matter whether you’re running 1x, 2x, or a fictitious 3x. Otherwise, you may be moving things off pixels that would have displayed just fine:

coordinates_on_and_between_pixels_future_retina

And that’s pretty much all there is to sharp drawing with Quartz.

Mapping Strings to Selectors

MappingStringsToSelectorsSketchBack in the old days of Carbon, when you wanted to handle a button press, you set up a command ID on your button, which was a simple integer, and then implemented a central command-handling function on your window that received the command ID and used a big switch statement to dispatch it to the right action.

In Cocoa, thanks to message sending and target/action, we don’t have this issue anymore. Each button knows the message to send and the object to send it to, and just triggers the action directly. No gigantic switch statement.

However, we still have a similar issue in key-value observing: When you call addObserver:forKeyPath:options:context, all key-value-observing notifications go through the one bottleneck: observeValueForKeyPath:ofObject:change:context:. So, to detect which property was changed, you have to chain several if statements together and check whether the key path is the one you registered for (and check the ‘context’ parameter so you’re sure this is not just a KVO notification your superclass or subclass requested), and then dispatch it to a method that actually reacts to it.

It would be much nicer if Apple just called a method that already contained the name of the key-value-path, wouldn’t it? E.g. if the key-path you are observing is passwordField.text, why doesn’t it call observerValueOfPasswordField_TextOfObject:change:context:?

But there is a common Cocoa coding pattern that can help us with this: Mapping strings to selectors. The centerpiece of this method is the NSSelectorFromString function. So imagine you just implemented observeValueForKeyPath:ofObject:change:context: like this:

-(void) observeValueForKeyPath: (NSString*)keyPath ofObject: (id)observedObject change: (NSDictionary*)changeInfo context: (void*)context
{
    NSString *sanitizedKeyPath = [keyPath stringByReplacingOccurrencesOfString: @"." withString: @"_"];
    NSString *selName = [NSString stringWithFormat: @"observeValueOf%@OfObject:change:context:", sanitizedKeyPath];
    SEL      action = NSSelectorFromString(selName);
    if( [self respondsToSelector: action] )
    {
        NSInvocation * inv = [NSInvocation invocationWithMethodSignature: [self methodSignatureForSelector: action]];
        [inv setTarget: self]; // Argument 0
        [inv setSelector: action]; // Argument 1
        [inv setArgument: &observedObject atIndex: 2];
        [inv setArgument: &changeInfo atIndex: 3];
        [inv setArgument: &context atIndex: 4];
        [inv invoke]
    }
    else
        [super observeValueForKeyPath: keyPath ofObject: observedObject change: changeInfo context: context];
}

We build a string that includes the name of the key-path, turn it into an actual selector, and then use -performSelector:withObject:, or in more complex cases like this one NSInvocation, to actually call it on ourselves.

For cases that have no clear mapping like this, you can always maintain an NSMutableDictionary where the key is whatever string your input is and the value the selector name for your output, and then use that to translate between the two. When you make whatever call equivalent to addObserver: you have in that case, it would add an entry to the dictionary. That’s probably how NSNotificationCenter does it internally.

Update:
As Peter Hosey pointed out, another good use case for this pattern is -validateMenuItem: where one could turn the menu item’s action into a string and concatenate that with ‘validate’.

Blocks and block lists

doctor_who_blocks

When I first heard about blocks, I was horrified. All the un-clean code structure of huge ten-page functions, plus the loss of self-documenting function names. Why would someone want anonymous functions? And even worse, anonymous functions that can cause retain circles because they automatically retain objects you reference, because they have access to the scope of the surrounding function, like nested functions?

Then, at one NSConference, someone pointed out that they are really good for making asynchronous code look more synchronous. Who would have thought that blocks, carefully used, could actually improve readability of code?

Imagine you are using an NSURLConnection to retrieve a JSON file from a server and extract information from it. In synchronous pseudocode:

-(void) showInfo
{
    NSString* myJSON = [NSString stringWithContentsOfURL: @"http://example.com/data.json"];
    if( myJSON == nil )
    {
        [self reportError];
        return;
    }
    NSString* userText = [self prettyPrintJSON: myJSON];
    [self showPanelWithText: userText button: @"OK"];
}

Minimal code for doing this asynchronously and avoid blocking the user interface and spinning the beach ball when the connection is slow includes creating an NSURLConnection, setting yourself as its delegate then displaying any error you get from one delegate method, or when the request completes and a second is called, to actually process the request. So the above code turns into pseudocode:

-(void) showInfo
{
    self.connection = [[NSURLConnection alloc] initWithURL: @"http://example.com/data.json"];
    myConnection.delegate = self;
    [myConnection start];
}

-(void) connection: (NSURLConnection*)sender didFinishLoading: (NSString*)myJSON
{
    NSString* userText = [self prettyPrintJSON: myJSON];
    [self showPanelWithText: userText button: @"OK"];
    self.connection = nil;
}

-(void) connectionDidFailLoading: (NSURLConnection*)sender
{
    [self reportError];    
}

Notice how 5 straightforward lines have turned into a spaghetti of three methods? Now imagine you had to chain several requests. You’d have to create separate delegate objects for each request, or key off the ‘sender’ parameter and handle the OK case for all requests together in one delegate method, and the error cases together in another.

Now how does that look with blocks (still pseudocode)?

-(void) showInfo
{
    [NSURLConnection sendAsynchronousRequest: @"http://example.com/data.json" completionHandler: ^( NSURLRequest req, NSString* myJSON, NSError* error )
        {
            if( error )
            {
                [self reportError];
                return;
            }
            NSString * userText = [self prettyPrintJSON: myJSON];
            [self showPanelWithText: userText button: @"OK"];
        }];
}

Shockingly, that almost looks like our original, synchronous code. Now to be fair, if someone at Apple had added a delegate method to NSURLConnection that combined the error case and the success case like the above block does, the original example would be a tad simpler as well. But performing several requests in sequence would still split the actual requests from their replies, and group them by request or reply.

With blocks, on the other hand, two requests in sequence would look almost like the synchronous code would, with nested ifs:

-(void) showInfo
{
    [NSURLConnection sendAsynchronousRequest: @"http://example.com/data.json" completionHandler: ^( NSURLRequest* req, NSString* myJSON, NSError* error )
    {
        if( error != nil )
        {
            [self reportError];
            return;
        }

        NSString* userText = [self prettyPrintJSON: myJSON];
        [self showPanelWithText: userText button: @"OK"];

        [NSURLConnection sendAsynchronousRequest: @"http"//example.com/data2.json" completionHandler: ^( NSURLRequest* req2, NSString* myJSON2, NSError* error2 )
        {
            if( error2 != nil )
            {
                [self reportError];
                return;
            }

            NSString * userText2 = [self prettyPrintJSON: myJSON2];
            [self showPanelWithText: userText2 button: @"Done"];
        }];
    }];
}

You’re probably already seeing where our problem is, though. Since every block adds one level of brackets and depth, it becomes pretty hard to re-order requests. You’d have to cut the inner request out, then wrap it around the outer request so it only triggers the other request on success.

But here is where it comes in handy that blocks aren’t just nested functions. Blocks are actually real Objective-C objects. So, we can keep an array of blocks:

-(void) showInfo
{
    NSMutableArray * steps = [NSMutableArray array];
    [steps addObject: ^( NSMutableArray * steps )
    {
        // First request start:
        [NSURLConnection sendAsynchronousRequest: @"http://example.com/data.json" completionHandler: ^( NSURLRequest* req, NSString* myJSON, NSError* error )
        {
            if( error != nil )
            {
                [self reportError];
                return;
            }

            NSString* userText = [self prettyPrintJSON: myJSON];
            [self showPanelWithText: userText button: @"OK"];
            // First request end.

            [[steps[0] retain] autorelease]; // Make sure we don't go away.
            [steps removeObjectAtIndex: 0];
            steps[0]( steps );
        }];
    }];
    [steps addObject: ^( NSMutableArray * steps )
    {
        // Second request start:
        [NSURLConnection sendAsynchronousRequest: @"http://example.com/data2.json" completionHandler: ^( NSURLRequest* req2, NSString* myJSON2, NSError* error2 )
        {
            if( error2 != nil )
            {
                [self reportError];
                return;
            }

            NSString* userText2 = [self prettyPrintJSON: myJSON2];
            [self showPanelWithText: userText2 button: @"OK"];
            // First request end.

            [[steps[0] retain] autorelease]; // Make sure we don't go away.
            [steps removeObjectAtIndex: 0];
            steps[0]( steps );
        }];
    }];
    [steps addObject: ^( NSMutableArray * steps )
    {
        // Done.
    }];
    steps[0]( steps ); // Kick off execution
}

So, we add the blocks to an array with 3 -addObject: calls, then at the bottom run the first block in the array. When each block is done, it removes itself from the array, and runs the next block in the array (except for the last block, which is simply there so the second-to-last block has someone after it to call — we could also just check whether the array is empty before trying to call the next block). This looks a little more complicated than it should, but if wrapped in an ObjC class with a -next method is very readable.

Now, if you want to re-order two requests, you simply re-order the -addObject: calls. Since none of the blocks care which block follows them, you don’t need to wrap anything around anything else.

You can now read all requests in sequence (hence I call these things block sequences), ignoring the spots at which control is given up to the system for a while, and re-arrange them as you please. Neat, huh?

Common Cocoa Coding Patterns: NSError returns

A sad iMac

Error reporting wasn’t something Cocoa did in much detail in the early days. There were nil return values instead of objects, or a BOOL that was YES on success.

C didn’t have exceptions, and by the time ObjC got “fake” exceptions based on the longjmp() mechanism, all wrapped up nicely in NSException and NS_DURING/NS_HANDLER/NS_ENDHANDLER macros, most of the framework API had already been written and it would have been too much work to make all of it work with exceptions and adapt all applications to watch for exceptions in error situations. So they were reserved mostly for Distributed Objects (where an additional error return wasn’t possible) and programming errors.

But with the release of Safari and WebKit in 2003, someone at Apple realized they needed more detailed and standardized error information, and introduced the NSError class. NSError is a simple container object for any error code you might encounter on your Apple device, plus a dictionary for any other info like an error message.

Error codes are not unique across all the libraries, frameworks and system services that are on your device, so each error code is also identified by its domain, an arbitrary string constant. For example, Mac OS X offers the NSCocoaErrorDomain, NSOSStatusErrorDomain, NSPOSIXErrorDomain and NSMachErrorDomain error domains, which let you wrap Cocoa framework error codes, Carbon/CoreServices error codes, standard Unix error codes and kernel errors unambiguously, all by wrapping them in an NSError. And you can make up your own for your application, library, and even for a single class. Whatever logical unit of encapsulation makes the most sense.

Most NSErrors are returned as a return parameter. This has the advantage that methods that already have a return value can still be implemented as they were before the arrival of NSError, and can return nil to have an entire chained expression collapse. E.g., a fictional

NSError    theErr = nil;
ULIObject  obj = [[[ULIObject allocGivingError: &theErr] initGivingError: &theErr] autoreleaseGivingError: &theErr];

can fail at any of the three calls and return nil, and none of the subsequent messages will be sent, nor will they touch theErr.

However, one thing Apple tells us is that we shouldn’t look at theErr above unless obj is nil. Why is that? Well, imagine a possible implementation of our fictional autoreleaseGivingError::

-(id) autoreleaseGivingError: (NSError**)outError
{
    ULIAutoreleasePool* currentPool = [ULIAutoreleasePool _currentPoolGivingError: outError];
    if( currentPool == nil )
        currentPool = [NSAutoreleasePool _createBottomPool];
    if( currentPool == nil )    // Still couldn't create?
    {
        // Hand on whatever error _currentPoolGivingError: had.
        return nil;
    }
    
    [currentPool addObject: self];
    return self;
}

Our fictional internal _currentPoolGivingError: method here might return nil and give us an NSError when there is no pool in place yet.

But in the most common case, we will be able to recover from this error by creating the pool 1.

So in most cases, we’ll just create the pool and add the object to it. If callers look at theErr in such a situation, they will see the error object put there by _currentPoolGivingError:, from which we recovered. So they will see an error where none occurred.

And that, kids, is why you always check the return value, and not just the error parameter.

1) This is nonsense in real life, because nobody would ever release this bottom pool and we’d have a quiet leak, but let’s just assume in our example’s world ULIRunLoop will release this bottom pool once it regains control, as part of a lazy-allocation-of-pools scheme.

Common Cocoa Coding Patterns: UITableView row index enum

One of the things pretty much every iPhone application has is a table view containing a pre-defined list of main menu items that lead to deeper sections. Many people just hard-code this list and the item indexes, only to later find out that they need to display some rows conditionally. The code becomes a mess of conditional statements duplicated all over the place to adjust the indexes in the case that a certain item does not apply.

But there is an easier way. The first thing you do, is create an enum with the item indexes:

enum
{
    kMainTableRowInbox = 0,
    kMainTableRowTrash,
    kMainTableRowSpam,
    kMainTableNumberOfRows
};

Whenever you would use the indexes, e.g. in your table view data source and delegate methods, use these constants instead. You have the same code as before, but if you want to add/insert a new item, you can just add the constant for it in the right spot, and the rest of your code magically updates itself.

If you have one source file that implements the main list for several similar products, you can even use the preprocessor to remove items that are only needed for one device. However, what do you do if you dynamically need to add/remove items at runtime? E.g. if your application can talk to two kinds of servers, and one has a kMainTableRowTrash, but the other kind doesn’t? Simple: You create a look-up-table:

static NSUInteger          sRowLookUpTable[kMainTableNumberOfRows] = { 0 };
static NSUInteger   sRowLookUpTableSize = 0;

-(void) rebuildRowLookUpTable
{
    NSUInteger  actualRowNumber = 0;
    for( NSUInteger virtualRowNumber = 0; virtualRowNumber < kMainTableNumberOfRows; virtualRowNumber++ )
    {
        if( virtualRowNumber == kMainTableRowTrash && ![self haveTrash] )
            continue;
        sRowLookUpTable[actualRowNumber] = virtualRowNumber;
        actualRowNumber++;
    }

    sRowLookUpTableSize = actualRowNumber;
}

Call this in your init method(s), or whenever some state changes that may affect which rows should be shown. Change your table view delegate methods to use sRowLookUpTableSize instead of kMainTableNumberOfRows for the number of rows. And whenever you look at an index to compare it to one of the row index constants, do

sRowLookUpTable[indexPath.row]

instead of just

indexPath.row

to translate the real row index into one of the constants that indicate what content you want displayed. This way, most of your code never needs to know in which order which items are actually shown in your table. It just needs to be able to display all kinds of rows, and only -rebuildRowLookUpTable needs to actually know which rows are hidden or visible.

Also, the constant names make it obvious what row a bit of code is dealing with. If, two years after you wrote an app on contract, the customer comes back and wants it updated for MacBook Airs with iOS, and remove the settings category, you can just search for a kMainTableRowSettings constant in the text editor and get rid of all that code. Or just move the constant below the kMainTableNumberOfRows constant. All the code is still there, compiles, but the index will never be added to the table.