"Sputnik" help  
Sputnik Help
Language Reference - Datatypes - Arrays (Dictionary)

Arrays (Dictionary)

In Sputnik an array is both an array and a dictionary in one (at the same time). The key in a dictionary is case sensitive.

A Dictionary is used to store variables under a key name this is useful for creating a kind of key/value system and is more useful then arrays in situations where you need this.

In Sputnik, This kind of array is often called an associative array, also known as a dictionary, allows you to store and access elements using key-value pairs. Unlike list arrays that use numeric indices, associative arrays use string keys for indexing and retrieval.

(Its worth noting a variable can contain both an array and a dictionary at the same time. This is because an array and an dictionary share the same data structure the arrays indexes are simply just keys in the dictionary. Sputnik will NOT automatically reorder the dictionary when accessed however it will remain in the order it was created in (and the order items were added/removed however you can trigger a reorder using the Order function however this will only order the numeric keys to order the string keys you should use KSort.).

In Sputnik, the automatic creation of array keys ensures a dynamic and flexible approach when working with nested arrays. When accessing elements using a chain of keys like $a[1][2][3][4], Sputnik dynamically generates the intermediate arrays, ensuring that each level exists as it traverses the structure. This feature is particularly useful when the right-hand side involves operators with assignment (= or x= etc), such as addition (+=), subtraction (-=), or multiplication (*=) and other similar types.

This chain creation mechanism guarantees the existence of elements in the array. For instance, when performing an operation like $a[7] += 10;, the behavior depends on the content of element 7. If element 7 is an array with zero elements, the operation will transform it into a numeric value, effectively changing [7] to 10. On the other hand, if element 7 is already an array with one or more elements, the += 10 operation will be applied to each of these elements individually.

This behavior signifies that operations like += and similar operators, when applied to an empty array, result in the array being transformed into a numeric value. Conversely, if the array already contains elements, these operators are applied to the existing elements, offering a versatile approach that accommodates a range of use cases.

This explains the above:

my $a = array(3 => 4); // Initialize array with an element at key 3
my $b = 5;             // Key for incrementing
my $c = 10;            // Key for assignment and incrementing
my $d = 8;             // Nested array key
$a[$b]++;              // Increment element at key 5
$a[$c] = array(9);     // Assign an array with a single element to key 10
$a[$c] += 10;          // Increment each element in the nested array at key 10
$a[8][$d] = 15;        // Assign a value to a nested array at key 8 and nested key 8
printr $a;             // Display the resulting array structure
// PRINTS
// Array
// (
//     [3] => 4
//     [5] => 1
//     [10] => Array
//         (
//             [0] => 19
//         )
//     [8] => Array
//         (
//             [8] => 15
//         )
// )


my $a = array(3 => 4); // Initialize array with an element at key 3
my $b = 5;             // Key for incrementing
my $c = 10;            // Key for assignment and incrementing
$a[$b]++;              // Increment element at key 5
$a[$c] = array();      // Assign an empty array to key 10
$a[$c] += 10;          // Transform the empty array at key 10 into a numeric value
printr $a;             // Display the resulting array structure
// PRINTS
// Array
// (
//     [3] => 4
//     [5] => 1
//     [10] => 10
// )

Heres a brief example:

my $array = array("One" => "cat", "Two" => "dog", "Three" => "mouse");
say "array : " . $array;
say "array[one] : " . $array["One"];
say "array[two] : " . $array["Two"];
say "array[three] : " . $array["Three"];
// PRINTS
// array : {ARRAY;Elements:3}
// array[one] : cat
// array[two] : dog
// array[three] : mouse

Arrays can be made using [] syntax instead of using array() like so:

my $array = ["Cat", "Dog"];
printr $array;
my $array = ["One" => "cat", "Two" => "dog", "Three" => "mouse"];
printr $array;

// PRINTS
// Array
// (
//     [0] => Cat
//     [1] => Dog
// )
// Array
// (
//     [One] => cat
//     [Two] => dog
//     [Three] => mouse
// )
Just something to keep in mind however array() syntax will often be used in examples to make it easier to understand what's happening.

You can also add more elements to the dictionary using the .= example:

my $array = array("One" => "cat", "Two" => "dog", "Three" => "mouse");
$array .= array("Four" => "woman", "Five" => "man");
say "array : " . $array;
say "array[one] : " . $array["One"];
say "array[two] : " . $array["Two"];
say "array[three] : " . $array["Three"];
say "array[four] : " . $array["Four"];
say "array[five] : " . $array["Five"];
// PRINTS
// array : {ARRAY;Elements:5}
// array[one] : cat
// array[two] : dog
// array[three] : mouse
// array[four] : woman
// array[five] : man

A more simple approach to adding new values is to simply modify the value directly example:

my $array = array("One" => "cat", "Two" => "dog", "Three" => "mouse");
$array .= array("Four" => "woman", "Five" => "man");
$array["Six"] = "Sheep";
$array["One"] = "Not a cat!";
$array["Seven"] = "Donkey";
say "array : " . $array;
say "array[one] : " . $array["One"];
say "array[two] : " . $array["Two"];
say "array[three] : " . $array["Three"];
say "array[four] : " . $array["Four"];
say "array[five] : " . $array["Five"];
say "array[six] : " . $array["Six"];
say "array[seven] : " . $array["Seven"];
// PRINTS
// array : {ARRAY;Elements:7}
// array[one] : Not a cat!
// array[two] : dog
// array[three] : mouse
// array[four] : woman
// array[five] : man
// array[six] : Sheep
// array[seven] : Donkey

Example of Multi-dimensional dictionary:

my $array = array("One" => array(3, 4), "Two" => array(3 =>array(8, 9)));
$array['One'][0] = "Hello";
say "array : " . $array;
say "array['One'] :"  . $array['One'];
say "array['One'][0] : " . $array['One'][0];
say "array['One'][1] : " . $array['One'][1];
say "array['Two'][3] : " . $array['Two'][3];
say "array['Two'][3][0] : " . $array['Two'][3][0];
say "array['Two'][3][1] : " . $array['Two'][3][1];
// Note you can mix numeric/string index to create all kinds of MD arrays
// PRINTS
// array : {ARRAY;Elements:2}
// array['One'] :{ARRAY;Elements:2}
// array['One'][0] : Hello
// array['One'][1] : 4
// array['Two'][3] : {ARRAY;Elements:2}
// array['Two'][3][0] : 8
// array['Two'][3][1] : 9

You can use qw// to produce simple arrays for example:

// initialize 
my $array = array();
 
// populate the dictionary with a few elements
$array = qw(one two three four);
// print it
foreach(my $val in $array)
{
    say $val;
}
// PRINTS
// one
// two
// three
// four

You can also use the qww// to produce simple arrays (with string keys) example:

// initialize 
my $array = array();
 
// populate the dictionary with a few elements
$array = qww(1 one 2 two 3 three 4 four);
// print it
foreach(my $key => my $val in $array)
{
    say "$key => $val";
}
// PRINTS
// 1 => one
// 2 => two
// 3 => three
// 4 => four

// Alternatively you could use any symbol you want:
// $arr = qww(1 one 2 two 3 three 4 four);
// $arr = qww{1 one 2 two 3 three 4 four};
// Or any other two symbols to define the start and end point
// Or pretty much anything!

You can also spread the qww// out like so:

// initialize 
my $array = array();
 
// populate the dictionary with a few elements
$array = qww(
    Cat     Meow
    Dog     Woof
    Foo     Bar
);
 
# print the dictionary 
foreach(my $key => my $val in $array)
{
    print "$key => $val\n";
}

// PRINTS
// Cat => Meow
// Dog => Woof
// Foo => Bar

The key in a dictionary is case sensitive:

my $a = array();
$a["CAT"] = 10;
$a["cat"] = 20;
printr $a;
// PRINTS
// Array
// (
//     [CAT] => 10
//     [cat] => 20
// )

There is a lot more you can do with dictionaries including functions to make using them easier but that will be shown in another part of the this documentation.


Contact
Cheryl (uberfox@hotmail.com)
Homepage
http://ubersoft.org