/ 
SPVM-0.9699
River stage two • 23 direct dependents • 26 total dependents
31 ++
/ SPVM::ExchangeAPI

Name

SPVM::ExchangeAPI - SPVM Exchange API

Description

SPVM::ExchangeAPI is APIs to convert Perl data structures to/from SPVM data structures, and to call SPVM methods from Perl.

Usage

  use SPVM ();
  my $api = SPVM::api();
  my $spvm_int_array = $api->new_int_array([1, 2, 3]);
  my $perl_array_ref = $spvm_int_array->to_array;
  
  my $spvm_string = $api->new_string("abc");
  my $perl_string = $spvm_string->to_string;
  
  use SPVM 'Int';
  my $int_object = Int->new(4);
  my $value = $int_object->value;

Fields

env

  my $env = $api->env;

Gets the current execution environment.

stack

  my $stack = $api->stack;

Gets the current call stack.

Class Methods

  my $api = SPVM::ExchangeAPI->new(env => $env, stack => $stack);

Creates a new SPVM::ExchangeAPI object.

Options:

env

An execution environment.

env must be a SPVM::Bulder::Env or SPVM::BlessedObject::Class object of the Env class.

stack

An call stack.

stack must be a SPVM::Bulder::Stack or SPVM::BlessedObject::Class object of the Stack class.

new_string

  my $spvm_string = $api->new_string($string);

Converts the Perl scalar $string to a SPVM string using perlapi SvPV, and returns the object that converts it to a SPVM::BlessedObject::String object.

If the $string is undef, returns undef.

If the $string is a SPVM::BlessedObject::String object, returns itself.

Exceptions:

The $string must be a non-reference scalar or a SPVM::BlessedObject::String object or undef. Otherwise an exception is thrown.

Examples:

  my $spvm_string = $api->new_string("abc");
  
  my $spvm_string = $api->new_string("あいう");

new_byte_array

  my $spvm_array = $api->new_byte_array($array);

Converts the Perl array reference $array to a SPVM byte array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Each element is converted by the conversion of "byte Type Argument".

If the $array is undef, returns undef.

If the $array is a SPVM::BlessedObject::Array object, returns itself.

Exceptions:

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be the byte[] type. Otherwise an exception is thrown.

Examples:

  my $spvm_array = $api->new_byte_array([1, 2, 3]);

new_byte_array_unsigned

  my $spvm_array = $api->new_byte_array_unsigned($array);

The same as the "new_byte_array" method, but each element is converted by the SvUV perlapi and a type cast to uint8_t in the C language.

  (int8_t)(uint8_t)SvUV(perl_scalar);

new_byte_array_len

  my $spvm_array= $api->new_byte_array_len($length);

Creates a SPVM byte array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_byte_array_len($length);

new_byte_array_from_bin

  my $spvm_array = $api->new_byte_array_from_bin($binary);

Converts the binary date $binary to a SPVM byte array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

The $binary is copied to a SPVM byte array by the memcpy function in the C laugnage. The length of the array is calcurated from the $binary.

Exceptions:

The $binary must be a defined non-reference scalar. Otherwise an exception is thrown.

Examples:

  my $binary = pack('c*', 97, 98, 99);
  my $spvm_array = $api->new_byte_array_from_bin($binary);

  my $string = "abc";
  my $spvm_array = $api->new_byte_array_from_bin($string);
  
  my $string = "あいう";
  my $spvm_array = $api->new_byte_array_from_bin($string);

new_short_array

  my $spvm_array = $api->new_short_array($array);

Converts the Perl array reference $array to a SPVM short array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Each element is converted by the conversion of "short Type Argument".

If the $array is undef, returns undef.

If the $array is a SPVM::BlessedObject::Array object, returns itself.

Exceptions:

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be the short[] type. Otherwise an exception is thrown.

Examples:

  my $spvm_array = $api->new_short_array([1, 2, 3]);

new_short_array_unsigned

  my $spvm_array = $api->new_short_array_unsigned($array);

The same as the "new_short_array" method, but each element is converted by the SvUV perlapi and a type cast to uint16_t in the C language.

  (int16_t)(uint16_t)SvUV(perl_scalar);

new_short_array_len

  my $spvm_array = $api->new_short_array_len($length);

Creates a SPVM short array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_short_array_len($length);

new_short_array_from_bin

  my $spvm_array = $api->new_short_array_from_bin($binary);

Converts the binary date $binary to a SPVM short array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

The $binary is copied to a SPVM short array by the memcpy function in the C laugnage. The length of the array is calcurated from the $binary.

Exceptions:

The $binary must be a defined non-reference scalar. Otherwise an exception is thrown.

The length of the $binary must be divisible by 2. Otherwise an exception is thrown.

Examples:

  my $binary = pack('s*', 97, 98, 99);
  my $spvm_array = $api->new_short_array_from_bin($binary);

