Defined in Array.Def Inherits from Object Uses extra
The Magic Cap system uses objects of class Array to represent indexed runs of same-size elements. Class Array is most noted for its starring role as a parent class of the text formatter classes.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Class Array provides the fundamental behavior for classes that represent indexed collections of elements that are all the same size. You'll rarely instantiate any objects of class Array; instead, you'll instantiate and use objects created from Array's concrete subclasses.
Instantiate: never Subclass: rarely Call its methods: sometimes
Class Array defines objects that consist of ordered, indexed runs of same-size elements. Other classes that require this ability, such as TextFormatter, are built on class Array. Class Array defines methods for reading and changing the array elements.
Class Array defines the following methods:
| Method | Description |
|---|---|
| Manipulating the whole array: | |
| Clear | Set the array length to zero, thus removing all elements |
| DeleteElems | Set the array length to zero, thus removing all elements; yes, this is exactly the same as Clear |
| CopyElems | Return a copy of the entire array |
| ReplaceElems | Replace the entire array with the given array |
| ReplaceElemsWithData | Replace the entire array with the given data |
| Manipulating ranges of the array: | |
| DeleteElemRange | Delete the given range from the array |
| CopyElemRange | Return an array containing a copy of the given range |
| ReplaceElemRange | Replace a range of elements with other object |
| ReplaceElemData | Replace a range with elements from memory |
| FillWithBytes | Fill a range of the array with a pattern of bytes |
| CopyToBytes | Copy elements from the object to memory |
| Manipulating one point in the array: | |
| AppendElems | Append the given elements to the end of the array |
| InsertElems | Insert the given elements into the array at insertPoint |
| InsertElems | Append the given amount of the given data to the end of the array |
| InsertData | Insert the given amount of the given data to the array at insertPoint |
Class Array defines the following fields:
| Field | Type | Description |
|---|---|---|
| length | Unsigned | Number of bytes of data in array |
Class Array defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| ArrayLength | Unsigned | Number of elements in the array; getter and setter for the lenth field |
| ArrayCapacity | Unsigned | The maximum number of elements the array can contain |
| Stride | Unsigned | The size of one array element in bytes; returns 1 by default |
When you want to operate on an array object, you'll find that many Array class routines use the concept of an array point, which is a position between two elements. The array point before the first element is numbered 0, the position between the first and second elements is numbered 1, and so on. The array point type is defined as follows:
typedef ulong ArrayPoint;
Class Array defines several methods that require you to specify a range of elements in the object. There's a data type for a range of elements, defined as follows:
typedef struct
{
ArrayPoint start; /* starting point for range */
ulong length; /* number of elements in range */
} ArrayRange;
operation Clear(), noFail, safe; operation DeleteElems(); Call: rarely Override: rarely
Call Clear to remove all elements from an array. Call DeleteElems to do the same. Both methods just set the array's length to zero using SetArrayLength. Parsimonious programmers will want to conserve memory by deleting unwanted array elements. You could so so by overriding DeleteElems.
operation CopyElems(): Array, noFail, safe; Call: rarely Override: rarely
Call CopyElems to get a new array that contains copies of all the elements of the current array. CopyElems returns the new array. It uses CopyElemRange to do the copying.
operation ReplaceElems(elemsToInsert: Array); Call: rarely Override: rarely
Call ReplaceElems to replace the entire contents of an array with the contents of the array in the elemsToInsert parameter. To do its work, ReplaceElems calls ReplaceElemRange with a range that covers the entire array.
operation ReplaceElemsWithData(data: Pointer; numberOfElems: Unsigned); Call: rarely Override: rarely
Call ReplaceElemsWithData to replace the entire contents of an array with data that isn't already in an array. The data parameter should point to the data you want to replace the current array elements. The numberOfElems parameter should contain the number of elements you wish to use. ReplaceElemsWithData calls ReplaceElemData to do its work.
operation DeleteElemRange(rangeToDelete: ArrayRange) Call: rarely Override: rarely
Call DeleteElemRange when you want to set a range of elements in the object to 0. Before you call DeleteElemRange, set rangeToDelete to indicate the range of elements that should be set to 0. DeleteElemRange calls ReplaceElemData to perform its action.
operation CopyElemRange(rangeToCopy: ArrayRange): Object; noFail Call: rarely Override: rarely
Call CopyElemRange when you want to create a new Array object that contains some or all of the elements that are in the object. The range of elements to copy is specified by rangeToCopy. CopyElemRange calls New to create a new object, then copies elements from the specified range into the new object using CopyToBytes. The new object is returned as the function result.
operation ReplaceElemRange(rangeToReplace: ArrayRange; elemsToInsert: Object) Call: sometimes Override: rarely
Call ReplaceElemRange when you want to replace a range of elements in the object with all the elements of another object. The elements to be added come from elemsToInsert, and they replace the elements in the object at the range specified by rangeToReplace. The elements that were at rangeToReplace in the object are lost. Replace calls ReplaceElemData to perform its action.
operation ReplaceElemData(rangeToReplace: ArrayRange; data: Pointer; count: Unsigned) Call: sometimes Override: rarely
Call ReplaceElemData to move data into the array from somewhere else in memory. The data parameter points to the bytes to be moved into the array, and count specifies how many elements to move. The moved elements take the place of the elements specified by rangeToReplace, and the old elements at that location are lost.
operation FillWithBytes(source: Pointer; numberOfBytes: Unsigned; fillRange: ArrayRange) Call: sometimes Override: rarely
Call FillWithBytes when you want to fill a specified range in the object with a pattern of bytes. The source pointer is the address of the first byte to be inserted. The numberOfBytes parameter indicates the length of the pattern of bytes. The fillRange parameter gives the range in the object to be filled.
If there are more bytes to be inserted than will fit in fillRange, bytes of the pattern are used until the range is filled. If the range to be filled is larger than the pattern, the pattern is repeated until the range is filled.
operation CopyToBytes(copyRange: ArrayRange; copyTo: Pointer); noFail Call: sometimes Override: rarely
Call CopyToBytes to copy a range of elements from the object to a location in memory. The elements are copied from copyRange to the location that copyTo points to. The copyRange parameter specifies both the starting element and the number of elements to copy.
operation AppendElems(elemsToAppend: Object) Call: rarely Override: rarely
Call AppendElems to add all the elements of another object to the end of the object. The elements to be appended are in elemsToAppend, and they are added to the object following its last element. AppendElems calls ReplaceElemRange to perform its action.
operation InsertElems(insertPoint: ArrayPoint; elemsToInsert: Object) Call: rarely Override: rarely
Call InsertElems to insert all the elements of another object into the object. The elements to be inserted are in elemsToInsert, and they are inserted into the object at insertPoint. InsertElems calls ReplaceElemRange to perform its action.
operation AppendData(data: Pointer; numberOfElems: Unsigned) Call: rarely Override: rarely
Call AppendData when you want to add a run of elements of any length onto the end of the object. The data parameter points to the start of the elements to be added, and numberOfElems indicates how many elements to add. AppendData calls ReplaceElemData to perform its action.
operation InsertData(insertPoint: ArrayPoint; data: Pointer; numberOfElems: Unsigned;) Call: rarely Override: rarely
Call InsertData when you want to insert some or all of a run of data elements into the object. The data parameter points to the first element to be inserted, and numberOfElems specifies how many elements to insert. The elements are inserted into the object at insertPoint. InsertData calls ReplaceElemData to perform its action.
overrides Compact Call: rarely Override: rarely
Call Compact to reduce the size of the array by making it just large enough to hold all its elements. Compact performs this action by calling SetArrayCapacity.
attribute ArrayLength: Unsigned // operation ArrayLength: Unsigned // operation SetArrayLength (newArrayLength: Unsigned) Call: sometimes Override: rarely
Call ArrayLength when you want to find out the number of elements that the array holds. ArrayLength returns the value that's in the object's logicalLength field.
Call SetArrayLength when you want to set the array's length to a new value. SetArrayLength makes the array large enough to hold newNumberOfElems elements.
attribute ArrayCapacity: Unsigned // operation ArrayCapacity: Unsigned // operation SetArrayCapacity(newArrayCapacity: Unsigned) Call: rarely Override: rarely
Call ArrayCapacity when you want to find out the number of elements that the array can hold. ArrayCapacity computes the number of bytes that are being used for array elements, then divides by the size of a single element.
Call SetArrayCapacity when you want to set the array's capacity to a new value. SetCapacity makes the array large enough to hold newNumberOfSlots elements.
overrides Validate Call: rarely Override: sometimes
Array_Validate checks for the following conditions:
Validate writes a debugging message if it discovers any of these conditions. After checking these conditions, Validate calls its inherited implementation.
You should override Validate if you want objects of your class to perform any additional validity checking. See Object_Validate for more information.