List operations

(directly go to documentation on : Head, Tail, Length, Map, MapSingle, MakeVector, Select, Nth, DestructiveReverse, Reverse, List, UnList, Listify, Concat, Delete, Insert, DestructiveDelete, DestructiveInsert, Replace, DestructiveReplace, FlatCopy, Contains, Find, Append, DestructiveAppend, RemoveDuplicates, Push, Pop, PopFront, PopBack, Swap, Count, Intersection, Union, Difference, FillList, Drop, Take, Partition, Assoc, AssocIndices, AssocDelete, Flatten, UnFlatten, Type, NrArgs, VarList, VarListArith, VarListSome, FuncList, FuncListArith, FuncListSome, BubbleSort, HeapSort, PrintList, Table, TableForm, GlobalPop, GlobalPush. )

# 21. List operations

Most objects that can be of variable size are represented as lists (linked lists internally). Yacas does implement arrays, which are faster when the number of elements in a collection of objects doesn't change. Operations on lists have better support in the current system.

Head | the first element of a list
Tail | returns a list without its first element
Length | the length of a list or string
Map | apply an n-ary function to all entries in a list
MapSingle | apply a unary function to all entries in a list
MakeVector | vector of uniquely numbered variable names
Select | select entries satisfying some predicate
Nth | return the n-th element of a list
DestructiveReverse | reverse a list destructively
Reverse | return the reversed list (without touching the original)
List | construct a list
UnList | convert a list to a function application
Listify | convert a function application to a list
Concat | concatenate lists
Delete | delete an element from a list
Insert | insert an element into a list
DestructiveDelete | delete an element destructively from a list
DestructiveInsert | insert an element destructively into a list
Replace | replace an entry in a list
DestructiveReplace | replace an entry destructively in a list
FlatCopy | copy the top level of a list
Contains | test whether a list contains a certain element
Find | get the index at which a certain element occurs
Append | append an entry at the end of a list
DestructiveAppend | destructively append an entry to a list
RemoveDuplicates | remove any duplicates from a list
Push | add an element on top of a stack
Pop | remove an element from a stack
PopFront | remove an element from the top of a stack
PopBack | remove an element from the bottom of a stack
Swap | swap two elements in a list
Count | count the number of occurrences of an expression
Intersection | return the intersection of two lists
Union | return the union of two lists
Difference | return the difference of two lists
FillList | fill a list with a certain expression
Drop | drop a range of elements from a list
Take | take a sublist from a list, dropping the rest
Partition | partition a list in sublists of equal length
Assoc | return element stored in association list
AssocIndices | return the keys in an association list
AssocDelete | delete an entry in an association list
Flatten | flatten expression w.r.t. some operator
UnFlatten | inverse operation of Flatten
Type | return the type of an expression
NrArgs | return number of top-level arguments
VarList | list of variables appearing in an expression
VarListArith | list of variables appearing in an expression
VarListSome | list of variables appearing in an expression
FuncList | list of functions used in an expression
FuncListArith | list of functions used in an expression
FuncListSome | list of functions used in an expression
BubbleSort | sort a list
HeapSort | sort a list
PrintList | print list with padding
Table | evaluate while some variable ranges over interval
TableForm | print each entry in a list on a line
GlobalPop | restore variables using a global stack
GlobalPush | save variables using a global stack

###

Head -- the first element of a list

##### Internal function

##### Calling format:

    Head(list)

##### Parameters:

`list` -- a list

##### Description:

This function returns the first element of a list. If it is applied to a general expression, it returns the first operand. An error is returned if "list" is an atom.

##### Examples:

    In> Head({a,b,c})
    Out> a;
    In> Head(f(a,b,c));
    Out> a;

##### See also:

Tail , Length .

###

Tail -- returns a list without its first element

##### Internal function

##### Calling format:

    Tail(list)

##### Parameters:

`list` -- a list

##### Description:

This function returns "list" without its first element.

##### Examples:

    In> Tail({a,b,c})
    Out> {b,c};

##### See also:

Head , Length .

###

Length -- the length of a list or string

##### Internal function

##### Calling format:

    Length(object)

##### Parameters:

`object` -- a list, array or string

##### Description:

Length returns the length of a list. This function also works on strings and arrays.

##### Examples:

    In> Length({a,b,c})
    Out> 3;
    In> Length("abcdef");
    Out> 6;

##### See also:

Head , Tail , Nth , Count .

###

Map -- apply an n-ary function to all entries in a list

##### Standard library

##### Calling format:

    Map(fn, list)

##### Parameters:

`fn` -- function to apply

`list` -- list of lists of arguments

##### Description:

This function applies "fn" to every list of arguments to be found in "list". So the first entry of "list" should be a list containing the first, second, third, ... argument to "fn", and the same goes for the other entries of "list". The function can either be given as a string or as a pure function (see Apply for more information on pure functions).

##### Examples:

    In> MapSingle("Sin",{a,b,c});
    Out> {Sin(a),Sin(b),Sin(c)};
    In> Map("+",{{a,b},{c,d}});
    Out> {a+c,b+d};

##### See also:

MapSingle , MapArgs , Apply .

###

MapSingle -- apply a unary function to all entries in a list

##### Standard library

##### Calling format:

    MapSingle(fn, list)

##### Parameters:

`fn` -- function to apply

`list` -- list of arguments

##### Description:

The function "fn" is successively applied to all entries in "list", and a list containing the respective results is returned. The function can be given either as a string or as a pure function (see Apply for more information on pure functions).

The `/@` operator provides a shorthand for `MapSingle`.

