/ 
SPVM-0.9009
River stage two • 37 direct dependents • 40 total dependents
/ SPVM::Document::ExchangeAPI

NAME

SPVM::Document::ExchangeAPI - SPVM Exchange API

DESCRIPTION

SPVM Exchange API is APIs to convert Perl data structures to SPVM data structures, and the reverse.

SPVM EXCHANGE API

SPVM Exchange API

SPVM Exchange API is described in this document.

What is SPVM Exchange API?

SPVM Exchange API is API for converting Perl data structure to/from SPVM data structure, and calling SPVM Method from Perl.

  • Convert Perl data structure such as Perl numbers, strings, arrays to/from SPVM data structure
  • Call SPVM Method from Perl

SPVM Module can be used as Perl Module.

Convert Perl Data Structure to SPVM Data Structure

Convert Perl Scalar Data to SPVM::Byte Value - SPVM::Byte->new

To Convert Perl Scalar Data to SPVM::Byte Value, use the SPVM::Byte->new method. 

my $spvm_byte = SPVM::Byte->new(98);

Perl Scalar Data is converted to numeric byte value of SPVM by the Rule to Convert Perl Scalar Data to SPVM Numeric Value, and the value is passed to the new method of SPVM::Byte, and SPVM:Byte object is returned.

Convert Perl Scalar Data to SPVM::Short - SPVM::Short->new

To Convert Perl Scalar Data to SPVM::Short, use the SPVM::Short->new method. 

my $spvm_short = SPVM::Short->new(9800);

Perl Scalar Data is converted to SPVM short types by the Rule to Convert Perl Scalar Data to SPVM Numeric Value, and the value is passed to the new method of SPVM:Short, and SPVM:Short object is returned.

Convert Perl Scalar Data to SPVM::Int - SPVM::Int->new

To Convert Perl Scalar Data to SPVM::Int, use the SPVM::Int->new method. 

my $spvm_int = SPVM::Int->new(100000);

Perl Scalar Data is converted to numeric int value of SPVM by the Rule to Convert Perl Scalar Data is converted to SPVM Numeric Value, and the value is passed to the new method of SPVM::Int, and the SPVM::Int object is returned.

Convert Perl Scalar Data to SPVM::Long type - SPVM::Long->new

To Convert Perl Scalar Data to SPVM::Long, use the SPVM::Long->new method. 

my $spvm_long = SPVM::Long->new(98);

Perl Scalar Data is converted to numeric long value of SPVM by the Rule to Convert Perl Scalar Data is converted to SPVM Numeric Value, and the value is passed to the new method of SPVM::Long, and the SPVM::Long object is returned.

Convert Perl Scalar Data to SPVM::Float - SPVM::Float->new

To Convert Perl Scalar Data to SPVM::Float, use the SPVM::Float->new method. 

my $spvm_float = SPVM::Float->new(2.5);Rule to Convert

Perl Scalar Data is converted to numric float value of SPVM by the Rule to Convert Perl Scalar Data to SPVM Numeric Value, and that value is passed to the new method of SPVM::Float, and SPVM::Float object is returned.

Convert Perl Scalar Data to SPVM::Double type - SPVM::Double->new

To Convert Perl Scalar Data to SPVM::Double, use the SPVM::Double->new method. 

my $spvm_double = SPVM::Double->new(2.5);

Perl Scalar Data is converted to numric double value of SPVM by the Rule to Convert Perl Scalar Data is converted to SPVM Numeric Value, and that value is passed to the new method of SPVM::Double, and SPVM::Double object is returned.

Convert Perl Array Reference to SPVM byte[] value - SPVM::new_byte_array

To convert Perl Array References to SPVM byte[] values, use the SPVM::new_byte_array function. 

my $spvm_nums = SPVM::new_byte_array([1, 2, 3]);

Takes Array Reference to the first argument.

The value of each element in the Array Reference is converted from the Perl Scalar Data to the SPVM byte type by the Rule to Convert the scalar values of Perl Scalar Data to Numeric Types of SPVM.

The return value is the SPVM::Data::Array object that represents the "byte[] value" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Array Reference to short[] value of SPVM

To convert Perl Array References to SPVM short[] values, use the SPVM::new_short_array function. 

my $spvm_nums = SPVM::new_short_array([1, 2, 3]);

Takes Array Reference to the first argument.

