NAME

Inline::SLang::Array - Support for arrays

SYNOPSIS

use Inline 'SLang';

# you can send arrays to S-Lang
print_in_slang( [ 1, 2, 4 ] );

# and get them back from S-Lang
$aref = get_from_slang();
print "The array contains: " . join(',', @$aref) . "\n";

__END__
__SLang__

define print_in_slang (arr) {
  variable adims, ndim, atype;
  ( adims, ndim, atype ) = array_info(arr);
  vmessage( "Array has type=%S with %d dims", atype, ndim );
  foreach ( arr ) {
    variable val = ();
    vmessage( "  Value = %s", string(val) );
  }
}
define get_from_slang() { return ["a string","another one","3"]; }

The output of this code - which can be found in the source-code distribution as examples/arrays.pl - is:

Array has type=Integer_Type with 1 dims
  Value = 1
  Value = 2
  Value = 4
The array contains: a string,another one,3

DESCRIPTION

The philosophy behind arrays in Perl and S-Lang is somewhat different, which makes converting arrays between the two languages a bit more awkward than with many of the other data types.

We admit three different array representations in Perl: Perl's array references; as an Array_Type object (this class is a part of the Inline::SLang package); and as a piddle (the fundamental object of the Perl Data Language which is the suggested method to analyze large numeric arrays in Perl). Before discussing this I want to talk about going the "other way".

Things to remember when converting arrays to S-Lang

Consider the following Perl array reference:

[ [ 2, 1 ], [ 4, 5 ], [ 8, 9 ] ]

This could be represented in S-Lang as one of the following arrays:

Integer_Type [3,2]
Double_Type  [3,2]
String_Type  [3,2]
Array_Type   [3]
Any_Type     [3]

Note that this does not match the way that PDL represents array (which would consider this to be a 2x3 array). This may cause issues when support for piddles is added.

Admittedly most of these are unlikely, but the point is that they are all valid representations, which makes automatically converting such an item to S-Lang awkward.

As discussed below it is possible to provide extra information (the type and/or dimensionality of the array) to help the conversion - using an Array_Type object or the Inline::SLang::SL_array() function - but hopefully the guesses the code makes will be sufficient.

How do we guess the array?

If the array is stored as a piddle or an Array_Type object then the computer can find out the information without guessing, so the following is only relevant when an array reference is used.

When given an array reference, the code looks at the first element to decide what type of array it is: if it is an array reference then we have a multi-dimensional array and the process is repeated until we reach a value. So, in the example above the "2" would be used to determine the type of the array - so it should come out as Integer_Type - and the array dimensions are taken to be [3,2].

How to confuse the array conversion (by data type)

Since the code only looks at the first element in the array to guess the type it is not too hard to come across arrays that will cause the code to croak with some bizarre message from S-Lang. For instance:

[ 1, 2, "a string" ]

will cause a problem since it is assumed to be an Integer_Type [3] array, which is fine for the first two elements but not for the last one.

The code could be updated so that it checks all elements in the array and finds the most suitable type and dimensionality; however, this could be a large performance hit for large arrays and the current advice is to use one of the techniques we describe below.

How to confuse the array conversion (by array size)

The code assumes that the array dimensions it calculates hold for all elements. If they don't then you will see error messages (quite possibly strange ones at that). As an example,

[ [ 2, 1 ], [1] ]

is guaranteed not to be liked by the code; on my machine it dislikes it so much that it causes a segmentation fault.

How can I help?

If you know the array size and/or type then you can use the Inline::SLang::sl_array() function to help the code out. As an example (see also examples/array_help.pl):

use Inline 'SLang' => Config => EXPORT =>
     [ 'sl_array', 'Integer_Type' ];
use Inline 'SLang';

my $aref = [ 1, 3, 2 ];
foo( $aref );
foo( sl_array( $aref, "Int_Type" ) );
foo( sl_array( $aref, [3] ) );
foo( sl_array( $aref, [3], Integer_Type() ) );

__END__
__SLang__

define foo(x) { vmessage("Array has type: %S", _typeof(x) ); }

which produces four lines saying

Array has type: Integer_Type

Note that I snuck in an example of using an automatically-generated wrapper around the DataType_Type constructor - the Integer_Type() function in the last call to foo().

Unfortunately you can not use sl_array() to typecast the array: at least not at the moment. If you replace Int_Type with String_Type in the above then you will come across the following error message

S-Lang Error: Type Mismatch: Unable to typecast Integer_Type to String_Type

even though Perl can happily treat 1 as an integer or a string. Suggestions on how to handle this case are welcome.

The sl_array() function is actually a wrapper around the constructor call for the Array_Type class which tries to guess the array type and size if they have not been supplied.

Things to remember when converting arrays to Perl

There are three different ways that a S-Lang array can be represented in Perl:

As a reference to a Perl array.
As a piddle (see the Perl Data Language documentation) for numeric types.

At the moment this option is NOT IMPLEMENTED. It will be soon, once I start thinking about the sizes of datatypes. What fun.
As an Array_Type object.