##### Examples:

    In> MapSingle("Sin",{a,b,c});
    Out> {Sin(a),Sin(b),Sin(c)};
    In> MapSingle({{x},x^2}, {a,2,c});
    Out> {a^2,4,c^2};

##### See also:

Map , MapArgs , /@ , Apply .

###

MakeVector -- vector of uniquely numbered variable names

##### Standard library

##### Calling format:

    MakeVector(var,n)

##### Parameters:

`var` -- free variable

`n` -- length of the vector

##### Description:

A list of length "n" is generated. The first entry contains the identifier "var" with the number 1 appended to it, the second entry contains "var" with the suffix 2, and so on until the last entry which contains "var" with the number "n" appended to it.

##### Examples:

    In> MakeVector(a,3)
    Out> {a1,a2,a3};

##### See also:

RandomIntegerVector , ZeroVector .

###

Select -- select entries satisfying some predicate

##### Standard library

##### Calling format:

    Select(pred, list)

##### Parameters:

`pred` -- a predicate

`list` -- a list of elements to select from

##### Description:

`Select` returns a sublist of "list" which contains all the entries for which the predicate "pred" returns `True` when applied to this entry.

##### Examples:

    In> Select("IsInteger",{a,b,2,c,3,d,4,e,f})
    Out> {2,3,4};

##### See also:

Length , Find , Count .

###

Nth -- return the n-th element of a list

##### Internal function

##### Calling format:

    Nth(list, n)

##### Parameters:

`list` -- list to choose from

`n` -- index of entry to pick

##### Description:

The entry with index "n" from "list" is returned. The first entry has index 1. It is possible to pick several entries of the list by taking "n" to be a list of indices.

More generally, `Nth` returns the n-th operand of the expression passed as first argument.

An alternative but equivalent form of `Nth(list, n)` is `list[n]`.

##### Examples:

    In> lst := {a,b,c,13,19};
    Out> {a,b,c,13,19};
    In> Nth(lst, 3);
    Out> c;
    In> lst[3];
    Out> c;
    In> Nth(lst, {3,4,1});
    Out> {c,13,a};
    In> Nth(b*(a+c), 2);
    Out> a+c;

##### See also:

Select , Nth .

###

DestructiveReverse -- reverse a list destructively

##### Internal function

##### Calling format:

    DestructiveReverse(list)

##### Parameters:

`list` -- list to reverse

##### Description:

This command reverses "list" in place, so that the original is destroyed. This means that any variable bound to "list" will now have an undefined content, and should not be used any more. The reversed list is returned.

Destructive commands are faster than their nondestructive counterparts. `Reverse` is the non-destructive version of this function.

##### Examples:

    In> lst := {a,b,c,13,19};
    Out> {a,b,c,13,19};
    In> revlst := DestructiveReverse(lst);
    Out> {19,13,c,b,a};
    In> lst;
    Out> {a};

##### See also:

FlatCopy , Reverse .

###

Reverse -- return the reversed list (without touching the original)

##### Standard library

##### Calling format:

    Reverse(list)

##### Parameters:

`list` -- list to reverse

##### Description:

This function returns a list reversed, without changing the original list. It is similar to `DestructiveReverse`, but safer and slower.

##### Example:

    In> lst:={a,b,c,13,19}
    Out> {a,b,c,13,19};
    In> revlst:=Reverse(lst)
    Out> {19,13,c,b,a};
    In> lst
    Out> {a,b,c,13,19};

##### See also:

FlatCopy , DestructiveReverse .

###

List -- construct a list

##### Internal function

##### Calling format:

    List(expr1, expr2, ...)

##### Parameters:

`expr1`, `expr2` -- expressions making up the list

##### Description:

A list is constructed whose first entry is "expr1", the second entry is "expr2", and so on. This command is equivalent to the expression "`expr1, expr2, ...`".

##### Examples:

    In> List();
    Out> {};
    In> List(a,b);
    Out> {a,b};
    In> List(a,{1,2},d);
    Out> {a,{1,2},d};

##### See also:

UnList , Listify .

###

UnList -- convert a list to a function application

##### Internal function

##### Calling format:

    UnList(list)

##### Parameters:

`list` -- list to be converted

##### Description:

This command converts a list to a function application. The first entry of "list" is treated as a function atom, and the following entries are the arguments to this function. So the function referred to in the first element of "list" is applied to the other elements.

Note that "list" is evaluated before the function application is formed, but the resulting expression is left unevaluated. The functions `UnList()` and `Hold()` both stop the process of evaluation.

##### Examples:

    In> UnList({Cos, x});
    Out> Cos(x);
    In> UnList({f});
    Out> f();
    In> UnList({Taylor,x,0,5,Cos(x)});
    Out> Taylor(x,0,5)Cos(x);
    In> Eval(%);
    Out> 1-x^2/2+x^4/24;

##### See also:

List , Listify , Hold .

###

Listify -- convert a function application to a list

##### Internal function

##### Calling format:

    Listify(expr)

##### Parameters:

`expr` -- expression to be converted

##### Description:

The parameter "expr" is expected to be a compound object, i.e. not an atom. It is evaluated and then converted to a list. The first entry in the list is the top-level operator in the evaluated expression and the other entries are the arguments to this operator. Finally, the list is returned.

##### Examples:

    In> Listify(Cos(x));
    Out> {Cos,x};
    In> Listify(3*a);
    Out> {*,3,a};

##### See also:

List , UnList , IsAtom .

###

Concat -- concatenate lists

##### Internal function

##### Calling format:

    Concat(list1, list2, ...)

##### Parameters:

`list1`, `list2`, ... -- lists to concatenate

