Name
Array -- collection supporting access to fixed group of members
Synopsis
//
// Array -- collection supporting access to fixed group of members
//
@deftype Array
CREATING
+ create: aZone setCount: (int)count;
+ create: aZone setMemberBlock:(id *)members setCount:(int)count;
SETTING
- (void) setCount: (int)count;
- (void) setDefaultMember: memberValue;
- (void) setMemberBlock: (id *)members setCount: (int)count;
USING
- getDefaultMember;
- (id *) getMemberBlock;
@end
Description
An array is a collection of members that are all created as members
of the collection at the same time. Existing member values may
be replaced with new values, but the members themselves are fixed
at constant offsets within the collection. The fixed structure of
an array permits very fast access to members by integer offset
positions, since the location of each member may be directly
calculated.
The Array type is one of the simplest collection types in the collections
library, and the closest to a data structure directly supported in C.
Unlike C arrays, the group of members belonging to the array is not
necessarily fixed for the lifetime of the array, but may be dynamically
resized to contain a different number of members. When an array is
dynamically resized, existing member values are preserved as much as
possible.
The Array type adds few messages to the generic messages inherited from
Collection. This type is provided partly so that a fixed-structure array
can be accessed with the same uniform set of basic messages as any other
kind of object collection. It also handles all required memory allocation
within the collection. As an option, however, the Array type can be used
to wrap an existing C array for external access as an object collection.
It can also provide access to an internal C array for direct manipulation
using C expressions. These forms of low-level access support hybrid modes
of use in which advantages of both low-level manipulation and external
object access can be combined.
Inherited behavior
@deftype Array
The Array type is directly creatable, and supports all standard messages
of Collection except removal of individual members. The messages based on
an integer offset, either on the collection (atOffset:, atOffset:put:), or
an index (setOffset:) all execute in fast constant time. Members of an
array are fully ordered according to these integer offsets. Sequential
access to members through its members is also fully supported. The Array
type disables the remove message inherited from Collection; the message is
defined, but any attempt to remove a member will raise an error that the
operation is not supported.
While the IndexSafety option of an Array defaults to Unsafe, indexes are
inherently safe under all operations with the exception of resizing
an array or resetting its member allocation. (The only individual member
operation which modifies contents of an array is replacing a member
value, and this does not affect existing indexes.) The UnsafeAtMember
value of IndexSafety is not supported since individual members cannot
be added or removed. A value of SafeAlways makes existing indexes safe
even under resizing or reallocation. If an existing index referred to a
member location that is no longer contained in the array, the index
location is reset to the End location.
The default value of the ReplaceOnly option is true, and cannot be
overridden.
The type of index returned by begin: on an array is simply Index. There
is no special index type for Array because there are no additional
messages beyond those already defined by Index.
Create-time options
SETIING
- (void) setCount: (int)count;
- (void) setDefaultMember: memberValue;
- (void) setMemberBlock: (void *)members setCount: (int)count;
USING
- (void) setDefaultMember: memberValue;
- getDefaultMember;
- (void) setMemberBlock: (void *)members setCount: (int)count;
- (void *) getMemberBlock;
All the Array create-time options can also be set after the array is
already created, subject to restrictions noted below.
Count
The Count option sets the number of members which belong to the collection.
Any non-negative value including zero is valid. If the array already exists,
the any existing members up to the new count will preserve their existing
values. If the new count is greater than the existing count, or a new
array is being created, all members will be assigned an initial default
value of either nil, or a value previously specified for DefaultMember.
The inherited getCount message of Collection obtains the current value set
for this option. There is no way to add or remove members of an array
except using the setCount: message directly.
DefaultMember
When this option is set, the initial value of all new members will be set
to the member value given (otherwise the default is nil). This option
gives a convenient way to distinguish members which have never been set
from any other valid member value, which could include nil. This option
may be reset after array creation only if some setting for the option was
given at create time. (The initial, explicitly set value can still be the
default nil, but a value must be set explicitly for the option to be
resettable later). The get message for this option always retrieves the
current setting, but this value has no effect except when the count of an
array is increased, so that new members need to be initialized.
MemberBlock
This option provides a means to wrap an existing C array for access as
an object collection. If this option is given, dynamic resizing is
not supported. The current C array being wrapped, however, can be
replaced by giving a new setting for MemberBlock after an array already
exists. A new setting can be given only if some setting was initially
given at create time.
Even if a setting was not given for MemberBlock at create time, the get
message for MemberBlock always returns a pointer to whatever internal
memory array is currently being used by the array object. If a
MemberBlock setting was given, the pointer returned will be the same as
the one previously given. In either case, the pointer returned may be
used to manipulate member values in any way desired using native C
expressions. After an array has been created, there is no way to
determine whether the MemberBlock pointer was established externally or by
internal allocation. If the pointer was established by internal
allocation, however, the external program must make no attempt to free or
otherwise reallocate this memory.
A count must always be supplied with an external member allocation, using
the setCount: argument of the compound message. If an external allocation
is being used, the only way to reset the count is also to reset
MemberBlock; any attempt to use the setCount: message by itself will raise
an error. Whenever an external member allocation is being used, the
external program is entirely responsible for assuring that the MemberBlock
value is a pointer to valid allocated memory containing at least the
number of member slots given by setCount:.
With an external member allocation, the array itself will not attempt to
either allocate this memory or free it when the array is dropped. Dropping
the array only removes its reference to the external allocation.
The pointer to allocated memory is given as a pointer to id type, but if a
data type given as MemberType has size greater than id, the pointer must
actually point to an array of slots each of which has the size of the data
type.
Since an array neither allocates nor frees an external member allocation,
the same region of allocated memory may be referenced by multiple arrays,
including overlapping member ranges each defined by starting location and
count. This flexibility enables alternate subrange views of a single,
contiguous initial allocation by means of separately created external
collections.
Create combination messages
CREATING
+ create: aZone setCount: (int)count;
+ create: aZone setMemberBlock:(id *)members setCount:(int)count;
In addition to the standard inherited create messages, the Array type
supports two forms of combination messages which both create the array and
set its initial options. These are provided both for convenience and to
provide the fastest possible array creation for simple cases in which
speed might be important. The two cases supported are creating an array
with a member count for its internal members already set, and creating an
array which refers to an external member allocation. If any more options
than these are needed, the normal method of setting options between
createBegin: and createEnd messages should be used instead.
Roger Burkhart <rmb@santafe.edu>
Last modified: