There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

Name

SPVM::List - Dynamic Object Array

Usage

use List;

# Create an object list
my $list = List->new;
my $list = List->new([(object)Byte->new(1), Int->new(2), Long->new(3)]);

# Create a Int list
my $list = List->new([Int->new(1), Int->new(2), Int->new(3)]);

# Create an object list with length
my $list = List->new_len([], 3);

# Create a Int list with length
my $list = List->new_len(new Int[0], 3);

# Get list length
my $length = $list->length;

# Push object value
$list->push(Int->new(3));

# Pop object value.
my $element = $list->pop;

# Unshift object value.
$list->unshift(Int->new(3));

# Shift object value.
my $element = $list->shift;

# Set object value.
$list->set(2, Int->new(3));

# Get object value.
my $element = $list->get(2);

# Insert object value
$list->insert(1, Int->new(3));

# Remove object value
my $element = $list->remove(1);

# Convert List to object array.
my $int_array = $list->to_array;

# Convert List to Int array.
my $int_array = (Int[])$list->to_array;

Description

List class in SPVM is the dynamic object array that has a specified object array type.

Details

Internal Data Structure

The "array" stored in an IntList object always starts at index 0.

The elements in the range that is greater than or equal to "length" field and less than "capacity" field are filled with undef.

Interfaces

Fields

capacity

has capacity : virtual ro int;

The capacity. This is the length of the internally reserved elements to extend the length of the list.

length

has length : virtual ro int;

The length of the list.

Class Methods

new

static method new : List ($array : object[] = undef, $capacity : int = -1);

Creates a new List object using "new_len".

The passed length to "new_len" is the length of $array. If the array is undef, the length is 0.

The element's addresses of the object array are copied to the elements of the the created array.

# object[]
my $list = List->new([(object)Byte->new(1), Int->new(2), Long->new(3)]);

# Int[]
my $list = List->new([Int->new(1), Int->new(2), Int->new(3)]);

new_len

static method new_len : List ($proto_array : object[], $length : int, $capacity : int = -1);

Creates a new StringList object with $protot_array, $length and $capacity.

If $protot_array is undefined, $protot_array is set to an object[] object.

If $capacity is less than 0, $capacity is set to the default value.

If $length is greater than $capacity, $capacity is set to the length.

Exceptions:

$length must be greater than or equal to 0. Otherwise an exception is thrown.

Examples:

# Create a Int list with length
my $list = List->new_len(new Int[0], 3);

new_ref

static method new_ref : List ($array : object[]);

Creates a new List object, and set "array" field to the array $array, and return the new object.

Exceptions:

The array $array must be defined. Otherwise an exception is thrown.

Instance Methods

get

method get : element ($index : int);

Gets the element of the position of $index.

If $index is a netative value, $index is set to "length" plus $index.

Exceptions:

$index must be greater than or equal to 0. Otherwise an exception is thrown.

$index must be less than the length of $list. Otherwise an exception is thrown.

insert

method insert : void ($index : int, $element : object);

Inserts an $element to the position of $index.

Exceptions:

$index must be greater than or equal to 0. Otherwise an exception is thrown.

$index must be less than or equal to the length of $list. Otherwise an exception is thrown.

pop

method pop : element ();

Removes the last element and return it.

Exceptions:

The length of $list must be greater than 0. Otherwise an exception is thrown.

push

method push : void ($element : object);

Adds an $element after the end of the list.

remove

method remove : element ($index : int);

Removes the element at the position of $index and return it.

Exceptions:

$index must be greater than or equal to 0. Otherwise an exception is thrown.

$index must be less than the length of $list. Otherwise an exception is thrown.

replace

method replace : void ($offset : int, $remove_length : int, $replace : object[] = undef);

Same as "splice" method, but the return vlaue is not returned.

Exceptions:

Exceptions thrown by "splice" method could be thrown.

splice

method splice : object[] ($offset : int, $remove_length : int, $replace : object[] = undef);

Replaces the elements of the range specified by $offset and $length with $replace array, and returns removed elements creating a new array.

If $replace is not defined, the replacemnet is not performed.

Exceptions:

$offset must be greater than or equal to 0. Otherwise an exception is thrown.

$remove_length must be greater than or equal to 0. Otherwise an exception is thrown.

$offset + $removing length must be less than or equal to the length of $list. Otherwise an exception is thrown.

reserve

method reserve : void ($new_capacity : int);

If $new_capacity is greater than the capacity of the list, the capacity of the list is extended to $new_capacity.

resize

method resize : void ($new_length : int);

Resize the list with $new_length.

Exceptions:

$new_length must be greater than or equal to 0. Otherwise an exception is thrown.

set

method set : void ($index : int, $element : object);

Sets $element at the position of $index.

If $index is a netative value, $index is set to "length" plus $index.

Exceptions:

$index must be greater than or equal to 0. Otherwise an exception is thrown.

$index must be less than the length of $list. Otherwise an exception is thrown.

shift

method shift : element ();

Removes the first element and return it.

Exceptions:

The length of $list must be greater than 0. Otherwise an exception is thrown.

to_array

method to_array : object[] ();

Creates a new array and copies all elements of the list into the new array, and returns it.

unshift

method unshift : void ($element : object);

Inserts an $element at the beginning of the list.

clone

method clone : List ();

Clones this instance and returns it.

Each element is cloned by Cloneable#clone method if it is defined, otherwise undef is assigned.

push_

method push_ : void ($elements : object[]);

Adds the elements $elements after the end of this list.

This method calls "push" method internally.

Exceptions:

The elements $elements must be defined.

Exceptions thrown by "push" method could be thrown.

unshift_

method unshift_ : void ($elements : object[]);

Inserts the elemnets $elements at the beginning of the list.

Exceptions:

The elements $elements must be defined.

Exceptions thrown by "unshift" method could be thrown.

get_array_unsafe

method get_array_unsafe : object[] ();

Same as "get_array", but this method is deprecated.

get_array

method get_array : object[] ();

Returns the internal "array".

Copyright & License

Copyright (c) 2023 Yuki Kimoto

MIT License