push - push values into a variable

SYNOPSIS

<push $&var $values [$index]>

DESCRIPTION
The push function "pushes" (inserts) the given $values into $&var, at the index given by $index (default 0). Existing value(s), if any, are pushed to the right. The target variable must be specified with pass-by-reference syntax - i.e. $&var not $var - because it will be modified. Passing it by value would not let it be modified, which might otherwise be a silent bug - hence an error is generated if it is passed by value.

The effective $index value may be 0 through the number of pre-existing values of $var; the latter value would cause $values to be appended to $var. Explicit negative $index values are interpreted as offsets from the end of $var, e.g. -1 is the last value. Out of range or non-integral $index values are a run-time error. An empty-string or zero-values $index is taken as the default, which is 0.

DIAGNOSTICS
The push function has no effect on $ret.

EXAMPLE

<a name=main>
  <$var = "a" "b" "c">
  <$vals = "x" "y" "z">
  <push $&var $vals 1>
  After: <loop $var> $var </loop>

</a>

The output of the above example would be:

After: a x y z b c

CAVEATS
The push function is only valid in syntaxversion 8.

SEE ALSO
pop