Array-of

Parameterized class for one-dimensional arrays.

t: is the data type of the elements in the array.

Description

There are a number of collection types built into Curl, including:

Arrays
Hash tables
Sets
Strings
Arguments

Array-of allows you to create one-dimensional, growable arrays. The ordered collection classes that are built into Curl, like Array-of, inherit from Sequence-of. The elements in such collections are indexed by a contiguous set of integers, starting at 0.

Notes

A partial hierarchy of the collection classes in Curl follows:

Aggregate-of
∟ Association-of
∟ HashTable-of
∟ Sequence-of
∟ Array-of
∟ Array-2-of
∟ Set-of
FastArray-of

For more information about collections in Curl, see Curl Developer's Guide: Collections.

Notes

If the contents of a collection change while you are iterating over that collection, the results are undefined.

Notes

Arrays grow by roughly doubling the size of their underlying FastArray-of each time it fills up. This requires allocating a new, larger FastArray-of and copying all the old elements into it.

To waste less space for very large arrays, once the array reaches a certain size (currently 1MB), the growth factor is reduced so it only doubles every four times it fills up.

This algorithm is subject to change in future releases. More precise control over representation size can be achieved using Array-of.efficient-size.

Initialize a one-dimensional array of elements.

from: The initial contents of self are copied from from.

Initialize a one-dimensional array of elements.

efficient-size: is the suggested maximum size of the FastArray-of that internally represents the array. This value is ultimately adjusted based on the type of the Array and certain other internal semantics. It is guaranteed to be adjusted upward, if changed at all. If you do not specify the efficient-size and there are elements, the efficient-size is set to an appropriate value based on the number of rest arguments. If you do not specify efficient-size and there are no elements, the efficient-size is set to some small value. (This value was chosen based on "typical" usage patterns.)

...: the rest arguments specify the initial elements in the array. The rest arguments are inserted into the array from left-to-right, with the leftmost argument inserted at index 0.

Example

The following code creates an instance of an array with no initial elements.

{let my-array:{Array-of String} = {new {Array-of String}}}

The following code creates an instance of an array with three initial elements.

{let my-array:{Array-of String} =
    {new {Array-of String}, "apple", "banana", "cherry"}}

Initialize a one-dimensional array of elements.

underlying-FastArray: The FastArray-of that internally represents the array.

Initialize a one-dimensional array of elements.

size: indicates the initial size of the FastArray-of that internally represents the array.

initial-value: is the default value to use for the initial value of all of the array elements.

efficient-size: is a hint for how many items are expected to go into the array. This parameter is used to choose an initial size of the FastArray-of that internally represents the array. This value is adjusted based on the type of self and certain other internal factors. It is guaranteed to be adjusted upward, if changed at all. If you do not specify efficient-size and there are elements, the efficient-size is set to a size that is optimized for the data type of the elements and the platform running the code.

This item is unsupported and reserved for internal use.

Gets or sets the efficient-size of self

Description

This is an implementation of the efficient-size semantics as defined in Association-of.efficient-size.

Supports iteration using for loops. Not intended for direct use.

Description

A getter that the Curl compiler uses when it encounters a container for loop that iterates over self.

Gets the size of (i.e. number of elements in) self.

The underlying FastArray-of that holds the data, but which is replaced if the array is resized beyond the limits of the FastArray-of.

Appends e to the end of self.

e: is the element to be appended.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Append an element to the end of the array.
    {my-array.append "Sally"}

    || Use a VBox to display the contents of price.
    || Add each element to the VBox, then display
    || the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

Notes

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Deletes all elements from self.

Example

{value
    || Declare and initialize my-array (an array
    || of String).
    let my-array:{Array-of String} =
        {new {Array-of String}, "apple", "banana", "cherry"}

    || Clear the array.
    {my-array.clear}

    || Check if the array is empty.
    {text The array is empty is...
        {value my-array.empty?}}
}

