## `listlib::insert` -- insert an element into a list

#### Introduction

`listlib::insert(`list, element`)` inserts `element` into `list`.

#### Call(s)

`listlib::insert(list, element <, function>)`

#### Parameters

`list` | - | MuPAD list
`element` | - | MuPAD expression to insert
`function` | - | function, that determines the insert position

#### Returns

the given list enlarged with the inserted element

#### Related Functions

`_concat`, `append`, `listlib::insertAt`

#### Details

- With the function `listlib::insert` any element can be inserted into any list.
- With the third optional argument a function can be given that compare the elements of the list with the element to insert and therewith determines the position, the element is inserted. The given function is called with two elements and have to return `TRUE`, if the two elements are in the right order, otherwise `FALSE` (see next paragraph).
- The given function is called step by step with an element of the list as first argument and the given element as second argument, until it returns `FALSE`. Then the given element is inserted into the list in front of the last proved element (see example 2).

- The list must be ordered with regard to the order function, otherwise the element could be inserted at the wrong place.

- If no third argument is given the function `_less` is used. If no order of the elements with regard to `_less` is defined, a function must be given, otherwise an error appears. The system function `sysorder` always can be used.

#### Example 1

Insert `3` into the given ordered list:

    >> listlib::insert([1, 2, 4, 5, 6], 3)

                                [1, 2, 3, 4, 5, 6]

Insert `3` into the given descending ordered list. The insert function represents and preserves the order of the list:

    >> listlib::insert([6, 5, 4, 2, 1], 3, _not@_less)

                                [6, 5, 4, 3, 2, 1]

Because identifiers cannot be ordered by `_less`, another function must be given, e.g., the function that represents the systems internal order:

    >> listlib::insert([a, b, d, e, f], c, sysorder)

                                [a, b, c, d, e, f]

#### Example 2

Because no function is given as third argument, the function `_less` is used. `_less` is called: `_less(1, 3)`, `_less(2, 3)`, `_less(4, 3)` and then `3` is inserted in front of `4`:

    >> listlib::insert([1, 2, 4], 3)

                                   [1, 2, 3, 4]

If the list is not ordered right, then the insert position could be wrong:

    >> listlib::insert([4, 1, 2], 3)

                                   [3, 4, 1, 2]

#### Example 3

The following example shows, how expressions can be ordered by a user defined priority. This order is given by the function named `priority`, which returns a smaller number, when the expression has a type with higher priority:

    >> priority := X -> contains(["_power", "_mult", "_plus"], type(X)):
       priority(x^2), priority(x + 2)

                                       1, 3

The function `sortfunc` returns `TRUE`, if the both given arguments are in the right order, i.e., the first argument has a higher (or equal) priority than the second argument:

    >> sortfunc := (X, Y) -> bool(priority(Y) > priority(X)):
       sortfunc(x^2, x + 2), sortfunc(x + 2, x*2)

                                    TRUE, FALSE

Now the expression `x*2` is inserted at the ``right'' place in the list:

    >> listlib::insert([x^y, x^2, x*y, -y, x + y], x*2, sortfunc)

                             y   2
                           [x , x , 2 x, x y, -y, x + y]

#### Changes

- used to be called `insert_ordered`
- The first both arguments are swapped.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000