@head
@title Array operations
These operations are provided for working with array objects. Only the most
commonly needed operations are supported. Generic operations such as
@ref{AAdd} and @ref{ACallMethod} can be used as well to perform additional
operations.
It is important to note that most of these operations only accept direct
instances of std::Array, i.e. they do not support subtypes of
Array. As a result of this limitation, these operations are
fast, since they do not have to verify the type of argument objects and
can directly access the internals of array objects without having
to perform polymorphic method dispatches.
Code that wishes to remain faithful to Alore semantics and avoid explicit
type checks may have to either use generic operations such as those described
in section
@href{Collection operations} or use two separate implementations, an efficient
one for Array objects that uses operations described in this
section, and a generic but less efficient one for objects of Array
subtypes or other sequence types.
Creating
@fun AValue AMakeArray(AThread *t, Assize_t len)
@desc Create a std::Array object of the specified length. The object
is initialized to contain nil values for all items.
@end
Reading and updating
@fun Assize_t AArrayLen(AValue v)
@desc Return the length of an array. The argument must be a std::Array
object, since this function performs no error checking. Subtypes of
Array are not supported.
@end
@fun AValue AArrayItem(AValue v, Assize_t index)
@desc Return the value of an item in an array. The first argument must be an
std::Array object, and the index (0-based) must be non-negative
and less than the length of the array. This function performs no
error checking. Subtypes of Array are not supported.
@end
@fun void ASetArrayItem(AThread *t, AValue v, Assize_t index, AValue item)
@desc Set the value of an item in an array. The second argument must be an
std::Array object, and the index (0-based) must be non-negative
and less than then length of the array. This function performs
no error checking of the argument values. Subtypes of Array
are not supported. Raise a direct exception if out of memory.
@end
@fun void AAppendArray(AThread *t, AValue v, AValue item)
@desc Append an item to the end of an array, increasing the length of the
array by one. The argument v must be std::Array object, since
this function performs no error checking. Subtypes of Array
are not supported either. Raise a direct exception if out of memory.
@end
@fun AValue ASubArray(AThread *t, AValue v, Assize_t i1, Assize_t i2)
@desc Return the subarray i1:i2 of an array. The rules for indices are
similar to when indexing subarrays in Alore code, and
negative indices are supported. As an exception, the constant
A_SLICE_END as the end index
specifies a subarray extending to the end of the array.
Subtypes of Array are not supported. @raise-direct
@end
Checking
@fun ABool AIsArray(AValue v)
@desc Return a boolean indicating whether the type of v is std::Array.
This operations returns false for objects belonging to a subtype of
Array. See also @ref{AIsArraySubType} described below.
@end
@fun void AExpectArray(AThread *t, AValue v)
@desc Check if the type of v is std::Array and raise a direct
@ref{std::TypeError} exception if it is not. The exception is raised
also for objects belonging to a subtype Array.
@end
@fun ABool AIsArraySubType(AValue v)
@desc Return a boolean indicating whether the type of v is std::Array
or a subtype of Array.
@end