The value of each element in the Array Reference is converted from the Perl Scalar Data to the Short type of SPVM by the Rule to Convert Perl Scalar Data is converted to a Numeric Type of SPVM.

The return value is the SPVM::Data::Array object that represents the "short[]" type of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Array Reference to SPVM int[] value

To convert Perl Array References to SPVM int[] values, use the SPVM::new_int_array function. 

my $spvm_nums = SPVM::new_int_array([1, 2, 3]);

Takes Array Reference to the first argument.

The value of each element in the Array Reference is converted from the Perl Scalar Data to the SPVM int type by the Rule to Convert the Rule to Convert Perl Scalar Data to SPVM Numeric Value.

The return value is the SPVM::Data::Array object that represents the "int[] value" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Array Reference to SPMV long[] value

To convert Perl Array References to long[] types of SPVM, use the SPVM::new_long_array function. 

my $spvm_nums = SPVM::new_long_array([1, 2, 3]);

Takes Array Reference to the first argument.

The value of each element in the Array Reference is converted from Perl Scalar Datas to long types of SPVM by the following conversions from perlapi and C99 type conversions: 

(int64_t) SvIV(perl_scalar_data)

The return value is the SPVM::Data::Array object that represents the "long[]" type of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Array Reference to SPVM float[] value

To convert Perl Array References to SPVM float[] values, use the SPVM::new_float_array function. 

my $spvm_nums = SPVM::new_float_array([1, 2, 3]);

Takes Array Reference to the first argument.

The value of each element in the Array Reference is converted from Perl Scalar Datas to float types of SPVM by the following conversions from perlapi and C99 type conversions: 

(float) SvNV(perl_scalar_data)

The return value is the SPVM::Data::Array object that represents the "float[] value" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Array Reference to SPVM double[] value

To convert Perl Array References to SPVM double[] value, use the SPVM::new_double_array function. 

my $spvm_nums = SPVM::new_double_array([1, 2, 3]);

Takes Array Reference to the first argument.

The value of each element in the Array Reference is converted from Perl Scalar Datas to double types of SPVM by the following conversions from perlapi and C99 type conversions: 

(double) SvNV(perl_scalar_data)

The return value is the SPVM::Data::Array object that represents the "double[] type" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Array Reference to SPVM Array Object - SPVM::new_object_array

To convert Perl Array References to SPVM Object Array, use the SPVM::new_object_array function. 

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

The first argument specifies the type name. It must be an array type that is an element of the base type that exists. Otherwise, an Exception is raised.

The second argument is Perl Array Reference. The element must be an object that inherits "SPVM::Data" representing the object type of the SPVM, or an Undefined Value. Otherwise, an Exception is raised.

The return value is an "SPVM::Data::Array" object that represents the array type of the SPVM.

You can also generate multidimensional arrays. 

my $object1 = SPVM::new_int_array([1, 2, 3]);
my $object2 = SPVM::new_int_array([4, 5, 6]);
my $oarray = SPVM::new_object_array("int[][]",[$object1, $object2]);

Convert Perl Array Reference to SPVM Multi Numeric Array - SPVM::new_mulnum_array

To convert Perl Array References to SPVM Multi Numeric Array, use the SPVM::new_mulnum_array function. 

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

The first argument specifies the array type of the value of the SPVM.

The second argument is Array Reference with a hash reference on the element. The key of the hash reference must contain the values of all fields of multiNumeric Type. Otherwise, an Exception is raised.

The return value is an "SPVM::Data::Array" object that represents the array type of the Value of SPVM.

The values in the hash reference is converted by the Rule to Convert Perl Scalar Data by Rule that convert scalar values to SPVM Numeric Value.

There are some samples. 

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

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

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

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

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

# new_mulnum_array - double
{
  my $values = [
    {x => 0, y => 1, z => 2},
    {x => 3, y => 4, z => 5},
    {x => 6, y => 7, z => 8},
  ];
  my $spvm_mulnum_array = SPVM::new_mulnum_array("TestCase::Point_3d[],"$values);
  ok(TestCase::ExchangeAPI-spvm_new_mulnum_array_double($spvm_mulnum_array));
  my $out_values = $spvm_mulnum_array->to_elems;
  is_deeply($out_values, $values);
}

Convert Perl Binary Data to SPVM byte[] value - SPVM::new_byte_array_from_bin