Returns a clone of self.

Returns

An instance of a subclass of Sequence-of. The object returned is of the same type as self.

Description

A clone is a new object with the same data type as self, containing the same elements (identically), in the same order, as self does.

Example

{value
    || Declare and initialize array-1 (the
    || original array).
    let array-1:{Array-of String} =
        {new {Array-of String}, "apple", "banana", "cherry"}

    || Initialize array-2 with a clone of the
    || contents of array-1.
    let array-2:{Array-of String} = {array-1.clone}

    || Use a VBox to display the contents of array-2.
    || Iterate over the contents of array-2, adding
    || them to the VBox.  Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in array-2 do
        {message.add each-element}
    }
    message
}

Notes

For a detailed description of cloning, see the section on cloning for the collection that you are using in Curl Developer's Guide: Collections.

Constructs a new Sequence from self, using the length elements starting at start.

start: is the index of the first element to be copied into the new Sequence.

length: is the number of elements to copy.

Example

{value
    || Declare and initialize array-1 (the
    || original array).
    let array-1:{Array-of String} =
        {new {Array-of String}, "apple", "banana", "cherry", "plum"}

    || Declare and initialize array-2 with a clone of the
    || two elements starting at index 1 of array-1.
    let array-2:{Array-of String} = {array-1.clone-range 1, 2}

    || Use a VBox to display the contents of array-2.
    || Iterate over the contents of array-2, adding
    || them to the VBox.  Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in array-2 do
        {message.add each-element}
    }
    message
}

Notes

If any part of the specified range is out of bounds, this method throws a KeyNotFoundException.

For a detailed description of cloning, see the section on cloning for the collection that you are using in Curl Developer's Guide: Collections.

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Concatenates s1 to the end of self.

s1: is the Sequence of elements to be concatenated.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Declare and initialize another array with
    || String elements.
    let your-array:{Array-of String} =
        {new {Array-of String}, "Mary", "Sally"}

    || Concatenate the elements of your-array onto
    || the end of my-array.
    {my-array.concat your-array}

    || Use a VBox to display the contents of my-array.
    || For each key in my-array, add an HBox to the VBox.
    || The HBox contains the relevant key and element.
    || Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

Notes

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Compares its argument with self for structural equality.

s2: the object with which self is to be compared

Returns

A bool indicating whether self and s2 are equal. This method returns true when self and s2 are structurally equal and false when they are not.

Description

Compares self with s2. If both collections have the same number of elements and each element of self is == the corresponding element of s2, the collections are deemed to be structurally equal, and true is returned.

Example

|| Declare and initialize array-1 (an array
|| of String) with three elements.
{let array-1:{Array-of String} =
    {new {Array-of String}, "apple", "banana", "cherry"}
}

|| Declare and initialize array-2 (an array
|| of String) with two elements.
{let array-2:{Array-of String} =
    {new {Array-of String}, "apple", "banana"}
}

|| Determine if the arrays are equal.
The arrays are equal is...  {array-1.equal? array-2}

|| Add an element to array-2.
{array-2.append "cherry"}

|| And test the arrays for equality again.
After the append operation, the arrays are equal is...
{array-1.equal? array-2}

Returns a clone of self, with elements filtered out.

p: determines whether a given element is to be filtered or not. This method calls p on each element in self. If p returns false, this method does not include that element in the clone. If p returns true, the element is included in the clone.

Returns

An instance of a subclass of Sequence-of. The object returned is of the same type as self. It contains a clone of self, with some elements filtered out.

Example

The following example creates a clone of an array, with all elements that begin with the letter a filtered out.

Example