##### Description:

The lists "list1", "list2", ... are evaluated and concatenated. The resulting big list is returned.

##### Examples:

    In> Concat({a,b}, {c,d});
    Out> {a,b,c,d};
    In> Concat({5}, {a,b,c}, {{f(x)}});
    Out> {5,a,b,c,{f(x)}};

##### See also:

ConcatStrings , : , Insert .

###

Delete -- delete an element from a list

##### Internal function

##### Calling format:

    Delete(list, n)

##### Parameters:

`list` -- list from which an element should be removed

`n` -- index of the element to remove

##### Description:

This command deletes the n-th element from "list". The first parameter should be a list, while "n" should be a positive integer less than or equal to the length of "list". The entry with index "n" is removed (the first entry has index 1), and the resulting list is returned.

##### Examples:

    In> Delete({a,b,c,d,e,f}, 4);
    Out> {a,b,c,e,f};

##### See also:

DestructiveDelete , Insert , Replace .

###

Insert -- insert an element into a list

##### Internal function

##### Calling format:

    Insert(list, n, expr)

##### Parameters:

`list` -- list in which "expr" should be inserted

`n` -- index at which to insert

`expr` -- expression to insert in "list"

##### Description:

The expression "expr" is inserted just before the n-th entry in "list". The first parameter "list" should be a list, while "n" should be a positive integer less than or equal to the length of "list" plus one. The expression "expr" is placed between the entries in "list" with entries "n-1" and "n". There are two border line cases: if "n" is 1, the expression "expr" is placed in front of the list (just as by the `:` operator); if "n" equals the length of "list" plus one, the expression "expr" is placed at the end of the list (just as by `Append`). In any case, the resulting list is returned.

##### Examples:

    In> Insert({a,b,c,d}, 4, x);
    Out> {a,b,c,x,d};
    In> Insert({a,b,c,d}, 5, x);
    Out> {a,b,c,d,x};
    In> Insert({a,b,c,d}, 1, x);
    Out> {x,a,b,c,d};

##### See also:

DestructiveInsert , : , Append , Delete , Remove .

###

DestructiveDelete -- delete an element destructively from a list

##### Internal function

##### Calling format:

    DestructiveDelete(list, n)

##### Parameters:

`list` -- list from which an element should be removed

`n` -- index of the element to remove

##### Description:

This is the destructive counterpart of `Delete`. This command yields the same result as the corresponding call to `Delete`, but the original list is modified. So if a variable is bound to "list", it will now be bound to the list with the n-th entry removed.

Destructive commands run faster than their nondestructive counterparts because the latter copy the list before they alter it.

##### Examples:

    In> lst := {a,b,c,d,e,f};
    Out> {a,b,c,d,e,f};
    In> Delete(lst, 4);
    Out> {a,b,c,e,f};
    In> lst;
    Out> {a,b,c,d,e,f};
    In> DestructiveDelete(lst, 4);
    Out> {a,b,c,e,f};
    In> lst;
    Out> {a,b,c,e,f};

##### See also:

Delete , DestructiveInsert , DestructiveReplace .

###

DestructiveInsert -- insert an element destructively into a list

##### Internal function

##### Calling format:

    DestructiveInsert(list, n, expr)

##### Parameters:

`list` -- list in which "expr" should be inserted

`n` -- index at which to insert

`expr` -- expression to insert in "list"

##### Description:

This is the destructive counterpart of `Insert`. This command yields the same result as the corresponding call to `Insert`, but the original list is modified. So if a variable is bound to "list", it will now be bound to the list with the expression "expr" inserted.

Destructive commands run faster than their nondestructive counterparts because the latter copy the list before they alter it.

##### Examples:

    In> lst := {a,b,c,d};
    Out> {a,b,c,d};
    In> Insert(lst, 2, x);
    Out> {a,x,b,c,d};
    In> lst;
    Out> {a,b,c,d};
    In> DestructiveInsert(lst, 2, x);
    Out> {a,x,b,c,d};
    In> lst;
    Out> {a,x,b,c,d};

##### See also:

Insert , DestructiveDelete , DestructiveReplace .

###

Replace -- replace an entry in a list

##### Internal function

##### Calling format:

    Replace(list, n, expr)

##### Parameters:

`list` -- list of which an entry should be replaced

`n` -- index of entry to replace

`expr` -- expression to replace the n-th entry with

##### Description:

The n-th entry of "list" is replaced by the expression "expr". This is equivalent to calling `Delete` and `Insert` in sequence. To be precise, the expression `Replace(list, n, expr)` has the same result as the expression `Insert(Delete(list, n), n, expr)`.

##### Examples:

    In> Replace({a,b,c,d,e,f}, 4, x);
    Out> {a,b,c,x,e,f};

##### See also:

Delete , Insert , DestructiveReplace .

###

DestructiveReplace -- replace an entry destructively in a list

##### Internal function

##### Calling format:

    DestructiveReplace(list, n, expr)

##### Parameters:

`list` -- list of which an entry should be replaced

`n` -- index of entry to replace

`expr` -- expression to replace the n-th entry with

##### Description:

This is the destructive counterpart of `Replace`. This command yields the same result as the corresponding call to `Replace`, but the original list is modified. So if a variable is bound to "list", it will now be bound to the list with the expression "expr" inserted.

Destructive commands run faster than their nondestructive counterparts because the latter copy the list before they alter it.

