"Sputnik" help  
Sputnik Help
// Ones without a Key (they only get Value)
foreach( <scope> in <iterable> <variable> from <start> )
{
statements
...
}
foreach( <scope> in <iterable> <variable> from <start> to <end> )
{
statements
...
} // Ones that get the Key and Value foreach( <scope> <key> => <scope> <value> in <iterable> )
{
statements
...
}
foreach( <scope> <key> => <scope> <value> in <iterable> from <start> )
{
statements
...
}
foreach( <scope> <key> => <scope> <value> in <iterable> from <start> to <end> )
{
statements
...
} // Regex foreach( <scope> in <value-regex-match> from <start> )
{
statements
...
}
foreach( <scope> in <value-regex-match> from <start> to <end> )
{
statements
...
}

Description

The foreach loop gives Sputnik an easy way to iterate over arrays, strings, binary and other things.

It will ignore any invalid input with no errors or warnings.

Parameters

<scope>

Optional; The scope to create temp variables in either my, global or you can omit this part.

Default: any by omitting the scope you are setting it to any what this means is it will try set it to any available variable with that starting with local then global if that fails it will try create a local if that fails it will try create a global.

<variable> The variable to store the temp data in as it is extracted from the <iterable> sometimes a variable isn't even used and a List() is used instead etc make sure to read the examples to see that.
<iterable> The Array, String or an Object that can be iterated over.
<start> Optional; A start position to begin the loop at. eg. if you set this to 4 it will skip the first 4 elements (counting 0).
<end> Optional; A end position to stop the loop at. eg. if the end is set to 5 it will stop on the 6th element (counting 0).
<key> This is a variable to store the Key of an Array in as it is being iterated over.
<value> This is a variable to store the Value of an Array in as it is being iterated over.

Remarks

Foreach statements may be nested.

The foreach loop in Sputnik provides a convenient way to iterate over arrays, strings, binary data, and other iterable objects. It allows you to extract values from the iterable and perform operations on them within a loop.

The foreach loop supports different variations based on the type of iteration you need. It can iterate over an iterable object without extracting the key or value, or it can iterate over an iterable object and simultaneously extract both the key and value.

To use the foreach loop, you provide the necessary parameters, such as the scope, variable name to store the extracted value, the iterable object, and optional start and end positions for the iteration. Additionally, you can specify a key variable to store the key when iterating over arrays with key/value pairs.

The foreach loop allows for nested loops and gracefully handles invalid input without producing errors or warnings.

When using the foreach loop with arrays, it iterates over each element of the array. For strings, it iterates over each character. When iterating over numbers, each digit is treated as a separate iteration. Binary data can also be iterated over, providing access to individual bytes.

Using the from parameter, you can specify a start position to begin the loop, skipping a certain number of elements or characters. The to parameter allows you to set an end position to stop the loop.

In some cases, you may want to extract key/value pairs from an array. By using the key and value variables, you can access the key and value of each element during iteration.

The foreach loop is particularly useful when working with nested arrays or using the List statement to unpack values from nested arrays.

It's important to note that modifying an array while iterating over it is generally not recommended, as it can lead to unexpected behavior and code complexity.

The foreach loop provides flexibility and simplicity in iterating over various data structures, making it a valuable tool for handling different types of iterations

A few things to keep in mind:

If the iterable contains an array the loop will cycle through each element in the array or otherwise iterable object.

If the iterable contains a string or numbers it will cycle through each char.

It is a bad idea to try edit the array while you are loop through it (although Sputnik was designed to handle that it is still not advisable as it makes the code very confusing).

Related

Loop Statements
Continue Statement
Redo Statement
Break Statement

Example

Due to how complex the Foreach loop is there will be a few additional sections for each unique type of the stuff you can iterate over

Make sure to read all of them so you are aware of what the Foreach loop can do.

Content Of Examples

Using on Array Values

Cycle through an array values:

my $a = array("cat", "dog", "fox");
foreach (my $i in $a)
{
    say $i;
}

// PRINTS
// cat
// dog
// fox

Using on Array with Key/Value pairs

Cycle through an array:

my $array = array(
        "One" => 100,
        "Two" => 200,
        "Three" => 300
        );
 
Foreach (my $key => my $value in $array)
{
    say "Key '$key' | Value '$value'";
}
// PRINTS
// Key 'One' | Value '100'
// Key 'Two' | Value '200'
// Key 'Three' | Value '300'

Using the Start:

my $array = array(
        "One" => 100,
        "Two" => 200,
        "Three" => 300
        );
 
Foreach (my $key => my $value in $array from 1)
{
    say "Key '$key' | Value '$value'";
}
// PRINTS
// Key 'Two' | Value '200'
// Key 'Three' | Value '300'

Using the Start and To:

my $array = array(
        "One" => 100,
        "Two" => 200,
        "Three" => 300
        );
 