{value
    || Declare and initialize array-1 (an array
    || of String).
    let array-1:{Array-of String} =
        {new {Array-of String}, "apple", "banana", "cherry"}

    || Create a clone array-2 that contains the elements
    || of array-1 with strings that begin with the letter
    || 'a' filtered out.
    let array-2:{Array-of String} =
        {array-1.filter-clone
            {proc {str:String}:bool
                {return str[0] != 'a'}
            }
        }

    || Use a VBox to display the contents of array-2.
    || Iterate over the contents of array-2, adding them
    || to the VBox.  Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in array-2 do
        {message.add each-element}
    }
    message
}

Notes

For a detailed description of cloning, see the section on cloning for the collection that you are using in Curl Developer's Guide: Collections.

Returns a clone of self, with elements filtered out, based on their keys (indices).

p: determines whether a given element is to be filtered or not. This method calls p on the key (index) for each element in self. If p returns false, this method does not include the element in the clone. If p returns true, the element is included in the clone.

Returns

An instance of a subclass of Sequence-of. The object returned is of the same type as self. It contains a clone of self, with some elements filtered out.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Create a clone that contains the elements of the
    || original, except that elements with even keys are
    || filtered out.
    let new-array:{Array-of String} =
        {my-array.filter-keys-clone
            {proc {index:int}:bool
                {return (index mod 2) == 0}
            }
        }

    || Use a VBox to display the contents of new-array.
    || Add each element to the VBox, then display
    || the VBox.
    let message:VBox = {VBox}
    {for each-element:String in new-array do
        {message.add each-element}
    }
    message
}

Notes

For a detailed description of cloning, see the section on cloning for the collection that you are using in Curl Developer's Guide: Collections.

Returns a specific element.

index: indicates the index of the element to be retrieved.

Returns

The retrieved element. The return value is of type self.element-type.

Example

|| Declare and initialize an array with String
|| elements.
{let my-array:{Array-of String} =
    {new {Array-of String},
        "apple",
        "banana",
        "cherry"
    }
}

|| Display the element at index 2.
{my-array.get 2}

Notes

If index is out of bounds, this method throws an ArrayBoundsException

You can use an array access expression to perform identical functionality. For example:

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String},
            "apple",
            "banana",
            "cherry"
        }

    || Display the element at index 2.
    my-array[2]
}

Returns a specific element, along with a bool that signifies whether the indicated element was found.

index: indicates the index of the element to be retrieved.

Returns

The retrieved element, if found. When an element was found, this return value is of type self.element-type.

The second value returned indicates whether index is valid.

If index is not valid, the first return value is undefined.

Notes

This is an abstract method of Association-of; it is implemented in subclasses of Association-of.

Indicates whether its argument is a valid index in self.

index: specifies the index to be tested.

Returns

This method returns true if index is a valid index in self, else false.

Description

Returns true if index is between 0 and self.size - 1.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Check if there is an element at index 3.
    || Remember that the first element in an array
    || is at index 0.
    {if {my-array.in-bounds? 3} then
        {text It is there!}
     else
        {text It is not there.}
    }
}

Notes

This method provides the same functionality as Sequence-of.key-exists?.

Inserts e into self immediately before the position designated by index.

e: is the element to be inserted.

index: specifies where e is to be inserted. After insertion, e's index is index.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Insert an element at position 1.  Subsequent
    || elements are shifted one position to the right.
    {my-array.insert "Mary", 1}

    || Insert an element at position 4.
    {my-array.insert "Sally", 4}

    || Use a VBox to display the contents of price.
    || Add each element to the VBox, then display
    || the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

Notes

If index is out of range, this method throws an KeyNotFoundException.

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Called by the serialization code when a class instance is to be written.

out: The SerializeOutputStream that called this method.

Description

This method must do the following steps, in order:

It must call SerializeOutputStream.write-class-version, normally with an argument of zero.
It must call super.object-serialize for each serializable superclass.
It must write its serialized state to out. This is normally done by calling SerializeOutputStream.write-one for each field.

Notes

This method should only be defined by serializable subclasses.

Removes and returns an element from the end of self.

Description