##### Examples:

    In> lst := {a,b,c,d,e,f};
    Out> {a,b,c,d,e,f};
    In> Replace(lst, 4, x);
    Out> {a,b,c,x,e,f};
    In> lst;
    Out> {a,b,c,d,e,f};
    In> DestructiveReplace(lst, 4, x);
    Out> {a,b,c,x,e,f};
    In> lst;
    Out> {a,b,c,x,e,f};

##### See also:

Replace , DestructiveDelete , DestructiveInsert .

###

FlatCopy -- copy the top level of a list

##### Internal function

##### Calling format:

    FlatCopy(list)

##### Parameters:

`list` -- list to be copied

##### Description:

A copy of "list" is made and returned. The list is not recursed into, only the first level is copied. This is useful in combination with the destructive commands that actually modify lists in place (for efficiency).

##### Examples:

The following shows a possible way to define a command that reverses a list nondestructively.

    In> reverse(l_IsList) <-- DestructiveReverse \
      (FlatCopy(l));
    Out> True;
    In> lst := {a,b,c,d,e};
    Out> {a,b,c,d,e};
    In> reverse(lst);
    Out> {e,d,c,b,a};
    In> lst;
    Out> {a,b,c,d,e};

###

Contains -- test whether a list contains a certain element

##### Standard library

##### Calling format:

    Contains(list, expr)

##### Parameters:

`list` -- list to examine

`expr` -- expression to look for in "list"

##### Description:

This command tests whether "list" contains the expression "expr" as an entry. It returns `True` if it does and `False` otherwise. Only the top level of "list" is examined. The parameter "list" may also be a general expression, in that case the top-level operands are tested for the occurrence of "expr".

##### Examples:

    In> Contains({a,b,c,d}, b);
    Out> True;
    In> Contains({a,b,c,d}, x);
    Out> False;
    In> Contains({a,{1,2,3},z}, 1);
    Out> False;
    In> Contains(a*b, b);
    Out> True;

##### See also:

Find , Count .

###

Find -- get the index at which a certain element occurs

##### Standard library

##### Calling format:

    Find(list, expr)

##### Parameters:

`list` -- the list to examine

`expr` -- expression to look for in "list"

##### Description:

This commands returns the index at which the expression "expr" occurs in "list". If "expr" occurs more than once, the lowest index is returned. If "expr" does not occur at all, `-1` is returned.

##### Examples:

    In> Find({a,b,c,d,e,f}, d);
    Out> 4;
    In> Find({1,2,3,2,1}, 2);
    Out> 2;
    In> Find({1,2,3,2,1}, 4);
    Out> -1;

##### See also:

Contains .

###

Append -- append an entry at the end of a list

##### Standard library

##### Calling format:

    Append(list, expr)

##### Parameters:

`list` -- list to append "expr" to

`expr` -- expression to append to the list

##### Description:

The expression "expr" is appended at the end of "list" and the resulting list is returned.

Note that due to the underlying data structure, the time it takes to append an entry at the end of a list grows linearly with the length of the list, while the time for prepending an entry at the beginning is constant.

##### Examples:

    In> Append({a,b,c,d}, 1);
    Out> {a,b,c,d,1};

##### See also:

Concat , : , DestructiveAppend .

###

DestructiveAppend -- destructively append an entry to a list

##### Internal function

##### Calling format:

    DestructiveAppend(list, expr)

##### Parameters:

`list` -- list to append "expr" to

`expr` -- expression to append to the list

##### Description:

This is the destructive counterpart of `Append`. This command yields the same result as the corresponding call to `Append`, but the original list is modified. So if a variable is bound to "list", it will now be bound to the list with the expression "expr" inserted.

Destructive commands run faster than their nondestructive counterparts because the latter copy the list before they alter it.

##### Examples:

    In> lst := {a,b,c,d};
    Out> {a,b,c,d};
    In> Append(lst, 1);
    Out> {a,b,c,d,1};
    In> lst
    Out> {a,b,c,d};
    In> DestructiveAppend(lst, 1);
    Out> {a,b,c,d,1};
    In> lst;
    Out> {a,b,c,d,1};

##### See also:

Concat , : , Append .

###

RemoveDuplicates -- remove any duplicates from a list

##### Standard library

##### Calling format:

    RemoveDuplicates(list)

##### Parameters:

`list` -- list to act on

##### Description:

This command removes all duplicate elements from a given list and returns the resulting list. To be precise, the second occurrence of any entry is deleted, as are the third, the fourth, etc.

##### Examples:

    In> RemoveDuplicates({1,2,3,2,1});
    Out> {1,2,3};
    In> RemoveDuplicates({a,1,b,1,c,1});
    Out> {a,1,b,c};

###

Push -- add an element on top of a stack

##### Standard library

##### Calling format:

    Push(stack, expr)

##### Parameters:

`stack` -- a list (which serves as the stack container)

`expr` -- expression to push on "stack"

##### Description:

This is part of a simple implementation of a stack, internally represented as a list. This command pushes the expression "expr" on top of the stack, and returns the stack afterwards.

##### Examples:

    In> stack := {};
    Out> {};
    In> Push(stack, x);
    Out> {x};
    In> Push(stack, x2);
    Out> {x2,x};
    In> PopFront(stack);
    Out> x2;

##### See also:

Pop , PopFront , PopBack .

###

Pop -- remove an element from a stack

##### Standard library

##### Calling format:

    Pop(stack, n)

##### Parameters:

`stack` -- a list (which serves as the stack container)

`n` -- index of the element to remove

##### Description:

This is part of a simple implementation of a stack, internally represented as a list. This command removes the element with index "n" from the stack and returns this element. The top of the stack is represented by the index 1. Invalid indices, for example indices greater than the number of element on the stack, lead to an error.