Foreach (my $key => my $value in $array from 1 to 1)
{
    say "Key '$key' | Value '$value'";
}
// PRINTS
// Key 'Two' | Value '200'

It is also possible to use a For loop to do basic actions of a Foreach loop but it doesnt support everything it is only included for a shorthand for certain tasks:

my $a = ["cat", "dog", "fox"];

for (my $i in $a)
{
    say $i;
}

for (my $i in Range(5))
{
    say $i;
}

// PRINTS
// cat
// dog
// fox
// 0
// 1
// 2
// 3
// 4
// 5

Using on Arrays

Cycle through an array of numbers:

my $array = array(2, 4, 6, 8, 10);
foreach(my $item in $array)
{
    say "Value is $item";
}
// PRINTS
// Value is 2
// Value is 4
// Value is 6
// Value is 8
// Value is 10

Cycle through an array of strings:

my $array = array("Cat", "Meow", "Dog", "Woof", "Sheep", "Kitten", "Lion");
foreach(my $item in $array)
{
    say "Value is $item";
}
// PRINTS
// Value is Cat
// Value is Meow
// Value is Dog
// Value is Woof
// Value is Sheep
// Value is Kitten
// Value is Lion

You can also referance when using arrays using the pointer & operator for example:

// make a new array to test on
my $array = array(2, 4, 6, 8, 10);
// We add a & before the $item to cause it to use it
// as a pointer instead of just copying the variable
foreach(&$item in $array)
{
    // We surround the $item in { } causing a code block
    // where Sputnik will use whats inside the { } as physical code
    // then we place a * before the $ causing its pointer to get 
    // resolved into a real variable if we dont do this you will
    // just see the REF and finally we place a \ before the $
    // causing it to become a literal $ and not part of a variable
    // the { } block will resolve it
    say "Value is {*\$item}"; // Prints 2 4 6 8 10
    *$item *= 2;
    // notice the * before $item? this tells Sputnik
    // to resolve the Pointer and get the real value
    // then we can modify it
}
// PRINTS
// Value is 2
// Value is 4
// Value is 6
// Value is 8
// Value is 10

foreach(my $item in $array)
{
    say "Value is $item"; // Prints 4 8 12 16 20
}
// PRINTS
// Value is 4
// Value is 8
// Value is 12
// Value is 16
// Value is 20

See the & before $item on the first loop? This causes $item to actually link to the real element inside the array so changing $item will change the item in the array.

This can be seen by printing the array after changing it in the example.

Note - This works on most things too such as Strings and Binary.

Using on Strings

Here we cycle through each char in a string:

my $str = "Hello World";
foreach(my $char in $str)
{
    say "Char is $char";
}
// PRINTS
// Char is H
// Char is e
// Char is l
// Char is l
// Char is o
// Char is  
// Char is W
// Char is o
// Char is r
// Char is l
// Char is d

Loop through a string and print each char but do it with a ref so we can modify the string in place:

my $str = "Hello"; 
say "Printing string";
foreach(&$c in $str)
{
    say *$c; // Resolve teh ref
    *$c = AscW(*$c) + 10; // Set the char
} 
say "Printing modified string";
foreach(my $c in $str)
{
    say $c;
}
// PRINTS
// Printing string
// H
// e
// l
// l
// o
// Printing modified string
// R
// o
// v
// v
// y

Are you trying use a Foreach on a string but getting Char data type when you want String for each char then see this example:

// Define a string
my $str = "Hello";
// Loop through the string as chars
// notice each one is a char data type
// this might cause problems if you expect
// to use it as a string see below for solution
foreach(my $c in $str)
{
    say vardump($c);
}
// Prints
// char'H'
// char'e'
// char'l'
// char'l'
// char'o'
 
// Solution? Cast to string
foreach(my $c in $str)
{
    $c = (string)$c;
    say vardump($c);
}
// Prints
// string(1) "H"
// string(1) "e"
// string(1) "l"
// string(1) "l"
// string(1) "o"

Using on Numbers

Here we cycle through each letter in a float:

my $num = 777.42;
foreach(my $char in $num)
{
    say "Char is $char";
}
// PRINTS
// Char is 7
// Char is 7
// Char is 7
// Char is .
// Char is 4
// Char is 2

Here we cycle through each letter in an integer:

my $num = 1337;
foreach(my $char in $num)
{
    say "Char is $char";
}
// PRINTS
// Char is 1
// Char is 3
// Char is 3
// Char is 7

Using the Binary

Here we cycle through binary data:

my $binary = Pack("ifz0", (int)100, (float)777.42, "Hello");
foreach(my $byte in $binary)
{
    say  
            "Index '" . DecPad($byte, 3) . "' " . 
            "Dec '$byte' " .  
            "Hex '" . Hex($byte) . "' " . 
            "Char '" . Chr($byte) . "'"
            ;
}
// PRINTS
// Index '100' Dec '100' Hex '64' Char 'd'
// Index '000' Dec '0' Hex '' Char ' '
// Index '000' Dec '0' Hex '' Char ' '
// Index '000' Dec '0' Hex '' Char ' '
// Index '225' Dec '225' Hex 'E1' Char 'á'
// Index '090' Dec '90' Hex '5A' Char 'Z'
// Index '066' Dec '66' Hex '42' Char 'B'
// Index '068' Dec '68' Hex '44' Char 'D'
// Index '072' Dec '72' Hex '48' Char 'H'
// Index '101' Dec '101' Hex '65' Char 'e'
// Index '108' Dec '108' Hex '6C' Char 'l'
// Index '108' Dec '108' Hex '6C' Char 'l'
// Index '111' Dec '111' Hex '6F' Char 'o'

Using the Start

Using Start:

my $a = array("Zero", "One", "Two", "Three", "Four", "Five", "Six");
foreach(my $c in $a from 1)
{
    say $c;
}
// PRINTS
// One
// Two
// Three
// Four
// Five
// Six

Using the Start and To

Using Start and To:

my $a = array("Zero", "One", "Two", "Three", "Four", "Five", "Six");
foreach(my $c in $a from 1 to 3)
{
    say $c;
}
// PRINTS
// One
// Two
// Three

Using the Foreach loop with the List() statement

Example of unpacking nested arrays with List():

my $array = array(
    array(1, 2),
    array(3, 4)
);
 
foreach (my list($a, $b) in $array) 
{
    // $a contains the first element of the nested array,
    // and $b contains the second element.
    say "A: $a; B: $b";
}
// Prints
// A: 1; B: 2
// A: 3; B: 4

Another example of unpacking nested arrays with List():

my $array = array(
    array(1, 2, 3, 4),
    array(5, 6, 7, 8)
);
 
foreach (my list($a, $b, $c, $d) in $array) 
{
    // $a contains the first element of the nested array,
    // and $b contains the second element.
    say "A: $a; B: $b; C: $c; D: $d";
}
// Prints
// A: 1; B: 2; C: 3; D: 4
// A: 5; B: 6; C: 7; D: 8

Yet another example of unpacking nested arrays with List() however this one only works if there is only 1 element in each array (key, value) and it must be a string and not numeric (like normal arrays):

my $array = array(
    array("Cat" => "Meow"),
    array("Dog" => "Woof"),
    array("Foo" => "Bar")
);
 
foreach (my list($key, $value) in $array) 
{
    // $a contains the first element of the nested array,
    // and $b contains the second element.
    say "Key: $key | Value: $value";
}
// Prints
// Key: Cat | Value: Meow
// Key: Dog | Value: Woof
// Key: Foo | Value: Bar

Example of using List() with an array that contains no nested arrays:

my $a = array("One", "Two", "Three", "Four", "Five", "Six");
foreach(my list($k, $j) in $a)
{
    say "$k - $j";
}
// Prints
// One - Two
// Three - Four
// Five - Six

Same as above but more arguments to extract:

my $a = array("One", "Two", "Three", "Four", "Five", "Six");
foreach(my list($k, $j, $l) in $a)
{
    say "$k - $j - $l";
}
// Prints
// One - Two - Three
// Four - Five - Six

Of course unpacking only one argument is the same as a normal Foreach:

my $a = array("One", "Two", "Three", "Four", "Five", "Six");
foreach(my list($k) in $a)
{
    say "$k";
}
// Prints
// One
// Two
// Three
// Four
// Five
// Six

You can nest lists inside lists like then this:

// my $arr = array( // expanded its easier to see what its doing
//              array(1, array(2, 3)),
//              array(4, array(5, 6))
//          );
my $arr = array(array(1, array(2, 3)), array(4, array(5, 6)));
foreach(my list($x, list($y, $z)) in $arr)
{
    say "$x - $y - $z";
}
// PRINTS
// 1 - 2 - 3
// 4 - 5 - 6
During each iteration, the values are extracted from the subarrays and printed using the say statement. The output displays the values of $x, $y, and $z for each iteration, separated by hyphens.

This demonstrates how nested arrays can be accessed and iterated over in Sputnik using the list destructuring syntax in a foreach loop.

Example of using the Regex Match Operator part on a String:

// Use foreach to return matched captures from a string
my $a = "One9-Two44-Three-Four-Five56-Six";
foreach($v in $a =~ m/(\d+)/g) // use g flag to match all
{
    say "Str " . $v;
}
// Prints
// Str 9
// Str 44
// Str 56

Example of using the Regex Match Operator part on an Array:

// Use foreach to return matched captures from an array
my $a = array("One1", "Two77", "Three", "Four", "Five22", "Six");
foreach($v in $a =~ m/(\d+)/) // g flag not needed each element is treated
{
    say "Array " . $v;
}
// Prints
// Array 1
// Array 77
// Array 22


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