To convert Perl Binary Data to the byte[] value of SPVM, use the SPVM::new_byte_array_from_bin function. 

my $perl_binary = pack('c3', 97, 98, 99);
my $spvm_byte_array = SPVM::new_byte_array_from_bin($perl_binary);

The first argument takes Perl Binary Data.

Binary columns are interpreted as 8-bit signed integers arranged in byte order in the execution environment. The length is the length when interpreted as an 8-bit signed integer.

The return value is the SPVM::Data::Array object that represents the "byte[] value" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

The sample above also has the same meaning as: Binary columns can be a sequence of 8-bit signed integers, using a pack or a string that is not perl decode. 

my $binary ="abc";
my $spvm_byte_array = SPVM::new_byte_array_from_bin($perl_binary);

Convert Perl Binary Data to SPVM string - SPVM::new_string_from_bin

To convert Perl Binary Data to SPVM string types, use the SPVM::new_string_from_bin function. 

my $perl_binary = pack('c3', 97, 98, 99);
my $spvm_byte_array = SPVM::new_string_from_bin($perl_binary);

The first argument takes Perl Binary Data.

Binary columns are interpreted as 8-bit signed integers arranged in byte order in the execution environment. The length is the length when interpreted as an 8-bit signed integer.

The return value is the SPVM::Data::Array object that represents the "byte[] value" of SPVM. The string type of SPVM is treated as a byte[] value at run time.

If the first argument is an Undefined Value, an Undefined Value is returned.

The sample above also has the same meaning as: Binary columns can be a sequence of 8-bit signed integers, using a pack or a string that is not perl decode. 

my $binary ="abc";
my $spvm_byte_array = SPVM::new_byte_array_from_bin($perl_binary);

This function is actually an alias for SPVM::new_byte_array_from_bin.

Convert Perl Binary Data to SPVM short[] value - SPVM::new_short_array_from_bin

To convert Perl Binary Data to the short[] value of SPVM, use the SPVM::new_short_array_from_bin function. 

my $perl_binary = pack('s3', 97, 98, 99);
my $spvm_short_array = SPVM::new_short_array_from_bin($perl_binary);

The first argument takes Perl Binary Data.

Binary columns are interpreted as a 16-bit signed integer sequence arranged in byte order in the execution environment. The length is the length when interpreted as a 16-bit signed integer.

The return value is the SPVM::Data::Array object that represents the "short[]" type of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Binary Data to SPVM int[] value - SPVM::new_int_array_from_bin

To convert Perl Binary Data to the SPVM int[] value, use the SPVM::new_int_array_from_bin function. 

my $perl_binary = pack('l3', 97, 98, 99);
my $spvm_int_array = SPVM::new_int_array_from_bin($perl_binary);

The first argument takes Perl Binary Data.

Binary columns are interpreted as a 32-bit signed integer sequence arranged in byte order in the execution environment. The length is the length when interpreted as a 32-bit signed integer.

The return value is the SPVM::Data::Array object that represents the "int[] value" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Binary Data to SPVM long[] value - SPVM::new_long_array_from_bin

To convert Perl Binary Data to the SPMV long[] value, use the SPVM::new_long_array_from_bin function. 

my $perl_binary = pack('q3', 97, 98, 99);
my $spvm_long_array = SPVM::new_long_array_from_bin($perl_binary);

The first argument takes Perl Binary Data.

Binary columns are interpreted as a 64-bit signed integer sequence arranged in byte order in the execution environment. The length is the length when interpreted as a 64-bit signed integer.

The return value is the SPVM::Data::Array object that represents the "long[]" type of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Binary Data to SPVM float[] value - SPVM::new_float_array_from_bin

To convert Perl Binary Data to the SPVM float[] value, use the SPVM::new_float_array_from_bin function. 

my $perl_binary = pack('f3', 0.5, 1.5, 2.5);
my $spvm_float_array = SPVM::new_float_array_from_bin($perl_binary);

The first argument takes Perl Binary Data.

Binary columns are interpreted as 32-bit floating-point sequences arranged in byte order in the execution environment. The length is the length when interpreted as a 32-bit floating point.

The return value is the SPVM::Data::Array object that represents the "float[] value" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Binary Data to SPVM double[] value - SPVM::new_double_array_from_bin

To convert Perl Binary Data to the double[] type of SPVM, use the SPVM::new_double_array_from_bin function. 