##### Examples:

    In> stack := {};
    Out> {};
    In> Push(stack, x);
    Out> {x};
    In> Push(stack, x2);
    Out> {x2,x};
    In> Push(stack, x3);
    Out> {x3,x2,x};
    In> Pop(stack, 2);
    Out> x2;
    In> stack;
    Out> {x3,x};

##### See also:

Push , PopFront , PopBack .

###

PopFront -- remove an element from the top of a stack

##### Standard library

##### Calling format:

    PopFront(stack)

##### Parameters:

`stack` -- a list (which serves as the stack container)

##### Description:

This is part of a simple implementation of a stack, internally represented as a list. This command removes the element on the top of the stack and returns it. This is the last element that is pushed onto the stack.

##### Examples:

    In> stack := {};
    Out> {};
    In> Push(stack, x);
    Out> {x};
    In> Push(stack, x2);
    Out> {x2,x};
    In> Push(stack, x3);
    Out> {x3,x2,x};
    In> PopFront(stack);
    Out> x3;
    In> stack;
    Out> {x2,x};

##### See also:

Push , Pop , PopBack .

###

PopBack -- remove an element from the bottom of a stack

##### Standard library

##### Calling format:

    PopBack(stack)

##### Parameters:

`stack` -- a list (which serves as the stack container)

##### Description:

This is part of a simple implementation of a stack, internally represented as a list. This command removes the element at the bottom of the stack and returns this element. Of course, the stack should not be empty.

##### Examples:

    In> stack := {};
    Out> {};
    In> Push(stack, x);
    Out> {x};
    In> Push(stack, x2);
    Out> {x2,x};
    In> Push(stack, x3);
    Out> {x3,x2,x};
    In> PopBack(stack);
    Out> x;
    In> stack;
    Out> {x3,x2};

##### See also:

Push , Pop , PopFront .

###

Swap -- swap two elements in a list

##### Standard library

##### Calling format:

    Swap(list, i1, i2)

##### Parameters:

`list` -- the list in which a pair of entries should be swapped

`i1, i2` -- indices of the entries in "list" to swap

##### Description:

This command swaps the pair of entries with entries "i1" and "i2" in "list". So the element at index "i1" ends up at index "i2" and the entry at "i2" is put at index "i1". Both indices should be valid to address elements in the list. Then the updated list is returned.

`Swap()` works also on generic arrays.

##### Examples:

    In> lst := {a,b,c,d,e,f};
    Out> {a,b,c,d,e,f};
    In> Swap(lst, 2, 4);
    Out> {a,d,c,b,e,f};

##### See also:

Replace , DestructiveReplace , Array'Create .

###

Count -- count the number of occurrences of an expression

##### Standard library

##### Calling format:

    Count(list, expr)

##### Parameters:

`list` -- the list to examine

`expr` -- expression to look for in "list"

##### Description:

This command counts the number of times that the expression "expr" occurs in "list" and returns this number.

##### Examples:

    In> lst := {a,b,c,b,a};
    Out> {a,b,c,b,a};
    In> Count(lst, a);
    Out> 2;
    In> Count(lst, c);
    Out> 1;
    In> Count(lst, x);
    Out> 0;

##### See also:

Length , Select , Contains .

###

Intersection -- return the intersection of two lists

##### Standard library

##### Calling format:

    Intersection(l1, l2)

##### Parameters:

`l1`, `l2` -- two lists

##### Description:

The intersection of the lists "l1" and "l2" is determined and returned. The intersection contains all elements that occur in both lists. The entries in the result are listed in the same order as in "l1". If an expression occurs multiple times in both "l1" and "l2", then it will occur the same number of times in the result.

##### Examples:

    In> Intersection({a,b,c}, {b,c,d});
    Out> {b,c};
    In> Intersection({a,e,i,o,u}, {f,o,u,r,t,e,e,n});
    Out> {e,o,u};
    In> Intersection({1,2,2,3,3,3}, {1,1,2,2,3,3});
    Out> {1,2,2,3,3};

##### See also:

Union , Difference .

###

Union -- return the union of two lists

##### Standard library

##### Calling format:

    Union(l1, l2)

##### Parameters:

`l1`, `l2` -- two lists

##### Description:

The union of the lists "l1" and "l2" is determined and returned. The union contains all elements that occur in one or both of the lists. In the resulting list, any element will occur only once.

##### Examples:

    In> Union({a,b,c}, {b,c,d});
    Out> {a,b,c,d};
    In> Union({a,e,i,o,u}, {f,o,u,r,t,e,e,n});
    Out> {a,e,i,o,u,f,r,t,n};
    In> Union({1,2,2,3,3,3}, {2,2,3,3,4,4});
    Out> {1,2,3,4};

##### See also:

Intersection , Difference .

###

Difference -- return the difference of two lists

##### Standard library

##### Calling format:

    Difference(l1, l2)

##### Parameters:

`l1`, `l2` -- two lists

##### Description:

The difference of the lists "l1" and "l2" is determined and returned. The difference contains all elements that occur in "l1" but not in "l2". The order of elements in "l1" is preserved. If a certain expression occurs "n1" times in the first list and "n2" times in the second list, it will occur "n1-n2" times in the result if "n1" is greater than "n2" and not at all otherwise.

##### Examples:

    In> Difference({a,b,c}, {b,c,d});
    Out> {a};
    In> Difference({a,e,i,o,u}, {f,o,u,r,t,e,e,n});
    Out> {a,i};
    In> Difference({1,2,2,3,3,3}, {2,2,3,4,4});
    Out> {1,3,3};

##### See also:

Intersection , Union .