Popping an element is an operation that is usually performed with Last-In, First-Out (LIFO) stacks. This method removes the last element in self, returning it. (The element at the end of self is the element at index size - 1.)

See also Sequence-of.push and Sequence-of.top-of-stack.

Example

Example: Pop an Element from a Stack

|| Declare and initialize an array with String
|| elements.
{let my-array:{Array-of String} =
    {new {Array-of String}, "Tom", "Dick", "Harry"}}

|| Pop an element from the array.
{text The return value of a pop operation is...}
{my-array.pop}

|| Use a VBox to display the contents of my-array.
|| Add each element to the VBox, then embed the
|| VBox within another for display.
{let message:VBox = {VBox}}
{for each-element:String in my-array do
    {message.add each-element}
}
{VBox
    {text After the pop operation, the array has the
        following elements...},
    {value message}
}

Notes

If self.size is 0, i.e. if the sequence is empty, this method throws a KeyNotFoundException.

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Pushes e onto the end of self.

e: is the element to be pushed.

Description

Pushing an element is an operation that is usually performed with Last-In, First-Out (LIFO) stacks. When you push an element onto a stack, you add it to the end of the stack. When you call this method, e is appended to the end of self.

See also Sequence-of.pop and Sequence-of.top-of-stack.

Example

Example: Push an Element onto a Stack

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Append an element to the end of the array.
    {my-array.push "Sally"}

    || Use a VBox to display the contents of my-array.
    || Add each element to the VBox, then display
    || the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

Notes

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Removes one or more successive elements from self.

index: specifies the index of the (first) element to remove.

length: specifies the number of successive elements to remove (defaults to 1).

error-if-missing?: indicates whether this method should throw an ArrayBoundsException if asked to remove an element that does not exist (defaults to true).

Description

If {self.key-exists? i} is true for every i from index to index + length - 1, this method removes the appropriate element from self.

If {self.key-exists? i} is false for any i in the specified range and error-if-missing? is true, this method throws a ArrayBoundsException.

If error-if-missing? is false, this method removes all specified elements i for which {self.key-exists? i} is true, doing nothing for any others.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String},
            "apple",
            "banana",
            "cherry"
        }

    || Remove the element at index 1.
    {my-array.remove 1}

    || Use a VBox to display the contents of my-array.
    || For each element in my-array, add a string to the
    || VBox.  Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

Reverses the order of the elements in self.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Reverse the order of the elements.
    {my-array.reverse}

    || Use a VBox to display the contents of price.
    || Add each element to the VBox, then display
    || the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

Notes

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Sets the element for a given index.

index: indicates index of the element to be set.

element: is the value of the element to be set. The type of this parameter is self.element-type.

Description

If key is in bounds, this method changes the value of the associated element to element.

If key is not in bounds, this method throws an ArrayBoundsException.

Example

|| Declare and initialize a hash table with
|| String keys and int elements.
|| Declare and initialize an array with String
|| elements.
{let my-array:{Array-of String} =
    {new {Array-of String},
        "apple",
        "banana",
        "cherry"
    }
}

|| Set the element at index 1 to "plum".
{my-array.set 1, "plum"}

|| Use a VBox to display the contents of my-array.
|| For each element in my-array, add an HBox to the
|| VBox.  The HBox contains the relevant index and
|| element.  Then display the VBox.
{let message:VBox = {VBox}}
{for key each-element:int in my-array do
    {message.add {HBox each-element, " ", {my-array.get each-element}}}
}
{value message}

Notes

You can use the set expression and an array access expression to perform similar functionality. For example:

Example

|| Declare and initialize an array with String
|| elements.
{let my-array:{Array-of String} =
    {new {Array-of String},
        "apple",
        "banana",
        "cherry"
    }
}

|| Set the element at index 1 to "plum".
{set my-array[1] = "plum"}