In most cases the first two representations are likely to be the ones you use; the use of an Array_Type object is only needed when it is hard for the code to guess the type/dimensionality of an array.

The Inline::SLang::sl_array2perl() function is used to define how S-Lang arrays are converted to Perl, and to find out what the current conversion system is. This function is described in Inline::SLang.

Example

use Inline 'SLang' => Config => EXPORT => [ 'sl_array2perl' ];
use Inline 'SLang';

# use array references for all S-Lang arrays
sl_array2perl(0);
my $a0 = get_array();
print "Array returned as an " . ref($a0) . "\n";
print "  dim size = " . (1+$#$a0) . "\n";

# use Array_Type for all S-Lang arrays
sl_array2perl(1);
my $a1 = get_array();
print "Array returned as an " . ref($a1) . "\n";
my ( $dims, $ndim, $atype ) = $a1->array_info();
print "  dim size = $$dims[0]\n";
print "  type     = $atype\n";

# use a piddle (assumes Inline::SLang::sl_have_pdl() == 1)
sl_array2perl(2);
my $a2 = get_array();
print "Array returned as an " . ref($a1) . "\n";
print "  dim size = " . $a2->getdims(0) . "\n";
print "  type     = " . $a2->type . "\n";

__END__
__SLang__

define get_array() { return [ 14.0, 3 ]; }

This example is available as examples/array_conversion.pl in the source distribution. When run this outputs:

Array returned as an ARRAY
  dim size = 2
Array returned as an Array_Type
  dim size = 2
  type     = Double_Type
Error: sl_array2perl() can only be sent an integer between 0 and 1 (inclusive) at examples/array_conversion.pl line 21.

The error message is because (as of version 0.11) we do not support PDL. We will do soon.

THE ARRAY_TYPE CLASS

The Perl Array_Type class stores the datatype and dimensionality of an array along with the data. In most cases this information is not needed so you should stick with using array references (or piddles) since it's much easier, but there are times when it can come in handy.

The Array_Type class inherit the default methods of all the Inline::SLang objects, namely:

typeof()

This returns Array_Type as a DataType_Type object. See the _typeof() method below to find the datatype used to store the data.
stringify()

This returns the string "Array_Type".
is_struct_type()

This returns 0.

As with the other object classes these methods can only be called using the $object->method( args ) syntax. There are also a number of additional methods for this class:

new( datatype, dims [, data ] )

The constructor takes the datatype of the array - as either a string or a DataType_Type object - and an array reference containing the size of the array and returns an Array_Type object. If a third argument is supplied then it is taken to be an array reference containing the data to be stored in the array. Note that in this case we just copy the array reference and not the actual data stored in this array. This means that you can change the data stored in the object: useful but can cause bizarre behaviour for the unwary.
```
my $arr1 = Array_Type->new( "Int_Type", [3,2] );
my $arr2 = Array_Type->new(
             "String_Type", [3],
             [ "a string", "another string", "boo" ]
           );
```
There is no sanity checking of the input values; if they do not agree then something strange will happen at some point during the execution of the progam.

An alternative way to create an Array_Type object is to use the Inline::SLang::sl_array() function, which is described in the Inline::SLang document. This has the advantage that it will try and guess the type and/or dimensionality of the array if you do not specify it.
_typeof()

Returns - as a DataType_Type object - the class of the data stored in the array.
```
my $arr1 = Array_Type->new( "Int_Type", [3,2] );
my $type = $arr1->_typeof();
```
array_info()

Mimics the S-Lang array_info() function (slightly more efficient than usng the S-Lang version). The array dimensions are returned as a Perl array reference and the datatype as a DataType_Type object.
```
my $arr1 = Array_Type->new( "Int_Type", [3,2] );
my ( $dims, $ndims, $type ) = $arr1->array_info();
print "Num of dims = $ndims and type = $type\n";
print "Dims = [ " . join( ", ", @$dims ) . " ]\n";
```
get( coord1, ..., coordN )

Returns the data value stored at the given location.
```
my $arr1 = Array_Type->new( "Int_Type", [3,2] );
my $val  = $arr1->get(1,0);
```
set( coord1, ..., coordN, newval )

Sets the data value stored at the given location to the specified value. It returns this value.
```
my $arr1 = Array_Type->new( "Int_Type", [3,2] );
$arr1->set(1,0,-43);
```
Note that there is no check made that the datatype of the new value matches that of the array. You will find out about this when you try to convert the array to S-Lang. Probably with a rather unfriendly message.
toPerl()

Since the accessor functions described above are very limited, the toPerl() can be used to get an array reference to the actual data. This can then be used as you would any other Perl array reference. If you change the array size then you are going to make the object unhappy, so take care.
```
my $arr1 = Array_Type->new( "Int_Type", [3,2] );
my $dref = $arr1->toPerl();
$$dref[1][0] = -4;
```

Further methods could be added to improve the array access - such as the resize S-Lang function and means of accessing array slices - but this is unlikely to happen since PDL has a much richer set of operations (although they only work for numeric types) or you can do the array processing in S-Lang.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)