new_int_array

  my $spvm_array = $api->new_int_array($array);

Converts the Perl array reference $array to a SPVM int array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Each element is converted by the conversion of "int Type Argument".

If the $array is undef, returns undef.

If the $array is a SPVM::BlessedObject::Array object, returns itself.

Exceptions:

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be the int[] type. Otherwise an exception is thrown.

Examples:

  my $spvm_array = $api->new_int_array([1, 2, 3]);

new_int_array_unsigned

  my $spvm_array = $api->new_int_array_unsigned($array);

The same as the "new_int_array" method, but each element is converted by the SvUV perlapi and a type cast to uint32_t in the C language.

  (int32_t)(uint32_t)SvUV(perl_scalar);

new_int_array_len

  my $spvm_array = $api->new_int_array_len($length);

Creates a SPVM int array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_int_array_len($length);

new_int_array_from_bin

  my $spvm_array = $api->new_int_array_from_bin($binary);

Converts the binary date $binary to a SPVM int array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

The $binary is copied to a SPVM int array by the memcpy function in the C laugnage. The length of the array is calcurated from the $binary.

Exceptions:

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

The length of the $binary must be divisible by 4. Otherwise an exception is thrown.

Examples:

  my $binary = pack('l*', 97, 98, 99);
  my $spvm_array = $api->new_int_array_from_bin($binary);

new_long_array

  my $spvm_array = $api->new_long_array($array);

Converts the Perl array reference $array to a SPVM long array, and returns the object that converts it to a SPVM::BlessedObject::Array object. Each element is converted by the conversion of "long Type Argument".

If the $array is undef, returns undef.

Exceptions:

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be the long[] type. Otherwise an exception is thrown.

Examples:

  my $spvm_array = $api->new_long_array([1, 2, 3]);

new_long_array_unsigned

  my $spvm_array = $api->new_long_array_unsigned($array);

The same as the "new_long_array" method, but each element is converted by the SvUV perlapi and a type cast to uint64_t in the C language.

  (int64_t)(uint64_t)SvUV(perl_scalar);

new_long_array_len

  my $spvm_array = $api->new_long_array_len($length);

Creates a SPVM long array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_long_array_len($length);

new_long_array_from_bin

  my $spvm_array = $api->new_long_array_from_bin($binary);

Converts the binary date $binary to a SPVM long array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

The $binary is copied to a SPVM long array by the memcpy function in the C laugnage. The length of the array is calcurated from the $binary.

Exceptions:

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

The length of the $binary must be divisible by 8. Otherwise an exception is thrown.

Examples:

  my $binary = pack('q*', 97, 98, 99);
  my $spvm_array = $api->new_long_array_from_bin($binary);

new_float_array

  my $spvm_array = $api->new_float_array($array);

Converts the Perl array reference $array to a SPVM float array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Each element is converted by the conversion of "float Type Argument".

If the $array is undef, returns undef.

If the $array is a SPVM::BlessedObject::Array object, returns itself.

Exceptions:

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be the float[] type. Otherwise an exception is thrown.

Examples:

  my $spvm_array = $api->new_float_array([1, 2, 3]);

new_float_array_len

  my $spvm_array = $api->new_float_array_len($length);

Creates a SPVM float array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_float_array_len($length);

new_float_array_from_bin

  my $spvm_array = $api->new_float_array_from_bin($binary);

Converts the binary date $binary to a SPVM float array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

The $binary is copied to a SPVM float array by the memcpy function in the C laugnage. The length of the array is calcurated from the $binary.

Exceptions:

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

The length of the $binary must be divisible by 4. Otherwise an exception is thrown.

Examples:

  my $binary = pack('f*', 97.1, 98.2, 99.3);
  my $spvm_array = $api->new_float_array_from_bin($binary);

new_double_array

  my $spvm_array = $api->new_double_array($array);

Converts the Perl array reference $array to a SPVM double array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Each element is converted by the conversion of "double Type Argument".

Exceptions:

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be the double[] type. Otherwise an exception is thrown.

Examples:

  my $spvm_array = $api->new_double_array([1, 2, 3]);

new_double_array_len

  my $spvm_array = $api->new_double_array_len($length);

Creates a SPVM double array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_double_array_len($length);

new_double_array_from_bin

  my $spvm_array = $api->new_double_array_from_bin($binary);

Converts the binary date $binary to a SPVM double array, and returns the object that converts it to a SPVM::BlessedObject::Array object.

The $binary is copied to a SPVM double array by the memcpy function in the C laugnage. The length of the array is calcurated from the $binary.

Exceptions:

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

The length of the $binary must be divisible by 8. Otherwise an exception is thrown.

Examples:

  my $binary = pack('d*', 97.1, 98.2, 99.3);
  my $spvm_array = $api->new_double_array_from_bin($binary);

new_string_array

  my $spvm_array = $api->new_string_array($array);

