## `split` -- split an object

#### Introduction

`split(`object, f`)` splits the object into a list of three objects. The first list entry is an object consisting of those operands of the input object that satisfy a criterion defined by the procedure `f`. The second list entry is built from the operands that violate the criterion. The third list entry is built from the operands for which it is unknown whether the criterion is satisfied.

#### Call(s)

`split(object, f <, p1, p2...>)`

#### Parameters

`object` | - | a list, a set, a table, an expression sequence, or an expression of type `DOM_EXPR`
`f` | - | a procedure returning a Boolean value
`p1, p2...` | - | any MuPAD objects accepted by `f` as additional parameters

#### Returns

a list with three objects of the same type as the input object.

### Overloadable:

`object`

#### Related Functions

`map`, `op`, `select`, `zip`

#### Details

- The function `f` must return a value that can be evaluated to one of the Boolean values `TRUE`, `FALSE`, or `UNKNOWN`. It may either return one of these values directly, or it may return an equation or an inequality that can be simplified to one of these values by the function `bool`.
- The function `f` is applied to all operands `x` of the input object via the call `f(x, p1, p2, ...)`. Depending on the result `TRUE`, `FALSE`, or `UNKNOWN`, this operand is inserted into the first, the second, or the third output object, respectively.

  The output objects are of the same type as the input object, i.e., a list is split into three lists, a set into three sets, a table into three tables etc.

- If the input object is an expression sequence, then neither the input sequence nor the output (a list containing three sequences) are flattened.
- Also ``atomic'' objects such as numbers or identifiers can be passed to `split` as first argument. Such objects are handled like sequences with a single operand.
- `split` is a function of the system kernel.

#### Example 1

The following command checks which of the integers in the list are prime:

    >> split([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], isprime)

                      [[2, 3, 5, 7], [1, 4, 6, 8, 9, 10], []]

The return value is a list of three lists. The first list contains the prime numbers, the second list contains all other numbers. The third list is empty, because for any number of the input list, it can be decided whether it is prime or not.

#### Example 2

With the optional arguments `p1, p2, ...` one can use functions that need more than one argument. For example, `contains` is a handy function to be used with `split`. The following call splits a list of sets into those sets that contain `x` and those that do not:

    >> split([{a, x, b}, {a}, {x, 1}], contains, x)

                         [[{a, b, x}, {x, 1}], [{a}], []]

The elements of the returned list are of of type `DOM_LIST`, because the given expression was a list. If the given expression is of another type, e.g., `DOM_SET`, also the elements of the result are of type `DOM_SET`, too:

    >> split({{a, x, b}, {a}, {x, 1}}, contains, x)

                         [{{x, 1}, {a, b, x}}, {{a}}, {}]

#### Example 3

We use the function `is` to split an expression sequence into sub-sequences. This function returns `UNKNOWN` if it cannot derive the queried property:

    >> split((-2, -1, a, 0, b, 1, 2), is, Type::Positive)

                           [(1, 2), (-2, -1, 0), (a, b)]

#### Example 4

We split a table of people marked as male or female:

    >> people := table("Tom" = "m", "Rita" = "f", "Joe" = "m"):
       [male, female, dummy] := split(people, has, "m"):

    >> male

                                  table(
                                    "Joe" = "m",
                                    "Tom" = "m"
                                  )

    >> female

                                  table(
                                    "Rita" = "f"
                                  )

    >> dummy

                                      table()

    >> delete people, male, female, dummy:

#### Changes

- no changes

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