Inherits from NSObject
Conforms to NGLIterator
NSFastEnumeration
Declared in NGLArray.h

Overview

This class is a collection that works just like an array, however it’s generic for any kind of data type, including basic C types. NGLArray does not retain the object.

This class is faster than the traditional NSArray. Depending on the tasks, NGLArray can be 50% faster than NSArray, the most expensive task of NGLArray is at least 15% faster than NSArray, which is “removeAll”. Actually, this class is more like a NSMutableArray, because you can change its collection at any time. This one also has a “hint” property called capacity, if you already know the maximum number of elements you can set this property to boost the performance a little bit more.

By default, every time you try to insert an item in this array and it’s capacity is full, a new block of 10 items will be allocated into this array.

The reasons that cause this one to be faster than NSArray are:

  • It basically work with pointers and dereference, instead of indices.
  • It has an internal iterator loop that manages the enumerations.
  • It doesn’t have many too checks. NGLArray assumes you know what you’re doing.

The achieve the best performance and still flexible, the NGLArray offers three kind of loops. Each one has its own cost and benefits:

  • NGLIterator: Loops through 100 millions in 1.5 seg.
    Uses NGLIterator protocol. This loop is good for small array in which you need to change it’s content during the loop or even from another thread. This routine offers a way to reset the loop at any time by calling the resetIterator method. The disadvantage of this routine is that it makes a Objective-C message call at each loop cycle, so it’s a little expensive compared to the other ones. Its syntax is:

id variable;
while ((variable = [myNGLArray nextIterator]))
{
// Do something...
}

  • NGLFor: Loops through 100 millions in 0.45 seg.
    Very fast loop using the iterator properties. Can deal with changes during the loop or even from another thread. Its disadvantage is that it has a special syntax and just resets the iterator loop at the beginning. So if you’re planning to use the NGLIterator after use this one, you must call resetIterator before start the NGLIterator. Its syntax is:

id variable;
nglFor (variable, myNGLArray)
{
// Do something...
}

  • ForEach: Loops through 100 millions in 0.3 seg.
    Uses NSFastEnumeration protocol (the Cocoa “for in” loop). This loop is the fastest one. However it’s be used only in few situations. Its disadvantage is that it only work with Objective-C objects and the array can’t be changed during the loop (changing the array during the loop will result in runtime error). Its syntax is:

id variable;
for (variable in myNGLArray)
{
// Do something...
}

The NGLArray class also provides a pointer to the items and a pointer to the mutations property. You can use them to implement your own NSFastEnumeration.

A category that extends the default behavior to perform some convenience method which could help when other classes makes use of this one.

Tasks

Other Methods

  •   capacity

    The capacity property is not the size/count of the array, it’s just a “hint” to optimize the array manipulation spped. This “hint” is useful for large array (above 10 items).

    property
  •   retainOption

    Indicates if this array will retain or not the objects in it. This property can’t be changed to ensure the integrity of the items and must be set when initializing this array. Only Objective-C objects can receive retain messages.

    property
  •   itemsPointer

    Returns the items pointer. This property is useful if you want to create your own implementation of NSFastEnumeration but keep using NGLArray as your collection.

    property
  •   mutationsPointer

    Returns the mutations pointer. This property is useful if you want to create your own implementation of NSFastEnumeration but keep using NGLArray as your collection.

    property
  •   values

    (Internal only) Returns a pointer to the array values. You should not call this method directly.

    property
  • – initWithRetainOption

    Initiates a NGLArray making it a safe collection, that means, it will retain every pointer that will be added to it. In this case, all pointer must be a subclass of NSObject.

  • – initWithNGLArray:

    Initiates a NGLArray instance based on another NGLArray.

  • – initWithPointers:

    Initiates a NGLArray instance based on many object/instances.

  • – addPointer:

    Adds a new object/instance to this collection. If the target already exist in this collection, it will be added again, resulting in a duplication.

  • – addPointerOnce:

    Adds a new object/instance to this collection only if the target is not already inside this collection. If the target already exist, nothing will happen.

  • – addPointersFromNGLArray:

    Adds all object/instance to this collection from another NGLArray. This method copies all objects/instances inside the informed NGLArray.

  • – indexOfPointer:

    Returns the index of a target inside this collection.

  • – hasPointer:

    Checks if a target is inside this collection.

  • – removePointer:

    Removes an object/instance inside this collection.

  • – removePointerAtIndex:

    Removes an object/instance in a specific position inside this collection.

  • – removeFirst

    Removes the very first object/instance in this collection.

  • – removeLast

    Removes the very last object/instance in this collection.

  • – removeAll

    Removes all the instances inside this library.

  • – objectAtIndex:

    Returns an object/instance in a specific position inside this collection.

  • – count

    Returns the number of instances in this library at the moment.

  • – forLoop:

    (Internal only) Prepares this array to work with “nglFor” loop. You should not call this method directly.

  • + array

    Returns an autoreleased instance of NGLArray.

NGLArrayExtended Methods

Properties

capacity

The capacity property is not the size/count of the array, it’s just a “hint” to optimize the array manipulation spped. This “hint” is useful for large array (above 10 items).

@property (nonatomic) unsigned int capacity

Discussion

The capacity property is not the size/count of the array, it’s just a “hint” to optimize the array manipulation spped. This “hint” is useful for large array (above 10 items).

The NGLArray will allocate the memory in sets/packages using this “hint” property.

Declared In

NGLArray.h

itemsPointer

Returns the items pointer. This property is useful if you want to create your own implementation of NSFastEnumeration but keep using NGLArray as your collection.

@property (nonatomic, readonly) NGL_ARC_ASSIGN id *itemsPointer

Discussion

Returns the items pointer. This property is useful if you want to create your own implementation of NSFastEnumeration but keep using NGLArray as your collection.

Remember that NSFastEnumeration is exclusive for Objective-C objects.

Declared In

NGLArray.h

mutationsPointer

Returns the mutations pointer. This property is useful if you want to create your own implementation of NSFastEnumeration but keep using NGLArray as your collection.

@property (nonatomic, readonly) unsigned long *mutationsPointer

Discussion

Returns the mutations pointer. This property is useful if you want to create your own implementation of NSFastEnumeration but keep using NGLArray as your collection.

Remember that NSFastEnumeration is exclusive for Objective-C objects.

Declared In

NGLArray.h

retainOption

Indicates if this array will retain or not the objects in it. This property can’t be changed to ensure the integrity of the items and must be set when initializing this array. Only Objective-C objects can receive retain messages.

@property (nonatomic, readonly) BOOL retainOption

Discussion

Indicates if this array will retain or not the objects in it. This property can’t be changed to ensure the integrity of the items and must be set when initializing this array. Only Objective-C objects can receive retain messages.

Declared In

NGLArray.h

values

(Internal only) Returns a pointer to the array values. You should not call this method directly.

@property (nonatomic, readonly) NGLArrayValues *values

Discussion

(Internal only) Returns a pointer to the array values. You should not call this method directly.

Declared In

NGLArray.h

Class Methods

array

Returns an autoreleased instance of NGLArray.

+ (id)array

Return Value

A NGLArray autoreleased instance.

Discussion

Returns an autoreleased instance of NGLArray.

Declared In

NGLArray.h

Instance Methods

addPointer:

Adds a new object/instance to this collection. If the target already exist in this collection, it will be added again, resulting in a duplication.

- (void)addPointer:(void *)pointer

Parameters

pointer

The target it self.

Discussion

Adds a new object/instance to this collection. If the target already exist in this collection, it will be added again, resulting in a duplication.

Declared In

NGLArray.h

addPointerOnce:

Adds a new object/instance to this collection only if the target is not already inside this collection. If the target already exist, nothing will happen.

- (void)addPointerOnce:(void *)pointer

Parameters

pointer

The target it self.

Discussion

Adds a new object/instance to this collection only if the target is not already inside this collection. If the target already exist, nothing will happen.

Declared In

NGLArray.h

addPointersFromNGLArray:

Adds all object/instance to this collection from another NGLArray. This method copies all objects/instances inside the informed NGLArray.

- (void)addPointersFromNGLArray:(NGLArray *)pointers

Parameters

pointers

The NGLArray instance to copy pointers from.

Discussion

Adds all object/instance to this collection from another NGLArray. This method copies all objects/instances inside the informed NGLArray.

Declared In

NGLArray.h

count

Returns the number of instances in this library at the moment.

- (unsigned int)count

Return Value

An int data type.

Discussion

Returns the number of instances in this library at the moment.

Declared In

NGLArray.h

forLoop:

(Internal only) Prepares this array to work with “nglFor” loop. You should not call this method directly.

- (NGLArrayValues *)forLoop:(void **)target

Parameters

target

A pointer to the target that will receive the items of this array. Inside this method the target will receive the first item.

Return Value

A pointer to the values of this array.

Discussion

(Internal only) Prepares this array to work with “nglFor” loop. You should not call this method directly.

Declared In

NGLArray.h

hasPointer:

Checks if a target is inside this collection.

- (BOOL)hasPointer:(void *)pointer

Parameters

pointer

The target it self.

Return Value

Returns YES (1) if the target is found, otherwise NO (0) will be returned.

Discussion

Checks if a target is inside this collection.

Declared In

NGLArray.h

indexOfPointer:

Returns the index of a target inside this collection.

- (unsigned int)indexOfPointer:(void *)pointer

Parameters

pointer

The target it self.

Return Value

Returns the index of the target or NGL_NOT_FOUND if the target was not found.

Discussion

Returns the index of a target inside this collection.

Declared In

NGLArray.h

initWithNGLArray:

Initiates a NGLArray instance based on another NGLArray.

- (id)initWithNGLArray:(NGLArray *)pointers

Parameters

pointers

A NGLArray to serve as base to the new NGLArray.

Return Value

A NGLArray instance.

Discussion

Initiates a NGLArray instance based on another NGLArray.

This method copies all objects/instances inside the informed NGLArray.

Declared In

NGLArray.h

initWithPointers:

Initiates a NGLArray instance based on many object/instances.

- (id)initWithPointers:(void *)first, ...

Parameters

first

The first object/instance to be added.

...

A sequence of objects/instances separated by commas. This method must end with a nil element.

Return Value

A NGLArray instance.

Discussion

Initiates a NGLArray instance based on many object/instances.

This method doesn’t make use of addPointerOnce, that means if a target is informed more than one time, it will remain duplicated inside this collection.

Declared In

NGLArray.h

initWithRetainOption

Initiates a NGLArray making it a safe collection, that means, it will retain every pointer that will be added to it. In this case, all pointer must be a subclass of NSObject.

- (id)initWithRetainOption

Return Value

A NGLArray instance.

Discussion

Initiates a NGLArray making it a safe collection, that means, it will retain every pointer that will be added to it. In this case, all pointer must be a subclass of NSObject.

The retained objects will receive a release message when they are removed or this instance of NGLArray is released.

Declared In

NGLArray.h

makeAllObjectsPerformSelector:

A convenience method that loops through all objects making them perform a selector.

- (void)makeAllObjectsPerformSelector:(SEL)selector

Parameters

selector

The selector which will be performed on all objects.

Discussion

A convenience method that loops through all objects making them perform a selector.

IMPORTANT: This method assumes you’re sure about this task and no additional check will be made to identify if the objects can receive such message. So, make sure all the objects are Objective-C instances and can receive the informed message.

Declared In

NGLArray.h

objectAtIndex:

Returns an object/instance in a specific position inside this collection.

- (void *)objectAtIndex:(unsigned int)index

Parameters

index

The index of the target. If the index is out of bounds, NULL will be returned.

Return Value

A pointer or NULL if no result was found.

Discussion

Returns an object/instance in a specific position inside this collection.

Declared In

NGLArray.h

removeAll

Removes all the instances inside this library.

- (void)removeAll

Discussion

Removes all the instances inside this library.

This method makes a clean up inside this library, freeing all allocated memories to the instances in it.

Declared In

NGLArray.h

removeFirst

Removes the very first object/instance in this collection.

- (void)removeFirst

Discussion

Removes the very first object/instance in this collection.

Declared In

NGLArray.h

removeLast

Removes the very last object/instance in this collection.

- (void)removeLast

Discussion

Removes the very last object/instance in this collection.

Declared In

NGLArray.h

removePointer:

Removes an object/instance inside this collection.

- (void)removePointer:(void *)pointer

Parameters

pointer

The target it self.

Discussion

Removes an object/instance inside this collection.

Declared In

NGLArray.h

removePointerAtIndex:

Removes an object/instance in a specific position inside this collection.

- (void)removePointerAtIndex:(unsigned int)index

Parameters

index

The index of the target. If the index is out of bounds, nothing will happen.

Discussion

Removes an object/instance in a specific position inside this collection.

Declared In

NGLArray.h