###

FillList -- fill a list with a certain expression

##### Standard library

##### Calling format:

    FillList(expr, n)

##### Parameters:

`expr` -- expression to fill the list with

`n` -- the length of the list to construct

##### Description:

This command creates a list of length "n" in which all slots contain the expression "expr" and returns this list.

##### Examples:

    In> FillList(x, 5);
    Out> {x,x,x,x,x};

##### See also:

MakeVector , ZeroVector , RandomIntegerVector .

###

Drop -- drop a range of elements from a list

##### Standard library

##### Calling format:

    Drop(list, n)
    Drop(list, -n)
    Drop(list, {m,n})

##### Parameters:

`list` -- list to act on

`n`, `m` -- positive integers describing the entries to drop

##### Description:

This command removes a sublist of "list" and returns a list containing the remaining entries. The first calling sequence drops the first "n" entries in "list". The second form drops the last "n" entries. The last invocation drops the elements with indices "m" through "n".

##### Examples:

    In> lst := {a,b,c,d,e,f,g};
    Out> {a,b,c,d,e,f,g};
    In> Drop(lst, 2);
    Out> {c,d,e,f,g};
    In> Drop(lst, -3);
    Out> {a,b,c,d};
    In> Drop(lst, {2,4});
    Out> {a,e,f,g};

##### See also:

Take , Select , Remove .

###

Take -- take a sublist from a list, dropping the rest

##### Standard library

##### Calling format:

    Take(list, n)
    Take(list, -n)
    Take(list, {m,n})

##### Parameters:

`list` -- list to act on

`n`, `m` -- positive integers describing the entries to take

##### Description:

This command takes a sublist of "list", drops the rest, and returns the selected sublist. The first calling sequence selects the first "n" entries in "list". The second form takes the last "n" entries. The last invocation selects the sublist beginning with entry number "m" and ending with the "n"-th entry.

##### Examples:

    In> lst := {a,b,c,d,e,f,g};
    Out> {a,b,c,d,e,f,g};
    In> Take(lst, 2);
    Out> {a,b};
    In> Take(lst, -3);
    Out> {e,f,g};
    In> Take(lst, {2,4});
    Out> {b,c,d};

##### See also:

Drop , Select , Remove .

###

Partition -- partition a list in sublists of equal length

##### Standard library

##### Calling format:

    Partition(list, n)

##### Parameters:

`list` -- list to partition

`n` -- length of partitions

##### Description:

This command partitions "list" into non-overlapping sublists of length "n" and returns a list of these sublists. The first "n" entries in "list" form the first partition, the entries from position "n+1" up to "2n" form the second partition, and so on. If "n" does not divide the length of "list", the remaining entries will be thrown away. If "n" equals zero, an empty list is returned.

##### Examples:

    In> Partition({a,b,c,d,e,f,}, 2);
    Out> {{a,b},{c,d},{e,f}};
    In> Partition(1 .. 11, 3);
    Out> {{1,2,3},{4,5,6},{7,8,9}};

##### See also:

Take , Permutations .

###

Assoc -- return element stored in association list

##### Standard library

##### Calling format:

    Assoc(key, alist)

##### Parameters:

`key` -- string, key under which element is stored

`alist` -- association list to examine

##### Description:

The association list "alist" is searched for an entry stored with index "key". If such an entry is found, it is returned. Otherwise the atom `Empty` is returned.

Association lists are represented as a list of two-entry lists. The first element in the two-entry list is the key, the second element is the value stored under this key.

The call `Assoc(key, alist)` can (probably more intuitively) be accessed as `alist[key]`.

##### Examples:

    In> writer := {};
    Out> {};
    In> writer["Iliad"] := "Homer";
    Out> True;
    In> writer["Henry IV"] := "Shakespeare";
    Out> True;
    In> writer["Ulysses"] := "James Joyce";
    Out> True;
    In> Assoc("Henry IV", writer);
    Out> {"Henry IV","Shakespeare"};
    In> Assoc("War and Peace", writer);
    Out> Empty;

##### See also:

AssocIndices , [] , := , AssocDelete .

###

AssocIndices -- return the keys in an association list

##### Standard library

##### Calling format:

    AssocIndices(alist)

##### Parameters:

`alist` -- association list to examine

##### Description:

All the keys in the association list "alist" are assembled in a list and this list is returned.

##### Examples:

    In> writer := {};
    Out> {};
    In> writer["Iliad"] := "Homer";
    Out> True;
    In> writer["Henry IV"] := "Shakespeare";
    Out> True;
    In> writer["Ulysses"] := "James Joyce";
    Out> True;
    In> AssocIndices(writer);
    Out> {"Iliad","Henry IV","Ulysses"};

##### See also:

Assoc , AssocDelete .

###

AssocDelete -- delete an entry in an association list

##### Standard library

##### Calling format:

    AssocDelete(alist, "key")
    AssocDelete(alist, {key, value})

##### Parameters:

`alist` -- association list

`"key"` -- string, association key

`value` -- value of the key to be deleted

##### Description:

The key `"key"` in the association list `alist` is deleted. (The list itself is modified.) If the key was found and successfully deleted, returns `True`, otherwise if the given key was not found, the function returns `False`.

The second, longer form of the function deletes the entry that has both the specified key and the specified value. It can be used for two purposes:

- to make sure that we are deleting the right value;
- if several values are stored on the same key, to delete the specified entry (see the last example).

At most one entry is deleted.

