Publication date: 07/30/2020

## Manipulating lists

The following functions 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 Table 8.4.

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

`A = {2, 3, 4, 2, 1, 2, 1};`
`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};`
` `
`B = {2, 3, 4, 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, 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 ); // store 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( a ); // a = {4, 3, 2, 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 functions

In-place functions 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 function 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 functions

For the not-in-place functions, you must either state the list directly or else quote a name that evaluates to a list. Such functions 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