Name
SPVM::Array - Array Utilities
Usage
use Array;
# Copy a byte array
{
my $array = [(byte)1, 2, 3];
my $array_copy = Array->copy_byte($array);
}
# Copy a short array
{
my $array = [(short)1, 2, 3];
my $array_copy = Array->copy_short($array);
}
# Copy a int array
{
my $array = [1, 2, 3];
my $array_copy = Array->copy_int($array);
}
# Copy a long array
{
my $array = [(long)1, 2, 3];
my $array_copy = Array->copy_long($array);
}
# Copy a float array
{
my $array = [1.5f, 2.5f, 3.5f];
my $array_copy = Array->copy_float($array);
}
# Copy a double array
{
my $array = [1.5, 2.5, 3.5];
my $array_copy = Array->copy_double($array);
}
# Copy a string array
{
my $array = ["abc", "def", "ghi"]
my $array_copy = Array->copy_string($array);
}
# Check if the two byte arrays equal
{
my $array1 = [(byte)1, 2];
my $array2 = [(byte)1, 2];
my $ret = Array->equals_byte($array1, $array2);
}
# Check if the two short arrays equal
{
my $array1 = [(short)1, 2];
my $array2 = [(short)1, 2];
my $ret = Array->equals_short($array1, $array2);
}
# Check if the two int arrays equal
{
my $array1 = [(int)1, 2];
my $array2 = [(int)1, 2];
my $ret = Array->equals_int($array1, $array2);
}
# Check if the two long arrays equal
{
my $array1 = [(long)1, 2];
my $array2 = [(long)1, 2];
my $ret = Array->equals_long($array1, $array2);
}
# Check if the two float arrays equal
{
my $array1 = [(float)1, 2];
my $array2 = [(float)1, 2];
my $ret = Array->equals_float($array1, $array2);
}
# Check if the two double arrays equal
{
my $array1 = [(double)1, 2];
my $array2 = [(double)1, 2];
my $ret = Array->equals_double($array1, $array2);
}
# Check if the two string arrays equal
{
my $array1 = ["abc", "def"];
my $array2 = ["abc", "def"];
my $ret = Array->equals_string($array1, $array2);
}
# Copy object array
my $array = [(object)Int->new(1), Int->new(2), Int->new(3)];
my $array_copy = Array->copy_object($array, method : object ($obj : object) {
my $int_obj = (Int)$obj;
my $new_int_obj = Int->new($int_obj->value);
return $new_int_obj;
});Description
Array provides array utilities.
Class Methods
copy_byte
static method copy_byte : byte[] ($array : byte[], $offset = 0 : int, $length = -1 : int)Create a new byte array with the length sepcified by the argument, and copy the elements from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
copy_double
static method copy_double : double[] ($array : double[], $offset = 0 : int, $length = -1 : int)Create a new double array with the length sepcified by the argument, and copy the elements from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
If the array is not defined, return undef.
copy_float
static method copy_float : float[] ($array : float[], $offset = 0 : int, $length = -1 : int)Create a new float array with the length sepcified by the argument, and copy the elements from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
copy_int
static method copy_int : int[] ($array : int[], $offset = 0 : int, $length = -1 : int)Create a new int array with the length sepcified by the argument, and copy the elements from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
copy_long
static method copy_long : long[] ($array : long[], $offset = 0 : int, $length = -1 : int)Create a new long array with the length sepcified by the argument, and copy the elements from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
copy_object
static method copy_object : object[] ($array : object[], $cloner = undef : Cloner, $offset = 0 : int, $legnth = -1 : int)Create a new object array with the length sepcified by the argument, and clone the elements of the object array from the offset to the position proceeded by the length to the created array.
Each element is cloned by the Cloner.
If the cloner is not defined, the address of each element is copied.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
copy_object_address
static method copy_object_address : object[] ($array : object[], $offset = 0 : int, $legnth = -1 : int);The alias for the following code using "copy_object".
my $ret = ©_object($array, undef, $offset, $length);copy_short
static method copy_short : short[] ($array : short[], $offset = 0 : int, $length = -1 : int)Create a new short array with the length sepcified by the argument, and copy the elements from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
copy_string
static method copy_string : string[] ($array : string[], $offset = 0 : int, $length = -1 : int)Create a new string array with the length sepcified by the argument, and copy the elements of the string array using copy operator from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
copy_string_address
static method copy_string_address : string[] ($array : string[], $offset = 0 : int, $length = -1 : int)Create a new string array with the length sepcified by the argument, and copy the addresses of the elements of the string array from the offset to the position proceeded by the length to the created array.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will be thrown.
The offset must be greater than or equal to 0. Otherwise an exception will be thrown.
The offset + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will be thrown.
dump_unsigned_byte
static method dump_unsigned_byte : string ($array : byte[])Same as the following code using the dump operator operator, but the elements are displayed as unsigned 8-bit integer.
my $ret = dump $array;dump_unsigned_int
static method dump_unsigned_int : string ($array : int[])Same as the following code using the dump operator operator, but the elements are displayed as unsigned 32-bit integer.
my $ret = dump $array;dump_unsigned_long
static method dump_unsigned_long : string ($array : long[])Same as the following code using the dump operator operator, but the elements are displayed as unsigned 64-bit integer.
my $ret = dump $array;dump_unsigned_short
static method dump_unsigned_short : string ($array : short[])Same as the following code using the dump operator operator, but the elements are displayed as unsigned 16-bit integer.
my $ret = dump $array;equals_byte
static method equals_byte : int ($array1 : byte[], $array2 : byte[])If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2, return 1.
Otherwise return 0.
equals_double
static method equals_double : int ($array1 : double[], $array2 : double[])If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2, return 1.
Otherwise return 0.
equals_float
static method equals_float : int ($array1 : float[], $array2 : float[])If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2, return 1.
Otherwise return 0.
equals_int
static method equals_int : int ($array1 : int[], $array2 : int[])If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2, return 1.
Otherwise return 0.
equals_long
static method equals_long : int ($array1 : long[], $array2 : long[])If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2, return 1.
Otherwise return 0.
equals_object
static method static method equals_object : int ($objs1 : object[], $objs2 : object[], $equality_checker : EqualityChecker)If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2 using the equality checker, return 1.
The equality checker is not defined, the address is used to check the equality.
Otherwise return 0.
equals_object_address
static method equals_object_address : int ($array1 : object[], $array2 : object[])The alias for the following code using "equals_object".
my $ret = &equals_object($array1, $array2, undef);equals_short
static method equals_short : int ($array1 : short[], $array2 : short[])If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2, return 1.
Otherwise return 0.
equals_string
static method equals_string : int ($array1 : string[], $array2 : string[])If the array 1 is not defined and the array 2 is not defined, return 1.
If the array 1 is defined and the array 2 is not defined, return 0.
If the array 1 is not defined, the array 2 is defined, return 0.
If the array 1 is defined and the array 2 is defined and the all elements of array 1 are equal to all elements of array 2 using the eq operator, return 1.
Otherwise return 0.
equals_string_address
static method equals_string_address : int ($array1 : string[], $array2 : string[])The alias for the following code using "equals_object_address".
my $ret = &equals_object_address($array1, $array2);memcpy_byte
static method memcpy_byte : void ($dest : byte[], $dest_offset : int, $source : byte[], $source_offset : int, $length : int)Copy the range of the elements of the source byte array to the range of the elements of the destination byte array.
The range of the elements of the source array is from the offset to the position proceeded by the length of the source.
The range of the elements of the destination array is from the offset of the destination to the offset of the destination + the length specified by the argument.
If the range of the elements of the source array and the range of the elements of the destination array overlap, the result is not guaranteed.
The destination must be defined. Otherwise an exception will occur.
The source must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the source must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination + the length specified by the argument must be less than or equal to the length of the destination. Otherwise an exception will occur.
The offset of the source + the length specified by the argument must be less than or equal to the length of the source. Otherwise an exception will occur.
memcpy_double
static method memcpy_double : void ($dest : double[], $dest_offset : int, $source : double[], $source_offset : int, $length : int)Copy the range of the elements of the source double array to the range of the elements of the destination double array.
The range of the elements of the source array is from the offset to the position proceeded by the length of the source.
The range of the elements of the destination array is from the offset of the destination to the offset of the destination + the length specified by the argument.
If the range of the elements of the source array and the range of the elements of the destination array overlap, the result is not guaranteed.
The destination must be defined. Otherwise an exception will occur.
The source must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the source must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination + the length specified by the argument must be less than or equal to the length of the destination. Otherwise an exception will occur.
The offset of the source + the length specified by the argument must be less than or equal to the length of the source. Otherwise an exception will occur.
memcpy_float
static method memcpy_float : void ($dest : float[], $dest_offset : int, $source : float[], $source_offset : int, $length : int)Copy the range of the elements of the source float array to the range of the elements of the destination float array.
The range of the elements of the source array is from the offset to the position proceeded by the length of the source.
The range of the elements of the destination array is from the offset of the destination to the offset of the destination + the length specified by the argument.
If the range of the elements of the source array and the range of the elements of the destination array overlap, the result is not guaranteed.
The destination must be defined. Otherwise an exception will occur.
The source must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the source must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination + the length specified by the argument must be less than or equal to the length of the destination. Otherwise an exception will occur.
The offset of the source + the length specified by the argument must be less than or equal to the length of the source. Otherwise an exception will occur.
memcpy_int
static method memcpy_int : void ($dest : int[], $dest_offset : int, $source : int[], $source_offset : int, $length : int)Copy the range of the elements of the source int array to the range of the elements of the destination int array.
The range of the elements of the source array is from the offset to the position proceeded by the length of the source.
The range of the elements of the destination array is from the offset of the destination to the offset of the destination + the length specified by the argument.
If the range of the elements of the source array and the range of the elements of the destination array overlap, the result is not guaranteed.
The destination must be defined. Otherwise an exception will occur.
The source must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the source must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination + the length specified by the argument must be less than or equal to the length of the destination. Otherwise an exception will occur.
The offset of the source + the length specified by the argument must be less than or equal to the length of the source. Otherwise an exception will occur.
memcpy_long
static method memcpy_long : void ($dest : long[], $dest_offset : int, $source : long[], $source_offset : int, $length : int)Copy the range of the elements of the source long array to the range of the elements of the destination long array.
The range of the elements of the source array is from the offset to the position proceeded by the length of the source.
The range of the elements of the destination array is from the offset of the destination to the offset of the destination + the length specified by the argument.
If the range of the elements of the source array and the range of the elements of the destination array overlap, the result is not guaranteed.
The destination must be defined. Otherwise an exception will occur.
The source must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the source must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination + the length specified by the argument must be less than or equal to the length of the destination. Otherwise an exception will occur.
The offset of the source + the length specified by the argument must be less than or equal to the length of the source. Otherwise an exception will occur.
memcpy_object_address
static method memcpy_object_address : void ($dest : object[], $dest_offset : int, $source : object[], $source_offset : int, $length : int)Copy the range of the elements of the source object array to the range of the elements of the destination object array.
Each address is copied.
The range of the elements of the source array is from the offset to the position proceeded by the length of the source.
The range of the elements of the destination array is from the offset of the destination to the offset of the destination + the length specified by the argument.
If the range of the elements of the source array and the range of the elements of the destination array overlap, the result is not guaranteed.
The destination must be defined. Otherwise an exception will occur.
The source must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the source must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination + the length specified by the argument must be less than or equal to the length of the destination. Otherwise an exception will occur.
The offset of the source + the length specified by the argument must be less than or equal to the length of the source. Otherwise an exception will occur.
memcpy_short
static method memcpy_short : void ($dest : short[], $dest_offset : int, $source : short[], $source_offset : int, $length : int)Copy the range of the elements of the source short array to the range of the elements of the destination short array.
The range of the elements of the source array is from the offset to the position proceeded by the length of the source.
The range of the elements of the destination array is from the offset of the destination to the offset of the destination + the length specified by the argument.
If the range of the elements of the source array and the range of the elements of the destination array overlap, the result is not guaranteed.
The destination must be defined. Otherwise an exception will occur.
The source must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the source must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the destination + the length specified by the argument must be less than or equal to the length of the destination. Otherwise an exception will occur.
The offset of the source + the length specified by the argument must be less than or equal to the length of the source. Otherwise an exception will occur.
memcpy_string_address
static method memcpy_string_address : void ($dest : string[], $dest_offset : int, $source : string[], $source_offset : int, $length : int);The alias for "memcpy_object_address".
memmove_byte
static method memmove_byte : void ($dest : byte[], $dest_offset : int, $source : byte[], $source_offset : int, $length : int)The same as "memcpy_byte", but even if the range of the source and the range of the destination overlap, the result is guaranteed.
memmove_double
static method memmove_double : void ($dest : double[], $dest_offset : int, $source : double[], $source_offset : int, $length : int)The same as "memcpy_double", but even if the range of the source and the range of the destination overlap, the result is guaranteed.
memmove_float
static method memmove_float : void ($dest : float[], $dest_offset : int, $source : float[], $source_offset : int, $length : int)The same as "memcpy_float", but even if the range of the source and the range of the destination overlap, the result is guaranteed.
memmove_int
static method memmove_int : void ($dest : int[], $dest_offset : int, $source : int[], $source_offset : int, $length : int)The same as "memcpy_int", but even if the range of the source and the range of the destination overlap, the result is guaranteed.
memmove_long
static method memmove_long : void ($dest : long[], $dest_offset : int, $source : long[], $source_offset : int, $length : int)The same as "memcpy_long", but even if the range of the source and the range of the destination overlap, the result is guaranteed.
memmove_object_address
static method memmove_object_address : void ($dest : object[], $dest_offset : int, $source : object[], $source_offset : int, $length : int)The same as "memcpy_object_address", but even if the range of the source and the range of the destination overlap, the result is guaranteed.
memmove_short
static method memmove_short : void ($dest : short[], $dest_offset : int, $source : short[], $source_offset : int, $length : int)The same as "memcpy_short", but even if the range of the source and the range of the destination overlap, the result is guaranteed.
memmove_string_address
static method memmove_string_address : void ($dest : string[], $dest_offset : int, $source : string[], $source_offset : int, $length : int);The same as the following code using "memmove_object_address".
&memmove_object_address($dest, $dest_offset, $source, $source_offset, $length);memset_byte
static method memset_byte : void ($array : byte[], $element : byte, $offset = 0 : int, $length = -1 : int)Set the range of the elements of the byte array to the element specified by the argument.
The range of the elements of the array is from the offset to the position proceeded by the length.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will occur.
The offset of the array must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the array + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will occur.
memset_double
static method memset_double : void ($array : double[], $element : double, $offset = 0 : int, $length = -1 : int)Set the range of the elements of the double array to the element specified by the argument.
The range of the elements of the array is from the offset to the position proceeded by the length.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will occur.
The offset of the array must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the array + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will occur.
memset_float
static method memset_float : void ($array : float[], $element : float, $offset = 0 : int, $length = -1 : int)Set the range of the elements of the float array to the element specified by the argument.
The range of the elements of the array is from the offset to the position proceeded by the length.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will occur.
The offset of the array must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the array + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will occur.
memset_int
static method memset_int : void ($array : int[], $element : int, $offset = 0 : int, $length = -1 : int)Set the range of the elements of the int array to the element specified by the argument.
The range of the elements of the array is from the offset to the position proceeded by the length.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will occur.
The offset of the array must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the array + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will occur.
memset_long
static method memset_long : void ($array : long[], $element : long, $offset = 0 : int, $length = -1 : int)Set the range of the elements of the long array to the element specified by the argument.
The range of the elements of the array is from the offset to the position proceeded by the length.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will occur.
The offset of the array must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the array + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will occur.
memset_object
static method memset_object : void ($array : object[], $element : object, $offset = 0 : int, $length = -1 : int)Set the range of the elements of the object array to the element specified by the argument.
The range of the elements of the array is from the offset to the position proceeded by the length.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will occur.
The offset of the array must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the array + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will occur.
memset_short
static method memset_short : void ($array : short[], $element : short, $offset = 0 : int, $length = -1 : int)Set the range of the elements of the short array to the element specified by the argument.
The range of the elements of the array is from the offset to the position proceeded by the length.
If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset.
The array must be defined. Otherwise an exception will occur.
The offset of the array must be greater than or equal to 0. Otherwise an exception will occur.
The offset of the array + the length specified by the argument must be less than or equal to the length of the array. Otherwise an exception will occur.
memset_string
static method memset_string : void ($array : string[], $element : string, $offset = 0 : int, $length = -1 : int)The alias for the following code using "memset_object".
&memset_object($dest, $element, $dest_offset, $length);new_proto
static method new_proto : object[] ($proto_array : object[], $length : int)Create a new object array as the same type as the prototype array with the length.
The prototype array must be defined. Otherwise an exception will occur.
The length must be greater than or equal to 0. Otherwise an exception will occur.