Manipulating lists

The following operators manipulate lists. They can also be used to manipulate expressions, as shown in the next section, Manipulating Expressions. A summary of commands with explanations is in Functions for Manipulating Lists or Expressions.

Most of the function have two variants, one that produces a new value, and one that works in-place directly on its arguments. Here are some examples:

A = Remove( A, 3 ); // delete the third item in the list A, storing result in A

Remove From( A, 3 ); // delete the third item in the list A, in place

Show( A ); // A = {2, 3, 2, 1, 2, 1};

onetwo = Insert( {1}, 2 );  // {1,2}

Insert Into( B, {1, 2}, 4 ); // put 1,2 before the current 4th item

Show( B ); // B = {2, 3, 4, 1, 2, 1, 2, 1, 2, 1};

Note: If position is omitted in the Insert Into command, items are placed at the end of the list.

a = Shift( {1,2,3,4}, 1 ); // stores the list {2,3,4,1} in a

Shift Into( a, -1 );

Show( a ); // a = {1, 2, 3, 4};

b = Reverse( a ); // b is now {4,3,2,1}

Reverse Into( a ); // a is now {4,3,2,1}

Show( b ); // b = {2, 3, 4, 1};

s = Sort List( {1,4,2,5, -7.2, Pi(), -11, cat, apple, cake} );

Show( s ); // s = {-11, -7.2, 1, 2, 4, 5, apple, cake, cat, Pi()};

c = {5, pie, 2, Pi(), -2};

Sort List Into( c );

Show( c ); // c = {-2, 2, 5, Pi(), pie};

In-place operators

In-place operators are those that operate on lists or expressions directly. They have From or Into in their names (for example, Remove From and Insert Into). They do not return a result; you have to show the list to see the result. The first argument for an in-place operator must be an L-value. An L-value is an entity such as a global variable whose value can be set.

myList = {a, b, c, d};

Insert Into( myList, 2, 3 );

Show( myList );

myList = {a, b, 2, c, d}

These examples show how to use Insert Into and Remove From with nested lists:

a = {{1, 2, 3}, {"A", "B", "C"}};

Show( a );

a = {{1, 2, 3}, {"A", "B", "C"}}

Insert Into( a[1], 99, 1 );

Show( a );

a = {{99, 1, 2, 3}, {"A", "B", "C"}}

Remove From( a[1], 1 );

Show( a );

a = {{1, 2, 3}, {"A", "B", "C"}}

Not in-place operators

For the not-in-place operators, you must either state the list directly or else quote a name that evaluates to a list. Such operators do not have From or Into in their names. They return manipulated lists or expressions without changing the original list or expression given in the first argument.

myNewList = Insert( {a, b, c, d}, 2, 3 );

{a, b, 2, c, d}

oldList = {a, b, c, d};

newList = Insert( oldList, 2, 3 );

{a, b, 2, c, d}

Substituting

Substitute() and Substitute Into() merit further discussion. Both functions find all matches to a pattern in a list (or expression) and replace them with another expression. Each pattern must be a name. The arguments are evaluated before they are applied, so most of the time you must quote them with an Expr() function.

Substitute( {a,b,c}, Expr( a ), 23); // returns {23,b,c}

Substitute( Expr( Sine( x ) ), Expr( x ), Expr( y ) ); // returns Sine(y)

To delay evaluating an argument, use NameExpr instead of Expr:

a = {quick, brown, fox, jumped, over, lazy, dogs};

b = Substitute( a, Expr( dogs ), Expr( cat ) );

canine = Expr( dogs );

equine = Expr( horse );

c = Substitute( a, Name Expr( canine ), Name Expr( equine ) );

Show( a, b, c );

a = {quick,brown,fox,jumped,over,lazy,dogs}

b = {quick,brown,fox,jumped,over,lazy,cat}

c = {quick,brown,fox,jumped,over,lazy,horse}

Substitute Into does the same work, in place:

Substitute Into( a, Expr( dogs ), Expr( horse ) );

You can list multiple pattern and replacement arguments to do more than one replacement in a single step:

d = Substitute( a,

	Name Expr( quick ), Name Expr( fast ),

	Name Expr( brown ), Name Expr( black ),

	Name Expr( fox ), Name Expr( wolf )

);

{fast,black,wolf,jumped,over,lazy,dogs}

Note that substitutions are done repeatedly over multiple instances of the expression pattern. For example:

Substitute( Expr( a + a ), Expr( a ), Expr( aaa ) );

results in:

aaa + aaa