CFMutableArray grows beyond its capacity

Question

Considere I have a CFMutableArray object created with the following function call:

CFMutableArrayRef marray = CFArrayCreateMutable(kCFAllocatorDefault, 1, &kCFTypeArrayCallBacks);

According to the CFMutableArray Documentation, the second argument of CFArrayCreateMutable, which is called capacity, is "the maximum number of values that can be contained by the new array. The array starts empty and can grow to this number of values (and it can have less). Pass 0 to specify that the maximum capacity is not limited. The value must not be negative."

However, if I append more than one value to my new array, it keeps growing. I mean, if the new array already has one value and I append a new one with CFArrayAppendValue(marray, newValue), this value is stored and the array count goes to 2, exceeding its capacity.

So, why this happens? Did I misunderstand the documentation?

Answer 1

Interesting. I don't think you're mis-understanding the documentation. I will point out that CFMutableArrayRef is "Toll Free Bridged" on iOS with NSMutableArray and therefore interchangeable. On iOS [NSMutableArray arrayWithCapacity] is NOT so limited and capacity is basically "guidance" and NOT a hard upper limit.

It might be worth filing a bug report on that, probably the docs are just wrong.

UPDATE: Just goes to show ya... always, always, always follow the maxim of the best docs are the source. I CMD-clicked on CFArrayCreateMutable to look at the comment in the source .h file.... guess I was right, because that says 'capacity' is a HINT that the implementation may ignore, as it apparently does in this case.

@function CFArrayCreateMutable
⋮
@param capacity A hint about the number of values that will be held by the CFArray.
    Pass 0 for no hint. The implementation may ignore this hint,** or may use it to
    optimize various operations. An array's actual capacity is only limited by
    address space and available memory constraints). If this parameter is negative,
    the behavior is undefined.

Don't forget, header comments are written by developers, whilst "docs" are written by some tech writer that doesn't have the same depth of knowledge.

Answer 2

From docs:

CFArrayAppendValue Adds a value to an array giving it the new largest index.

Parameters

theArray The array to which value is to be added. If theArray is a limited-capacity array and it is full before this operation, the behavior is undefined.

So, I think you should only make sure not to add a value to a full limited-capacity array, or the behavior will be undefined!

Or, you can pass 0 for the capacity parameter to specify that the maximum capacity is not limited.

Update:

As @Cliff Ribaudo pointed out, it seems there is a contradiction between the official documentation and code documentation:

@param capacity A hint about the number of values that will be held by the CFArray. Pass 0 for no hint. The implementation may ignore this hint, or may use it to optimize various operations. An array's actual capacity is only limited by address space and available memory constraints).

So we can assume the online documentation is outdated and the code documentation is possibly the right.