my $perl_binary = pack('f3', 0.5, 1.5, 2.5);
my $spvm_double_array = SPVM::new_double_array_from_bin($perl_binary);

The first argument takes Perl Binary Data.

Binary columns are interpreted as 32-bit floating-point sequences arranged in byte order in the execution environment. The length is the length when interpreted as a 32-bit floating point.

The return value is the SPVM::Data::Array object that represents the "double[] type" of SPVM.

If the first argument is an Undefined Value, an Undefined Value is returned.

Convert Perl Binary Data to SPVM Multi Numeric Array - SPVM::new_mulnum_array_from_bin

To convert Perl Binary Data to SPVM Multi Numeric Array, use the SPVM::new_mulnum_array_from_bin function. 

my $binary = pack('l9', ($INT_MIN, 1, 2), (3, 4, 5), (6, 7, 8));
my $spvm_mulnum_array = SPVM::new_mulnum_array_from_bin("TestCase::Point_3i[],"$binary);

The first argument specifies the Perl packed binaries. The length of the binary is multiplied by the number of multinumeric fields and the field width, which must be disdivided. Otherwise, an Exception is raised.

The second argument specifies the array type of the value of the SPVM.

The return value is an "SPVM::Data::Array" object that represents the array type of the Value of SPVM. The length of the returned array is the length of the binary, multiplied by the number of multinumeric fields and the field width, divided.

There are some samples. 

# new_mulnum_array_from_bin - byte
{
  my $binary = pack('c9', (0, 1, 2), (3, 4, 5), (6, 7, 8));
  my $spvm_mulnum_array = SPVM::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 = SPVM::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 = SPVM::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 = SPVM::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 = SPVM::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 = SPVM::new_mulnum_array_from_bin("TestCase::Point_3d[],"$binary);
}

The first argument specifies the array type of the value of the SPVM.

The second argument is Array Reference with a hash reference on the element. The key of the hash reference must contain the values of all fields of multiNumeric Type. Otherwise, an Exception is raised.

Convert Perl string to SPVM byte[] value - SPVM::new_byte_array_from_string

To convert Perl string to SPVM byte[] value, use SPVM::new_byte_array_from_string function. A Perl string here refers to a decoded string. 

use utf8;
my $spvm_byte_array = SPVM::new_byte_array_from_string("aiueo");

It receives a Perl string as the first argument. A Perl string here refers to a decoded string.

The length is the length when counting the byte string as UTF-8.

The return value is a "SPVM::Data::Array" object that represents the "byte[]" type of SPVM.

If the first argument is an Undefined Value, the Undefined Value will be returned.

Perl Convert string to SPVM string - SPVM::new_string

To convert perl strings to SPVM string types, use the SPVM::new_string function. Perl strings refer to decoded strings here. 

use utf8;
my $spvm_string = SPVM::new_string("Aiueo");

The first argument takes a Perl string.

The length is utf-8, the length of the byte sequence counted.

The return value is the SPVM::Data::Array object that represents the "byte[] value" of SPVM. The string type of SPVM is treated as a byte[] value at run time.

If the first argument is an Undefined Value, an Undefined Value is returned.

This function is actually an alias for SPVM::new_byte_array_from_string.

Convert SPVM Value to Perl Data

Get SPVM Array Length - length

Get SPVM Array Length 

my $length = $spvm_array->length;

Convert SPVM Array to Perl Array Reference - to_elems

To convert SPVM Array to Perl Array Reference, use the SPVM::Data::Array to_elems method. 

my $perl_array_ref = $spvm_array->to_elems;

If the elements of the SPVM Array are Numeric Types, the SPVM Numeric Value is converted by the Rule that convert Numeric Types of Perl to Perl Scalar Datas.

If the element of the SPVM Array is an object type, the corresponding SPVM::Data or its subclass is created.

If the elements of the SPVM Array are multiNumeric Types, a hash reference is created with the key and value of the field. The value is converted by a rule that converts the Numeric Type of SPVM to Perl Scalar Datas.

If the elements of the SPVM Array are Undefined Values, they is converted to undefined Perl values.

Convert SPVM Array to Perl Binary Data - to_bin

To convert SPVM Array to Perl Binary Data, use the SPVM::Data::Array to_bin method. 

my $perl_binary = $spvm_array->to_bin;

If the SPVM Array is a numeric array type or a value array type, the binary representation in SPVM is copied directly into the scalar variable.