##### Examples:

    In> writer := {};
    Out> {};
    In> writer["Iliad"] := "Homer";
    Out> True;
    In> writer["Henry IV"] := "Shakespeare";
    Out> True;
    In> writer["Ulysses"] := "James Joyce";
    Out> True;
    In> AssocDelete(writer, "Henry IV")
    Out> True;
    In> AssocDelete(writer, "Henry XII")
    Out> False;
    In> writer
    Out> {{"Ulysses","James Joyce"},
      {"Iliad","Homer"}};
    In> DestructiveAppend(writer,
      {"Ulysses", "Dublin"});
    Out> {{"Iliad","Homer"},{"Ulysses","James Joyce"},
      {"Ulysses","Dublin"}};
    In> writer["Ulysses"];
    Out> "James Joyce";
    In> AssocDelete(writer,{"Ulysses","James Joyce"});
    Out> True;
    In> writer
    Out> {{"Iliad","Homer"},{"Ulysses","Dublin"}};

##### See also:

Assoc , AssocIndices .

###

Flatten -- flatten expression w.r.t. some operator

##### Standard library

##### Calling format:

    Flatten(expression,operator)

##### Parameters:

`expression` -- an expression

`operator` -- string with the contents of an infix operator.

##### Description:

Flatten flattens an expression with respect to a specific operator, converting the result into a list. This is useful for unnesting an expression. Flatten is typically used in simple simplification schemes.

##### Examples:

    In> Flatten(a+b*c+d,"+");
    Out> {a,b*c,d};
    In> Flatten({a,{b,c},d},"List");
    Out> {a,b,c,d};

##### See also:

UnFlatten .

###

UnFlatten -- inverse operation of Flatten

##### Standard library

##### Calling format:

    UnFlatten(list,operator,identity)

##### Parameters:

`list` -- list of objects the operator is to work on

`operator` -- infix operator

`identity` -- identity of the operator

##### Description:

UnFlatten is the inverse operation of Flatten. Given a list, it can be turned into an expression representing for instance the addition of these elements by calling UnFlatten with "+" as argument to operator, and 0 as argument to identity (0 is the identity for addition, since a+0=a). For multiplication the identity element would be 1.

##### Examples:

    In> UnFlatten({a,b,c},"+",0)
    Out> a+b+c;
    In> UnFlatten({a,b,c},"*",1)
    Out> a*b*c;

##### See also:

Flatten .

###

Type -- return the type of an expression

##### Internal function

##### Calling format:

    Type(expr)

##### Parameters:

`expr` -- expression to examine

##### Description:

The type of the expression "expr" is represented as a string and returned. So, if "expr" is a list, the string `"List"` is returned. In general, the top-level operator of "expr" is returned. If the argument "expr" is an atom, the result is the empty string `""`.

##### Examples:

    In> Type({a,b,c});
    Out> "List";
    In> Type(a*(b+c));
    Out> "*";
    In> Type(123);
    Out> "";

##### See also:

IsAtom , NrArgs .

###

NrArgs -- return number of top-level arguments

##### Standard library

##### Calling format:

    NrArgs(expr)

##### Parameters:

`expr` -- expression to examine

##### Description:

This function evaluates to the number of top-level arguments of the expression "expr". The argument "expr" may not be an atom, since that would lead to an error.

##### Examples:

    In> NrArgs(f(a,b,c))
    Out> 3;
    In> NrArgs(Sin(x));
    Out> 1;
    In> NrArgs(a*(b+c));
    Out> 2;

##### See also:

Type , Length .

###

VarList -- list of variables appearing in an expression

###

VarListArith -- list of variables appearing in an expression

###

VarListSome -- list of variables appearing in an expression

##### Standard library

##### Calling format:

    VarList(expr)
    VarListArith(expr)
    VarListSome(expr, list)

##### Parameters:

`expr` -- an expression

`list` -- a list of function atoms

##### Description:

The command `VarList(expr)` returns a list of all variables that appear in the expression `expr`. The expression is traversed recursively.

The command `VarListSome` looks only at arguments of functions in the `list`. All other functions are considered "opaque" (as if they do not contain any variables) and their arguments are not checked. For example, `VarListSome(a + Sin(b-c))` will return `{a, b, c}`, but `VarListSome(a*Sin(b-c), {*})` will not look at arguments of `Sin()` and will return `{a,Sin(b-c)}`. Here `Sin(b-c)` is considered a "variable" because the function `Sin` does not belong to `list`.

The command `VarListArith` returns a list of all variables that appear arithmetically in the expression `expr`. This is implemented through `VarListSome` by restricting to the arithmetic functions `+`, `-`, `*`, `/`. Arguments of other functions are not checked.

Note that since the operators "`+`" and "`-`" are prefix as well as infix operators, it is currently required to use `Atom("+")` to obtain the unevaluated atom "`+`".

##### Examples:

    In> VarList(Sin(x))
    Out> {x};
    In> VarList(x+a*y)
    Out> {x,a,y};
    In> VarListSome(x+a*y, {Atom("+")})
    Out> {x,a*y};
    In> VarListArith(x+y*Cos(Ln(x)/x))
    Out> {x,y,Cos(Ln(x)/x)}
    In> VarListArith(x+a*y^2-1)
    Out> {x,a,y^2};

##### See also:

IsFreeOf , IsVariable , FuncList , HasExpr , HasFunc .

###

FuncList -- list of functions used in an expression

###

FuncListArith -- list of functions used in an expression

###

FuncListSome -- list of functions used in an expression

##### Standard library

##### Calling format:

    FuncList(expr)
    FuncListArith(expr)
    FuncListSome(expr, list)

##### Parameters:

`expr` -- an expression

`list` -- list of function atoms to be considered "transparent"

##### Description:

