NAME

Inline::SLang::Assoc - Support for associative arrays

SYNOPSIS

use Inline 'SLang';

# you can send hash references to S-Lang
print_in_slang( { a => 23, "b b" => "foo" } );

# and get them back from S-Lang
$href = get_from_slang();
print "The assoc array contains:\n" .
  join( "", map { "\t$_ => $$href{$_}\n"; } keys %$href );

__END__
__SLang__

define print_in_slang (assoc) {
  message( "SLang thinks you sent it an assoc. array with:" );
  foreach ( assoc ) using ( "keys", "values" ) {
    variable k, v;
    ( k, v ) = ();
    vmessage( " key %s = %S", k, v );
  }
}
define get_from_slang() {
  variable x = Assoc_Type [String_Type];
  x["a key"] = "a value";
  x["another key"] = "another value";
  return x;
}

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

SLang thinks you sent it an assoc. array with:
 key a = 23
 key b b = foo
The assoc array contains:
        another key => another value
        a key => a value

DESCRIPTION

Since S-Lang's associative arrays are similar to Perl's associative (aka "hash") arrays then the conversion is fairly easy. It is not completely trivial since S-Lang's assoc. arrays know about the datatype of the variables they contain.

When a S-Lang associative array is sent to Perl, it is converted into a Assoc_Type Perl object. As discussed below, this behaves just like a hash reference with a few additional method calls.

When sending an associative array to a S-Lang function from Perl, two different (but not very different) techniques can be used:

• As a hash reference.

  When converted to S-Lang, it will appear as a Assoc_Type [Any_Type] array since the code does not try to guess the type based on the stored values. This could be a future enhancement if the current approach turns out to be unsatisfactory (Any_Type variables can be a bit of a pain to work with in S-Lang).

  Or we could assume a default type of Int_Type, which would match S-Lang's approach.

• As a Perl Assoc_Type object.

  Whilst it involves more typing to set up, you are guaranteed that the datatype is correct.

THE ASSOC_TYPE CLASS

The Perl Assoc_Type class stores the datatype of the array along with the data. Once you have created the object you can use it as a hash reference to get and set fields in the array. As described below the object also has a number of methods based on the S-Lang language which provides similar functionality.

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

• typeof()

  This returns Assoc_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 "Assoc_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 )

  The constructor takes the datatype of the asociative array - as either a string or a DataType_Type object - and returns an Assoc_Type object.

  The return value can be treated as a hash reference, or you can use some of the other methods described below to manipulate the contents of the array.

  my $assoc = Assoc_Type->new( "String_Type" );
  $$assoc{foo} = "hello";
  $$assoc{baz} = "hi there";
  while ( my ($k,$v) = each %$assoc ) {
    print "  key $k has a value of $v\n";
  }

  The order of keys returned by the Perl hash iterators - such as each, keys, and values - is not guaranteed to match that of S-Lang's iterators such as assoc_get_keys.

• _typeof()

  Returns - as a DataType_Type object - the class of the data stored in the array. This is unlike the S-Lang _typeof command which just returns Assoc_Type.

  my $assoc = Assoc_Type->new( "Complex_Type" );
  my $type  = $assoc->_typeof();

• length()

  Returns the number of keys in the associative array.

  my $assoc = Assoc_Type->new( "Double_Type" );
  $$assoc{"foo"} = 1.0; $$assoc{"bar"} = 3.0e6;
  print "Number of keys = ", $assoc->length, "\n";

• get_keys()

  Returns, as an array reference, a list of the keys of the asociative array. It is essentially S-Lang's assoc_get_keys() routine although it is implemented using Perl's keys routine. This means that the order of the returned keys is not guaranteed to match that of S-Lang's assoc_get_keys().

  my $assoc = Assoc_Type->new( "Double_Type" );
  $$assoc{"foo"} = 1.0; $$assoc{"bar"} = 3.0e6;
  foreach my $k ( $assoc->get_keys ) {
    print "  key $k has value $$assoc{$k}\n";
  }

  There is no advantage to using this method over Perl's keys %$assoc.

• get_values()

  Returns, as an array reference, a list of the values of the asociative array. It is essentially S-Lang's assoc_get_values() routine although it is implemented using Perl's values routine. This means that the order of the returned keys is not guaranteed to match that of S-Lang's assoc_get_values().

  my $assoc = Assoc_Type->new( "Double_Type" );
  $$assoc{"foo"} = 1.0; $$assoc{"bar"} = 3.0e6;
  foreach my $v ( $assoc->get_values ) {
    print "  array contains $v\n";
  }

  There is no advantage to using this method over Perl's values %$assoc.

• key_exists( $key )

  Returns 1 if the key exists in the associative array and 0 otherwise. It is essentially S-Lang's assoc_key_exists() routine.

  my $assoc = Assoc_Type->new( "Double_Type" );
  $$assoc{"foo"} = 1.0; $$assoc{"bar"} = 3.0e6;
  print "foo exists\n" if $assoc->key_exists("foo");

  There is no advantage to using this method over Perl's exists $$assoc{$key}.

• delete_key( $key )

  Removes the key from the associative array. It is essentially S-Lang's delete_key() routine.

  my $assoc = Assoc_Type->new( "Double_Type" );
  $$assoc{"foo"} = 1.0; $$assoc{"bar"} = 3.0e6;
  print "foo exists\n" if $assoc->key_exists("foo");

  There is no advantage to using this method over Perl's delete $$assoc{$key}.

• get_value( $key )

  Returns the value for the given key.

  my $assoc = Assoc_Type->new( "Double_Type" );
  $$assoc{"foo"} = 1.0; $$assoc{"bar"} = 3.0e6;
  my $val = $assoc->get_value( "foo" );

  There is no advantage to using this method rather than Perl's $$assoc{$key}.

• set_value( $key, $val )

  Sets the given key to the supplied value.

  my $assoc = Assoc_Type->new( "Double_Type" );
  $$assoc{"foo"} = 1.0; $$assoc{"bar"} = 3.0e6;
  $assoc->set_value( "foo", 44.1 );

  There is no advantage to using this method over Perl's $$assoc{$key}.

SEE ALSO

Inline::SLang::Array, Inline::SLang, Math::Complex, PDL