|| Use a VBox to display the contents of my-array.
|| For each element in my-array, add an HBox to the
|| VBox.  The HBox contains the relevant index and
|| element.  Then display the VBox.
{let message:VBox = {VBox}}
{for key each-element:int in my-array do
    {message.add {HBox each-element, " ", {my-array.get each-element}}}
}
{value message}

Sets the size of self.

new-size: indicates the new size for self. If this parameter is negative, this method throws an ArrayBoundsException.

new-val: designates a value to fill newly created slots with, if new-size is greater than the current value of self.size.

Notes

If new-size < 0, this method throws an ArrayBoundsException.

Sorts the elements of self. The sorting algorithm employed is stable; i.e., it does not change the relative order of equal elements.

comparison-proc: compares the elements for the purpose of the sort. This procedure returns true when applied to two elements in self if the two elements are already in the proper order.

When this parameter is not supplied, the system attempts to choose a default which sorts the elements into ascending order.

Example

The following example sorts an {Array-of String} into ascending order (the default).

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Sort the elements.
    {my-array.sort}

    || Use a VBox to display the contents of price.
    || Add each element to the VBox, then display
    || the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

The following example sorts an {Array-of int} into descending order.

Example

{value
    || Declare and initialize an array with int
    || elements.
    let my-array:{Array-of int} =
        {new {Array-of int}, 7, 69, 13, 33, 22}

    || Sort the elements into descending order.
    {my-array.sort comparison-proc =
        {proc {x:int, y:int}:bool
            {return x > y}
        }
    }

    || Use a VBox to display the contents of my-array.
    || Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:int in my-array do
        {message.add each-element}
    }
    message
}

Notes

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Splices s1 into self immediately before the position designated by index.

s1: is the Sequence of elements to be spliced in.

index: specifies where the first element of s1 is to be inserted. After insertion, the index of first element of s1 is index; the other elements of s1 are inserted sequentially.

Example

{value
    || Declare and initialize an array with String
    || elements.
    let my-array:{Array-of String} =
        {new {Array-of String}, "Tom", "Dick", "Harry"}

    || Declare and initialize another array with
    || String elements.
    let your-array:{Array-of String} =
        {new {Array-of String}, "Mary", "Sally"}

    || Insert the elements of your-array into my-array
    || at index 1.  Subsequent elements of my-array
    || are shifted to the right.
    {my-array.splice your-array, 1}

    || Use a VBox to display the contents of my-array.
    || For each key in my-array, add an HBox to the VBox.
    || The HBox contains the relevant key and element.
    || Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-array do
        {message.add each-element}
    }
    message
}

Notes

If index is out of range, this method throws an KeyNotFoundException.

This is an abstract method of Sequence-of; it is implemented in subclasses of Sequence-of.

Returns the element at the top of self, viewed as a stack, without modifying self. This is the last element of the sequence.

Returns

The element at the "top" of the sequence.

Description

Returning the value at the top of a collection is usually performed with Last-In, First-Out (LIFO) stacks. This method returns the last element in self

Calling this method should not change the contents of self. However, the default implementation invokes pop followed by push which will temporarily change the state. Most subclasses, including Array-of, override this method to avoid this issue.

See also Sequence-of.push and Sequence-of.pop.

Example

Example: Get the Top Element on a Stack

|| Declare and initialize an array with String
|| elements.
{let my-array:{Array-of String} =
    {new {Array-of String}, "Tom", "Dick", "Harry"}
}

|| View the top of the stack.
{text The return value of a top-of-stack operation is...}
{my-array.top-of-stack}

|| Use a VBox to display the contents of my-array.
|| Add each element to the VBox, then embed the
|| VBox within another for display.
{let message:VBox = {VBox}}
{for each-element:String in my-array do
    {message.add each-element}
}
{VBox
    {text After the top-of-stack operation, the array has
        the following elements...},
    {value message}
}

Notes

If self.size is 0, i.e. if the sequence is empty, this method throws a KeyNotFoundException.