If the Array of SPVM is of any other type, an Exception is raised.

Convert SPVM string to Perl string - to_string

To convert SPVM string to a Perl string, use the SPVM::Data::Array to_string method. 

my $perl_string = $spvm_string->to_string;

If the SPVM type is of byte[] or string type, it is converted to a string decoded by Perl UTF-8.

If the Data in SPVM is an Undefined Value, it is converted to an Undefined Value in Perl.

If the Data in SPVM is of a type other than the above, an Exception is raised.

Convert SPVM string Array to Perl Array Reference that element is string - to_strings

To convert SPVM string Array to Perl Array Reference that element is string, use the SPVM::Data::Array to_strings method. 

my $perl_array_ref = $spvm_string_array->to_strings;

If the SPVM type is of byte[]], or string[], it is converted to a reference for an array of perl UTF-8 decoded strings.

If an element of the SPVM Array type is an Undefined Value, it is converted to an Undefined Value in Perl.

If the Data in SPVM is of a type other than the above, an Exception is raised.

Call SPVM Method

Load SPVM Module

The SPVM Module can be loaded from Perl as follows: The Module name and search Rule are the same as Perl, except that the extension is "spvm". 

# script.pl
use SPVM 'Foo';

Suppose the following Foo.spvm is placed on the Module search path. 

# Foo.spvm
package Foo {
  sub sum : int ($x1: int, $x2: int) {
    return $x1 + $x2;
  }
}

Call Method

In order to call a Method, the SPVM Module must be loaded by Load SPVM Module. 

# script.pl
use SPVM 'Foo';

Suppose the following Foo.spvm is placed on the Module search path. 

# Foo.spvm
package Foo {
  sub sum : int ($x1: int, $x2: int) {
    return $x1 + $x2;
  }
}

SPVM Method are wrapped in Perl Method and can be called using Perl class Call Method. 

# script.pl
use SPVM 'Foo';

my $total = Foo->sum(1, 2);

If the number of arguments does not match the number of arguments of the SPVM Method, an Exception will be thrown.

The Perl value passed as an argument is converted to the SPVM value by Argument Type Conversion.

If the converted type does not match the argument type of the SPVM Method, an Exception is thrown.

The return value is transformed by the conversion on the return value.

SPVM Exception is converted to Perl Exception.

Call Method

In order to call the method, the SPVM Module must be loaded by Load SPVM Module. 

# script.pl
use SPVM 'Foo';

Suppose the following Foo.spvm is placed on the Module search path. 

# Foo.spvm
package Foo {
  sub new : Foo () {
    return new Foo;
  }

  sub sum : int ($self: self, $x1: int, $x2: int) (
    return $x1 + $x2;
  }
}

SPVM Method are wrapped in Perl Method and can be called using Perl Call Method. 

# script.pl
use SPVM 'Foo';

my $foo = Foo->new;

my $total = $foo->sum(1, 2);

If the number of arguments does not match the number of arguments of the SPVM Method, an Exception will be thrown.

The Perl value passed as an argument is converted to the SPVM value by Argument Type Conversion.

If the converted type does not match the argument type of the SPVM Method, an Exception is thrown.

The return value is transformed by the conversion on the return value.

SPVM Exception is converted to Perl Exception.

Argument Type Conversion

Numeric Type

If the argument type of the SPVM Method definition is a Numeric Type, the argument value is Perl Scalar Data. It is converted to SPVM number by the Rule to Convert to SPVM number types. 

# SPVM Method definition
package Foo {
  sub call_byte : void ($num: byte);
  sub call_short : void ($num: short);
  sub call_int : void ($num: int);
  sub call_long : void ($num: long);
  sub call_float : void ($num: float);
  sub call_double : void ($num: double);
}

# Call from Perl
Foo->call_byte(23);
Foo->call_short(23);
Foo->call_int(23);
Foo->call_long(23);
Foo->call_float(2.3);
Foo->call_double(2.3);
Multi Numeric Type

If the argument type in the SPVM Method definition was a Multi Numeric Type, the argument value must be a hash reference and the key must contain all Multi Numeric field names. Otherwise, an Exception will be raised. The value of the hash reference is The rule that converts the scalar value of Perl to the Numeric Type of SPVM Is converted to a value. 