The command `FuncList(expr)` returns a list of all function atoms that appear in the expression `expr`. The expression is recursively traversed.

The command `FuncListSome(expr, list)` does the same, except it only looks at arguments of a given `list` of functions. All other functions become "opaque" (as if they do not contain any other functions). For example, `FuncListSome(a + Sin(b-c))` will see that the expression has a "`-`" operation and return `{+,Sin,-}`, but `FuncListSome(a + Sin(b-c), {+})` will not look at arguments of `Sin()` and will return `{+,Sin}`.

`FuncListArith` is defined through `FuncListSome` to look only at arithmetic operations `+`, `-`, `*`, `/`.

Note that since the operators "`+`" and "`-`" are prefix as well as infix operators, it is currently required to use `Atom("+")` to obtain the unevaluated atom "`+`".

##### Examples:

    In> FuncList(x+y*Cos(Ln(x)/x))
    Out> {+,*,Cos,/,Ln};
    In> FuncListArith(x+y*Cos(Ln(x)/x))
    Out> {+,*,Cos};
    In> FuncListSome({a+b*2,c/d},{List})
    Out> {List,+,/};

##### See also:

VarList , HasExpr , HasFunc .

###

BubbleSort -- sort a list

###

HeapSort -- sort a list

##### Standard library

##### Calling format:

    BubbleSort(list, compare)
    HeapSort(list, compare)

##### Parameters:

`list` -- list to sort

`compare` -- function used to compare elements of `list`

##### Description:

This command returns `list` after it is sorted using `compare` to compare elements. The function `compare` should accept two arguments, which will be elements of `list`, and compare them. It should return `True` if in the sorted list the second argument should come after the first one, and `False` otherwise.

The function `BubbleSort` uses the so-called "bubble sort" algorithm to do the sorting by swapping elements that are out of order. This algorithm is easy to implement, though it is not particularly fast. The sorting time is proportional to n^2 where n is the length of the list.

The function `HeapSort` uses a recursive algorithm "heapsort" and is much faster for large lists. The sorting time is proportional to n*Ln(n) where n is the length of the list.

##### Examples:

    In> BubbleSort({4,7,23,53,-2,1}, "<");
    Out> {-2,1,4,7,23,53};
    In> HeapSort({4,7,23,53,-2,1}, ">");
    Out> {53,23,7,4,1,-2};

###

PrintList -- print list with padding

##### Standard library

##### Calling format:

    PrintList(list)
    PrintList(list, padding);

##### Parameters:

`list` -- a list to be printed

`padding` -- (optional) a string

##### Description:

Prints `list` and inserts the `padding` string between each pair of items of the list. Items of the list which are strings are printed without quotes, unlike `Write()`. Items of the list which are themselves lists are printed inside braces `{}`. If padding is not specified, a standard one is used (comma, space).

##### Examples:

    In> PrintList({a,b,{c, d}}, " .. ")
    Out> " a ..  b .. { c ..  d}";

##### See also:

Write , WriteString .

###

Table -- evaluate while some variable ranges over interval

##### Standard library

##### Calling format:

    Table(body, var, from, to, step)

##### Parameters:

`body` -- expression to evaluate multiple times

`var` -- variable to use as loop variable

`from` -- initial value for "var"

`to` -- final value for "var"

`step` -- step size with which "var" is incremented

##### Description:

This command generates a list of values from "body", by assigning variable "var" values from "from" up to "to", incrementing "step" each time. So, the variable "var" first gets the value "from", and the expression "body" is evaluated. Then the value "from"+"step" is assigned to "var" and the expression "body" is again evaluated. This continues, incrementing "var" with "step" on every iteration, until "var" exceeds "to". At that moment, all the results are assembled in a list and this list is returned.

##### Examples:

    In> Table(i!, i, 1, 9, 1);
    Out> {1,2,6,24,120,720,5040,40320,362880};
    In> Table(i, i, 3, 16, 4);
    Out> {3,7,11,15};
    In> Table(i^2, i, 10, 1, -1);
    Out> {100,81,64,49,36,25,16,9,4,1};

##### See also:

For , MapSingle , .. , TableForm .

###

TableForm -- print each entry in a list on a line

##### Standard library

##### Calling format:

    TableForm(list)

##### Parameters:

`list` -- list to print

##### Description:

This functions writes out the list `list` in a better readable form, by printing every element in the list on a separate line.

##### Examples:

    In> TableForm(Table(i!, i, 1, 10, 1));

    1
     2
     6
     24
     120
     720
     5040
     40320
     362880
     3628800
    Out> True;

##### See also:

PrettyForm , Echo , Table .

###

GlobalPop -- restore variables using a global stack

###

GlobalPush -- save variables using a global stack

##### Standard library

##### Calling format:

    GlobalPop(var)
    GlobalPop()
    GlobalPush(expr)

##### Parameters:

`var` -- atom, name of variable to restore from the stack

`expr` -- expression, value to save on the stack

##### Description:

These functions operate with a global stack, currently implemented as a list that is not accessible externally (it is protected through `LocalSymbols`).

`GlobalPush` stores a value on the stack. `GlobalPop` removes the last pushed value from the stack. If a variable name is given, the variable is assigned, otherwise the popped value is returned.

If the global stack is empty, an error message is printed.

##### Examples:

    In> GlobalPush(3)
    Out> 3;
    In> GlobalPush(Sin(x))
    Out> Sin(x);
    In> GlobalPop(x)
    Out> Sin(x);
    In> GlobalPop(x)
    Out> 3;
    In> x
    Out> 3;

##### See also:

Push , PopFront .