Converts the Perl array reference $array to a SPVM string array, and returns the object that converts it to a SPVM::BlessedObject::Array object. Each element is converted by the "new_string" method.

If the $array is undef, returns undef.

If the $array is a SPVM::BlessedObject::Array object, returns itself.

Exceptions:

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be the string[] type. Otherwise an exception is thrown.

Examples:

  my $spvm_array = $api->new_string_array(["foo", "bar", "baz"]);
  
  my $spvm_array = $api->new_string_array(["あい", "うえ", "お"]);

new_string_array_len

  my $spvm_array = $api->new_string_array_len($length);

Creates a SPVM string array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_string_array_len($length);

new_object_array

  my $spvm_object_array = $api->new_object_array($type_name, $array);

Converts the Perl array reference $array to a value of the SPVM object array(1-dimensional) type $type_name, and returns the object that converts it to a SPVM::BlessedObject::Array object of the $type_name type.

If the $array is undef, it is converted to SPVM undef.

If the $array is a SPVM::BlessedObject::Array object, returns itself.

Exceptions:

If the type name $type_name was parsed, but the basic type name could not be extracted, an exception is thrown.

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be assignable. Otherwise an exception is thrown.

If the bacic type of the type $type_name is not found, an exception is thrown.

The dimension of the type $type_name must be 1. Otherwise an exception is thrown.

The $type_name must be an object array type. Otherwise an exception is thrown.

Examples:

  my $point1 = SPVM::Point->new;
  my $point2 = SPVM::Point->new;
  my $spvm_array = $api->new_object_array("Point[]", [$point1, $point2]);

new_object_array_len

  my $spvm_array = $api->new_object_array_len($type_name, $length);

Creates a SPVM object array(1-dimensional) with the type name $type_name and the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object of the $type_name type.

Exceptions:

If the type name $type_name was parsed, but the basic type name could not be extracted, an exception is thrown.

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

If the bacic type of the type $type_name is not found, an exception is thrown.

The dimension of the type $type_name must be 1. Otherwise an exception is thrown.

The $type_name must be an object array type. Otherwise an exception is thrown.

Examples:

  my $length = 10;
  my $spvm_array = $api->new_object_array("Point[]", $length);

new_any_object_array

  my $byte_array = $api->new_any_object_array(
    [SPVM::Byte->new(1), SPVM::Byte>new(2), SPVM::Byte->new(3)]
  );

The alias for the following code using the "new_object_array" method.

  my $spvm_array = $api->new_object_array('object[]', $array);

new_any_object_array_len

  my $spvm_array = $api->new_any_object_array_len($length);

Creates a SPVM object array with the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object of the $type_name.

Exceptions:

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

Examples:

  my $length = 10;
  my $spvm_array = $api->new_any_object_array("Point[]", $length);

new_options

  my $spvm_any_object_array = $api->new_options($options);

Converts the Perl hash reference $options to a value of the SPVM object[] type, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Each key of the $options is converted to a SPVM::BlessedObject::String object using the "new_string" method.

Exceptions:

The value of the $options must be a SPVM::BlessedObject object. Otherwise an exception is thrown.

The $options must be a hash reference. Otherwise an exception is thrown.

Examples:

  my $options = $api->new_options({
    x => SPVM::Int->new(1),
    y => SPVM::Int->new(2)
  });

new_mulnum_array

  my $spvm_mulnum_array = $api->new_mulnum_array($type_name, $array);

Converts the Perl array reference of a hash references $array to the SPVM multi-numeric array type $type_name, and returns the object that converts it to a SPVM::BlessedObject::Array object.

Each value of the hash reference is coverted by the conversion of "byte Type Argument", "short Type Argument", "int Type Argument", "long Type Argument", "float Type Argument", "double Type Argument" corresponding to the numeric type of the the element of the $type.

Exceptions:

If the type name $type_name was parsed, but the basic type name could not be extracted, an exception is thrown.

All fields of the element type of the $type_name must be defined. Otherwise an exception is thrown.

If the bacic type of the type $type_name is not found, an exception is thrown.

The dimension of the type $type_name must be 1. Otherwise an exception is thrown.

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be assignable. Otherwise an exception is thrown.

Examples:

  my $values = [
    {x => 0, y => 1, z => 2},
    {x => 3, y => 4, z => 5},
    {x => 6, y => 7, z => 8},
  ];
  my $spvm_mulnum_array = $api->new_mulnum_array("TestCase::Point_3i[]", $values);

new_mulnum_array_len

  my $spvm_array = $api->new_mulnum_array_len($type_name, $length);

Creates a SPVM object array with the type name $type_name and the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object of the $type_name.

Exceptions:

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

If the bacic type of the type $type_name is not found, an exception is thrown.

The dimension of the $type_name must be 1. Otherwise an exception is thrown.

Examples:

  my $length = 10;
  my $spvm_array = $api->new_mulnum_array("Complex_2d[]", $length);