# SPVM Method definition
package Foo {
  sub call_complex_float : void ($z: SPVM::Complex_2f);
  sub call_complex_double : void ($z: SPVM::Complex_2d);
}

# Call from Perl
Foo->call_complex_float({re => 2.3, im => 5.6});
Foo->call_complex_double({re => 2.3, im => 5.6});
Numeric Reference Type

If the argument type in the SPVM Method definition was a Numeric Reference Type, the argument value must be a scalar reference. Otherwise, an Exception will be raised. 

# SPVM Method definition
package Foo {
  sub call_byte_ref : void ($num: byte&);
  sub call_short_ref : void ($num: short&);
  sub call_int_ref : void ($num: int&);
  sub call_long_ref : void ($num: long&);
  sub call_float_ref : void ($num: float&);
  sub call_double_ref : void ($num: double&);
}

# Call from Perl
my $num_byte = 23;
Foo->call_byte_ref(\$num_byte);

my $num_short = 23;
Foo->call_short_ref(\$num_short);

my $num_int = 23;
Foo->call_int_ref(\$num_int);

my $num_long = 23;
Foo->call_long_ref(\$num_long);

my $num_float = 23;
Foo->call_float_ref(\$num_float);

my $num_double = 23;
Foo->call_double_ref(\$num_double);

If the argument type in the SPVM Method definition was a Multi Numeric Reference Type, the argument value is a hash reference reference and the key contains all Multi Numeric field names. is needed. Otherwise, an Exception will be raised.

If the argument type of the SPVM Method definition is a numeric array type, the Perl Array Reference is converted to the corresponding Perl SPVM::Data::Array object. The value of the element is The rule that converts the scalar value of Perl to the Numeric Type of SPVM Will be converted to. The argument is a string,

If the argument type of the SPVM Method definition is a byte[] value, the Perl decoded string is encoded in UTF-8 and represents byte[] Perl's SPVM::Data: Converted to a: Array object.

If the argument type of the SPVM Method definition is an object type and the value passed to the argument is an Undefined Value, it is converted to the SPVM Undefined Value.

If the argument type of the SPVM Method definition is a string compatible type and the value passed to the argument is a scalar value that is not a reference, it is encoded in UTF-8 and represents the SPVM byte[] value. Converts to a Perl SPVM::Data::Array object.

If the argument type of the SPVM Method definition is a string compatible array type and the value passed to the argument is Array Reference and the first element is a scalar value that is not a reference, SPVM byte[] Converted to a Perl SPVM::Data::Array object representing[]. If the element has an Undefined Value, it is converted to SPVM Undefined Value, otherwise it is encoded to UTF-8 and converted to SPVM byte[] value.

If the argument type of the SPVM Method definition is a byte[] value and the value passed to the argument is Array Reference, convert it to a Perl SPVM::Data::Array object that represents byte[]. Will be done. The element value is converted by the Rule to Convert Perl Scalar Data ​​to SPVM Numeric Value.

If the argument type of the SPVM Method definition is a short[] value and the value passed to the argument is Array Reference, convert it to a Perl SPVM::Data::Array object that represents a short[]. Will be done. The element value is converted by the Rule to Convert Perl Scalar Data ​​to SPVM Numeric Value.

If the argument type of the SPVM Method definition is int[] value and the value passed to the argument is Array Reference, convert it to a Perl SPVM::Data::Array object that represents int[] Will be done. The element value is converted by the Rule to Convert Perl Scalar Data ​​to SPVM Numeric Value.

If the argument type of the SPVM Method definition is a long[] type and the value passed to the argument is Array Reference, convert it to a Perl SPVM::Data::Array object representing long[]. Will be done. The element value is converted by the Rule to Convert Perl Scalar Data ​​to SPVM Numeric Value.

If the argument type of the SPVM Method definition is float[] value and the value passed to the argument is Array Reference, convert it to a Perl SPVM::Data::Array object that represents float[]. Will be done. The element value is converted by the Rule to Convert Perl Scalar Data ​​to SPVM Numeric Value.

If the argument type of the SPVM Method definition is double[] type and the value passed to the argument is Array Reference, convert it to a Perl SPVM::Data::Array object that represents double[]. Will be done. The element value is converted by the Rule to Convert Perl Scalar Data ​​to SPVM Numeric Value.

If the argument type of the SPVM Method definition is an object[] type and the value passed to the argument is Array Reference, convert it to a Perl SPVM::Data::Array object that represents object[]. Will be done. If the element value is an Undefined Value, it is converted to SPVM undefined, and if it is a non-reference scalar value, it is encoded to UTF-8 and converted to SPVM byte[] value. If it is SPVM::Data object, it will not be converted. Otherwise, an Exception will be raised.

Return Value Type Conversion

If the return value is a Numeric Type of SPVM, Rule to Convert the Numeric Type of SPVM to a scalar value of Perl It is converted to a Perl Scalar Data by.

If the return value is a SPVM Multi Numeric Type, it will be converted to a hash reference. The key is the SPVM Multi Numeric field name and the value is SPVM Numeric Value is converted to Perl Scalar Data. The value is converted to a Perl Scalar Data by the rule.

If the return value is an Undefined Value for the SPVM object type, it will be converted to a Perl Undefined Value.

If the return value is SPVM Array type(including generic object array type), it will be converted to the corresponding Perl SPVM::Data::Array object.

If the return value is an object type other than the SPVM Array type, it will be converted to the corresponding Perl SPVM::Data object.

Utility Functions

Get SPVM Exception - SPVM::exception

Gets the SPVM exception. If the string is not undef, it is considered as UTF-8 and is the decoded string. 

my $exception = SPVM::exception();

Set SPVM Exception - SPVM::set_exception

Sets the SPVM exception. The argument specifies the decoded string or undef. 

SPVM::set_exception("Aiu");
SPVM::set_exception(undef);

Get Number of Allocated Memory Blocks Count - SPVM::get_memory_blocks_count

you can use memory_blocks_count function to get the number of reserved memory blocks. 

my $count = SPVM::get_memory_blocks_count();

The SPVM runtime reserves memory from the heap when creating Object and creating new week references. The memory reserved by a single memory retrieval operation is called a memory block.

SPVM has a reference count GC, and usually you don't need to be aware of memory storage and release, but when you write a Method natively, you might want to make sure that there is no memory leak in your trial. 

# First Memory Blocks Count
my $start_memory_blocks_count = SPVM::get_memory_blocks_count();

# Processing
# ...

# Last Memory Blocks Count
my $end_memory_blocks_count = SPVM::get_memory_blocks_count();

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

Rule to Convert Perl Scalar Data to SPVM Numeric Value

The Rule to Convert Perl Scalar Data to SPVM Numeric Value are defined below.

Conversion Rule are written in C. SvIV and SvNV are functions defined in perlapi. int8_t, int16_t, int32_t, int64_t, float, double are the types defined in C99.

Convert Perl Scalar Data to SPVM byte value 

(int8_t)SvIV(perl_scalar_data)

Convert Perl Scalar Data to SPVM short value 

(int16_t)SvIV(perl_scalar_data)

Convert Perl Scalar Data to SPVM int value 

(int32_t)SvIV(perl_scalar_data)

Convert Perl Scalar Data to SPVM long value 

(int64_t)SvIV(perl_scalar_data)

Convert Perl Scalar Data to SPVM float value 

(float)SvNV(perl_scalar_data)

Convert Perl Scalar Data to SPVM double value 

(double)SvNV(perl_scalar_data)

Rule to Convert SPVM Numeric Value to Perl Scalar Data

The Rule to Convert Perl Scalar Data to SPVM Numeric Value are defined below.

Conversion Rule are written in C. newSViv and newSVnv are functions defined in perlapi. int8_t, int16_t, int32_t, int64_t, float, double are the types defined in C99.

Convert SPVM byte value to Perl Scalar Data 

int8_t spvm_byte_value;
newSViv(spvm_byte_value)

Convert SPVM short value to Perl Scalar Data 

int16_t spvm_short_value;
newSViv(spvm_short_value)

Convert SPVM int value to Perl Scalar Data 

int32_t spvm_int_value;
newSViv(spvm_int_value)

Convert SPVM long value to Perl Scalar Data 

int64_t spvm_long_value;
newSViv(spvm_long_value)

Convert SPVM float value to Perl Scalar Data 

float spvm_float_value;
newSVnv(spvm_float_value)

Convert SPVM double value to Perl Scalar Data 

double spvm_double_value;
newSVnv(spvm_double_value)

1 POD Error

The following errors were encountered while parsing the POD:

Around line 979:

Non-ASCII character seen before =encoding in '​​to'. Assuming UTF-8