new_mulnum_array_from_bin

  my $spvm_mulnum_array = $api->new_mulnum_array_from_bin($type_name, $binary);

Converts the binary data $binary to a SPVM multi-numeric array type $type_name, and returns the object that converts it to a SPVM::BlessedObject::Array object.

The $binary is copied to a SPVM multi-numeric array by the memcpy function in the C laugnage. The length of the array is calcurated from the $binary.

Exceptions:

If the bacic type of the type $type_name is not found, an exception is thrown.

The dimension of the type $type_name must be 1. Otherwise an exception is thrown.

The $binary must be an array reference. Otherwise an exception is thrown.

The length of the $binary must be divisible by the length of fields * the byte size of the element type. Otherwise an exception is thrown.

Examples:

  # new_mulnum_array_from_bin - byte
  {
    my $binary = pack('c9', (0, 1, 2), (3, 4, 5), (6, 7, 8));
    my $spvm_mulnum_array = $api->new_mulnum_array_from_bin("TestCase::Point_3b[]", $binary);
  }

  # new_mulnum_array_from_bin - short
  {
    my $binary = pack('s9', (0, 1, 2), (3, 4, 5), (6, 7, 8);;
    my $spvm_mulnum_array = $api->new_mulnum_array_from_bin("TestCase::Point_3s[]", $binary);
  }

  # new_mulnum_array_from_bin - int
  {
    my $binary = pack('l9', (0, 1, 2), (3, 4, 5), (6, 7, 8));
    my $spvm_mulnum_array = $api->new_mulnum_array_from_bin("TestCase::Point_3i[]", $binary);
  }

  # new_mulnum_array_from_bin - long
  {
    my $binary = pack('q9', (0, 1, 2), (3, 4, 5), (6, 7, 8));
    my $spvm_mulnum_array = $api->new_mulnum_array_from_bin("TestCase::Point_3l[]", $binary);
  }

  # new_mulnum_array_from_bin - float
  {
    my $binary = pack('f9', (0, 1, 2), (3, 4, 5), (6, 7, 8));
    my $spvm_mulnum_array = $api->new_mulnum_array_from_bin("TestCase::Point_3f[]", $binary);
  }

  # new_mulnum_array_from_bin - double
  {
    my $binary = pack('d9', (0, 1, 2), (3, 4, 5), (6, 7, 8));
    my $spvm_mulnum_array = $api->new_mulnum_array_from_bin("TestCase::Point_3d[]", $binary);
  }

new_muldim_array

  my $spvm_object_array = $api->new_muldim_array($type_name, $array);

Converts the Perl array reference $array to a value of the SPVM multi-dimensional array type $type_name, and returns the object that converts it to a SPVM::BlessedObject::Array object.

If the $array is undef, it is converted to SPVM undef.

If the $array is a SPVM::BlessedObject::Array object, returns itself.

Exceptions:

If the $array is a reference other than the array reference, an exception is thrown.

The $array: If it is a reference, it must be an array reference. Otherwise an exception is thrown.

The $array: If it is a SPVM::BlessedObject::Array object, the type must be assignable. Otherwise an exception is thrown.

If the bacic type of the type $type_name is not found, an exception is thrown.

The dimension of the $type_name must be greater than or equal to 2 and less than or equal to 255. Otherwise an exception is thrown.

The assignability of the element to the element type of the $type_name is checked. If it is not assignable, an exception is thrown.

Examples:

  my $object1 = $api->new_int_array([1, 2, 3]);
  my $object2 = $api->new_int_array([4, 5, 6]);
  my $objects = $api->new_muldim_array("int[][]", [$object1, $object2]);

new_muldim_array_len

  my $spvm_array = $api->new_muldim_array_len($type_name, $length);

Creates a SPVM multi-dimentional array with the type name $type_name and the length $length, and returns the object that converts it to a SPVM::BlessedObject::Array object of the $type_name.

Exceptions:

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

If the bacic type of the type $type_name is not found, an exception is thrown.

The dimension of the $type_name must be greater than or equal to 2 and less than or equal to 255. Otherwise an exception is thrown.

Examples:

  my $length = 10;
  my $spvm_array = $api->new_muldim_array("int[][]", $length);

get_exception

  my $message = $api->get_exception();

Returns the exception of the current thread variables as a SPVM::BlessedObject::String object.

If the exception is not set, undef is returned.

set_exception

  $api->set_exception($message);

Sets a message given by the $message to the exception of the current thread variables.

The $message is converted to the SPVM string using the "new_string" method.

Exceptions:

Exceptions thrown by the "new_string" method are thrown.

Examples:

  $api->set_exception("Error");
  $api->set_exception(undef);

get_memory_blocks_count

  my $count = $api->get_memory_blocks_count();

Returns the count of memory blocks on the current execution environment.

Examples:

  # First Memory Blocks Count
  my $start_memory_blocks_count = $api->get_memory_blocks_count();

  # Processing
  # ...

  # Last Memory Blocks Count
  my $end_memory_blocks_count = $api->get_memory_blocks_count();

  unless ($end_memory_blocks_count == $start_memory_blocks_count) {
    die"Memroy leak";
  }

class

  my $class = $api->class($class_name);

Creates a new SPVM::ExchangeAPI::Class object with the class name $class_name, and returns it.

Examples:

  my $class = $api->class('Int');
  my $spvm_object = $class->new(1);

dump

  my $dump = $api->dump($object);

Converts the SPVM object $object to a dumped string using the dump operator, and returns it.

Exceptions:

The $object must be a SPVM::BlessedObject object. Otherwise an exception is thrown.

error

  my $error = $api->new_error;

Creates a new SPVM::ExchangeAPI::Error object, and returns it.

The error code is set to 0.

call_method

  my $ret = $api->call_method($invocant, $method_name, @args);
  
  my $ret = $api->call_method($invocant, $method_name, @args, $error);

Calls a class method or an instance method. If the invocant $invocant is a string, a class method is called. If the invocant $invocant is a SPVM::BlessedObject::Class, an instance method is called.

Each of the arguments @args are converted by the rule of "Argument Conversion".

The method name $method_name allows a static method name such as Foo::bar.

The return value is converted by the rule of "Return Value Conversion".

If a SPVM::ExchangeAPI::Error object is passed to the last of the arguments, and if an exception is thrown from a SPVM method, the error code is set to the code field of the object.

Exceptions:

If the $invocant is a SPVM::BlessedObject, the $invocant must be a SPVM::BlessedObject::Class object. Otherwise an exception is thrown.

The static method call must be valid. Otherwise an exception is thrown.

If the M method in the C class is not found, an exception is thrown.

If too few arguments are passed to the M method in the C class, an exception is thrown.

If too many arguments are passed to the M method in the C class, an exception is thrown.

If the "Argument Conversion" in argument conversion fails, an exception is thrown.

If the calling method throws an exception, the exception is thrown.

Examples:

  # Class method call
  my $obj_int = $api->call_method("Int", "new", 1);
  
  # Instance method call
  $api->call_method($obj_int, "set_value", 5);
  my $value = $api->call_method($obj_int, "value");
  
  # Call static instance method
  $api->call_method($object, "Foo::value");

Easy Ways:

Calling class methods can be made easier using the SPVM class loading feature.

  use SPVM 'Int';
  my $int_object = Int->new(4);

Instance method calls can be made easier using SPVM::BlessedObject::Class.

  my $value = $int_object->value;

Argument Conversion

Each argument passed to the "call_method" method are converted to a SPVM value according to the SPVM type before it passed to a SPVM method.

byte Type Argument

A Perl scalar is converted to a value of the SPVM byte type by the SvIV perlapi and a type cast to int8_t in the C language.

  (int8_t)SvIV(perl_scalar)

Exceptions:

The argument must be a non-reference scalar. Otherwise an exception is thrown.

short Type Argument

A Perl scalar is converted to a value of the SPVM short type by the SvIV perlapi and a type cast to int16_t in the C language.

  (int16_t)SvIV(perl_scalar)

Exceptions:

The argument must be a non-reference scalar. Otherwise an exception is thrown.

int Type Argument

A Perl scalar is converted to a value of the SPVM int type by the SvIV perlapi and a type cast to int32_t in the C language.

  (int32_t)SvIV(perl_scalar)

Exceptions:

The argument must be a non-reference scalar. Otherwise an exception is thrown.

Examples:

  my $int_object = SPVM::Int->new(10);

long Type Argument

A Perl scalar is converted to a value of the SPVM long type by the SvIV perlapi and a type cast to int64_t in the C language.

  (int64_t)SvIV(perl_scalar)

Exceptions:

The argument must be a non-reference scalar. Otherwise an exception is thrown.

Examples:

  my $long_object = SPVM::Long->new(10);

float Type Argument

A Perl scalar is converted to a value of the SPVM float type by the SvNV perlapi and a type cast to float in the C language.

  (float)SvNV(perl_scalar)

Exceptions:

The argument must be a non-reference scalar. Otherwise an exception is thrown.

Examples:

  my $float_object = SPVM::Float->new(10.5);

double Type Argument

A Perl scalar is converted to a value of the SPVM double type by the SvNV perlapi and a type cast to double in the C language.

  (double)SvNV(perl_scalar)

Exceptions:

The argument must be a non-reference scalar. Otherwise an exception is thrown.

Examples:

  my $double_object = SPVM::Double->new(10.5);

string Type Argument

A Perl scalar is converted to a value of the SPVM string type by the "new_string" method.

Exceptions:

Exceptions thrown by the "new_string" method are thrown.

Examples:

  my $substr = SPVM::Fn->substr("abcde", 0, 3);

Any Object Type Argument

No conversion is performed.

Exceptions:

The argument must be a SPVM::BlessedObject object or undef. Otherwise an exception is thrown.

Class Type Argument

No conversion is performed.

Exceptions:

The argument must be a SPVM::BlessedObject::Class object of a Z assignable type or undef. Otherwise an exception is thrown.

Interaface Type Argument

No conversion is performed.

Exceptions:

The argument must be a SPVM::BlessedObject::Class object of a Z assignable type or undef. Otherwise an exception is thrown.

Multi-Numeric Type Argument

Multi-Numeric byte

Converts a hash reference containing field names and its values of the multi-numeric byte type to a value of the multi-numeric byte type.

Each field value is coverted by the conversion of "byte Type Argument".

Exceptions:

The argument must be a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl hash reference to MyClassPoint_2b type
  SPVM::MyClass->foo({x => 1, y => 2});

Multi-Numeric short Type Argument

Converts a hash reference containing field names and its values of the multi-numeric short type to a value of the multi-numeric short type.

Each field value is coverted by the conversion of "short Type Argument".

Exceptions:

The argument must be a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl hash reference to MyClassPoint_2s type
  SPVM::MyClass->foo({x => 1, y => 2});

Multi-Numeric int Type Argument

Converts a hash reference containing field names and its values of the multi-numeric int type to a value of the multi-numeric int type.

Each field value is coverted by the conversion of "int Type Argument".

Exceptions:

The argument must be a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl hash reference to MyClassPoint_2i type
  SPVM::MyClass->foo({x => 1, y => 2});

Multi-Numeric long Type Argument

Converts a hash reference containing field names and its values of the multi-numeric long type to a value of the multi-numeric long type.

Each field value is coverted by the conversion of "long Type Argument".

Exceptions:

The argument must be a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl hash reference to MyClassPoint_2l type
  SPVM::MyClass->foo({x => 1, y => 2});

Multi-Numeric float Type Argument

Converts a hash reference containing field names and its values of the multi-numeric float type to a value of the multi-numeric float type.

Each field value is coverted by the conversion of "float Type Argument".

Exceptions:

The argument must be a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl hash reference to MyClassPoint_2f type
  SPVM::MyClass->foo({x => 1.2, y => 2.3});

Multi-Numeric double Type Argument

Converts a hash reference containing field names and its values of the multi-numeric double type to a value of the multi-numeric double type.

Each field value is coverted by the conversion of "double Type Argument".

Exceptions:

The argument must be a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl hash reference to MyClassPoint_2d type
  SPVM::MyClass->foo({x => 1.2, y => 2.3});

Numeric Reference Type Argument

byte Reference Type Argument

A Perl reference is converted to a value of the SPVM byte reference type.

The referenced value is converted to a value of the SPVM byte type by the conversion of "byte Type Argument".

After returning from the SPVM method, the referenced value is converted to a Perl scalar by the conversion of "byte Type Return Value"

Exceptions:

The argument must be a scalar reference. Otherwise an exception is thrown.

Examples:

  # Converts a Perl scalar reference to byte* type
  my $value = 23;
  SPVM::MyClass->foo(\$value);

short Reference Type Argument

A Perl reference is converted to a value of the SPVM short reference type.

The referenced value is converted to a value of the SPVM short type by the conversion of "short Type Argument".

After returning from the SPVM method, the referenced value is converted to a Perl scalar by the conversion of "short Type Return Value"

Exceptions:

The argument must be a scalar reference. Otherwise an exception is thrown.

Examples:

  # Converts a Perl scalar reference to short* type
  my $value = 23;
  SPVM::MyClass->foo(\$value);

int Reference Type Argument

A Perl reference is converted to a value of the SPVM int reference type.

The referenced value is converted to a value of the SPVM int type by the conversion of "int Type Argument".

After returning from the SPVM method, the referenced value is converted to a Perl scalar by the conversion of "int Type Return Value"

Exceptions:

The argument must be a scalar reference. Otherwise an exception is thrown.

Examples:

  # Converts a Perl scalar reference to int* type
  my $value = 23;
  SPVM::MyClass->foo(\$value);

long Reference Type Argument

A Perl reference is converted to a value of the SPVM long reference type.

The referenced value is converted to a value of the SPVM long type by the conversion of "long Type Argument".

After returning from the SPVM method, the referenced value is converted to a Perl scalar by the conversion of "long Type Return Value"

Exceptions:

The argument must be a scalar reference. Otherwise an exception is thrown.

Examples:

  # Converts a Perl scalar reference to long* type
  my $value = 23;
  SPVM::MyClass->foo(\$value);

float Reference Type Argument

A Perl reference is converted to a value of the SPVM float reference type.

The referenced value is converted to a value of the SPVM float type by the conversion of "float Type Argument".

After returning from the SPVM method, the referenced value is converted to a Perl scalar by the conversion of "float Type Return Value"

Exceptions:

The argument must be a scalar reference. Otherwise an exception is thrown.

Examples:

  # Converts a Perl scalar reference to float* type
  my $value = 23.5;
  SPVM::MyClass->foo(\$value);

double Reference Type Argument

A Perl reference is converted to a value of the SPVM double reference type.

The referenced value is converted to a value of the SPVM double type by the conversion of "double Type Argument".

After returning from the SPVM method, the referenced value is converted to a Perl scalar by the conversion of "double Type Return Value"

Exceptions:

The argument must be a scalar reference. Otherwise an exception is thrown.

Examples:

  # Converts a Perl scalar reference to double* type
  my $value = 23.5;
  SPVM::MyClass->foo(\$value);

Multi-Numeric Reference Type Argument

Multi-Numeric byte Reference Type Argument

A Perl reference is converted to a SPVM multi-numeric byte reference type.

Each field is converted to a value of the SPVM byte type by the conversion of "byte Type Argument".

After returning from the SPVM method, each field value is converted to a Perl scalar by the conversion of "byte Type Return Value".

Exceptions:

The reference must be a scalar reference to a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl scalar reference to a hash reference to the MyClassPoint_2b* type
  my $value = {x => 1, y => 2};
  SPVM::MyClass->foo(\$value);

Multi-Numeric short Reference Type Argument

A Perl reference is converted to a SPVM multi-numeric short reference type.

Each field is converted to a value of the SPVM short type by the conversion of "short Type Argument".

After returning from the SPVM method, each field value is converted to a Perl scalar by the conversion of "short Type Return Value".

Exceptions:

The reference must be a scalar reference to a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl scalar reference to a hash reference to the MyClassPoint_2s* type
  my $value = {x => 1, y => 2};
  SPVM::MyClass->foo(\$value);

Multi-Numeric int Reference Type Argument

A Perl reference is converted to a SPVM multi-numeric int reference type.

Each field is converted to a value of the SPVM int type by the conversion of "int Type Argument".

After returning from the SPVM method, each field value is converted to a Perl scalar by the conversion of "int Type Return Value".

Exceptions:

The reference must be a scalar reference to a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl scalar reference to a hash reference to the SPVM MyClassPoint_2i* type
  my $value = {x => 1, y => 2};
  SPVM::MyClass->foo(\$value);

Multi-Numeric long Reference Type Argument

A Perl reference is converted to a SPVM multi-numeric long reference type.

Each field is converted to a value of the SPVM long type by the conversion of "long Type Argument".

After returning from the SPVM method, each field value is converted to a Perl scalar by the conversion of "long Type Return Value".

Exceptions:

The reference must be a scalar reference to a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl scalar reference to a hash reference to the SPVM MyClassPoint_2l* type
  my $value = {x => 1, y => 2};
  SPVM::MyClass->foo(\$value);

Multi-Numeric float Reference Type Argument

A Perl reference is converted to a SPVM multi-numeric float reference type.

Each field is converted to a value of the SPVM float type by the conversion of "float Type Argument".

After returning from the SPVM method, each field value is converted to a Perl scalar by the conversion of "float Type Return Value".

Exceptions:

The reference must be a scalar reference to a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl scalar reference to a hash reference to the SPVM MyClassPoint_2f* type
  my $value = {x => 1,2, y => 2.3};
  SPVM::MyClass->foo(\$value);

Multi-Numeric double Reference Type Argument

A Perl reference is converted to a SPVM multi-numeric double reference type.

Each field is converted to a value of the SPVM double type by the conversion of "double Type Argument".

After returning from the SPVM method, each field value is converted to a Perl scalar by the conversion of "double Type Return Value".

Exceptions:

The reference must be a scalar reference to a hash reference. Otherwise an exception is thrown.

If a field is not found, an exception is thrown.

Examples:

  # Converts a Perl scalar reference to a hash reference to the SPVM MyClassPoint_2d* type
  my $value = {x => 1.2, y => 2.3};
  SPVM::MyClass->foo(\$value);

Array Type Argument

byte[] Type Argument

A Perl array reference(or undef) is converted to a value of the byte[] type by the "new_byte_array" method.

Exceptions:

Exceptions thrown by the "new_byte_array" method are thrown.

Examples:

  # Converts a Perl array reference to the byte[] type
  SPVM::MyClass->foo([1, 2, 3]);

short[] Type Argument

A Perl array reference(or undef) is converted to a value of the short[] type by the "new_short_array" method.

Exceptions:

Exceptions thrown by the "new_short_array" method are thrown.

Examples:

  # Converts a Perl array reference to the short[] type
  SPVM::MyClass->foo([1, 2, 3]);

int[] Type Argument

A Perl array reference(or undef) is converted to a value of the int[] type by the "new_int_array" method.

Exceptions:

Exceptions thrown by the "new_int_array" method are thrown.

Examples:

  # Converts a Perl array reference to the int[] type
  SPVM::MyClass->foo([1, 2, 3]);

long[] Type Argument

A Perl array reference(or undef) is converted to a value of the long[] type by the "new_long_array" method.

Exceptions:

Exceptions thrown by the "new_long_array" method are thrown.

Examples:

  # Converts a Perl array reference to the long[] type
  SPVM::MyClass->foo([1, 2, 3]);

float[] Type Argument

A Perl array reference(or undef) is converted to a value of the float[] type by the "new_float_array" method.

Exceptions:

Exceptions thrown by the "new_float_array" method are thrown.

Examples:

  # Converts a Perl array reference to float[] type
  SPVM::MyClass->foo([1.2, 2.3, 3.4]);

double[] Type Argument

A Perl array reference(or undef) is converted to a value of the double[] type by the "new_double_array" method.

Exceptions:

Exceptions thrown by the "new_double_array" method are thrown.

Examples:

  # Converts a Perl array reference to the double[] type
  SPVM::MyClass->foo([1.2, 2.3, 3.4]);

string[] Type Argument

A Perl array reference(or undef) is converted to a value of the string[] type by the "new_string_array" method.

Exceptions:

Exceptions thrown by the "new_string_array" method are thrown.

Examples:

  # Converts a Perl array reference to the string[] type
  SPVM::MyClass->foo(["あい", "うえ", "お"]);

Any Object Array Type Argument

A Perl array reference(or undef) is converted to a value of the object[] type by the "new_object_array" method.

Exceptions:

Exceptions thrown by the "new_object_array" method are thrown.

Class Array Type Argument

A Perl array reference(or undef) is converted to a value of the class type by the "new_object_array" method.

Exceptions:

Exceptions thrown by the "new_object_array" method are thrown.

Interface Array Type Argument

A Perl array reference(or undef) is converted to a value of the interface type by the "new_object_array" method.

Exceptions:

Exceptions thrown by the "new_object_array" method are thrown.

Multi-Numeric Array Type Argument

A Perl array reference(or undef) is converted to a value of the multi-numeric array type by the "new_mulnum_array" method.

Exceptions:

Exceptions thrown by the "new_mulnum_array" method are thrown.

Examples:

  # Converts a Perl array reference of a hash reference to the Complex_2d[] type
  SPVM::MyClass->foo([{re => 1.2, im => 2.3}, {re => 3.4, im => 4.5}]);

Multi-Dimensional Array Type Argument

A Perl array reference(or undef) is converted to a value of the multi-dimensional array type by the "new_muldim_array" method.

Exceptions:

Exceptions thrown by the "new_muldim_array" method are thrown.

Return Value Conversion

A SPVM return value is converted to a Perl value according to the SPVM type.

void Type Return Value

The SPVM void return value is converted to Perl undef.

byte Type Return Value

A value of the SPVM byte type is converted to a Perl scalar using the newSViv perlapi.

short Type Return Value

A value of the SPVM short type is converted to a Perl scalar using the newSViv perlapi.

int Type Return Value

A value of the SPVM float type is converted to a Perl scalar using the newSViv perlapi.

long Type Return Value

A value of the SPVM float type is converted to a Perl scalar using the newSViv perlapi.

float Type Return Value

A value of the SPVM float type is converted to a Perl scalar using the newSVnv perlapi.

double Type Return Value

A value of the SPVM double type is converted to a Perl scalar using the newSVnv perlapi.

string Type Return Value

If the SPVM return value is undef, it is converted to Perl undef.

Otherwise it is converted to a SPVM::BlessedObject::String object.

Multi-Numeric Type Return Value

The value of the SPVM multi-numeric type is converted to a Perl hash reference that has the field names of the multi-numeric type as the keys.

Each field value is converted by the conversion of "byte Type Return Value", "short Type Return Value", "int Type Return Value", "long Type Return Value", "float Type Return Value", "double Type Return Value" according to the multi-numeric type.

Any Object Type Return Value

If the SPVM return value is undef, it is converted to Perl undef.

If the type of the return value is an array type, it is converted to a SPVM::BlessedObject::Array object.

If the type of the return value is an string type, it is converted to a SPVM::BlessedObject::String object.

Otherwise it is converted to a SPVM::BlessedObject::Class object.

Class Type Return Value

If the SPVM return value is undef, it is converted to Perl undef.

Otherwise it is converted to a SPVM::BlessedObject::Class object.

Interface Type Return Value

If the SPVM return value is undef, it is converted to Perl undef.

Otherwise it is converted to a SPVM::BlessedObject::Class object.

Array Type Return Value

If the SPVM return value is undef, it is converted to Perl undef.

Otherwise it is converted to a SPVM::BlessedObject::Array object.

Copyright & License

Copyright (c) 2023 Yuki Kimoto

MIT License