## `contains` -- test if an entry exists in a container

#### Introduction

`contains(`s, object`)` tests if `object` is an element of the set `s`.

`contains(`l, object`)` returns the index of `object` in the list `l`.

`contains(`t, object`)` tests if the array, table, or domain `t` has an entry corresponding to the index `object`.

#### Call(s)

`contains(s, object)`
`contains(l, object <, i>)`
`contains(t, object)`

#### Parameters

`s` | - | a set
`l` | - | a list
`t` | - | an array, a table, or a domain
`object` | - | an arbitrary MuPAD object
`i` | - | an integer

#### Returns

For sets, arrays, tables, or domains, `contains` returns one of the Boolean values `TRUE` or `FALSE`. For lists, the return value is a nonnegative integer.

### Overloadable:

`s`, `l`, `t`

#### Related Functions

`_in`, `_index`, `has`, `op`, `slot`

#### Details

- `contains` is a fast membership test for MuPAD's basic container data types. For lists and sets, `contains` searches the elements for the given object. However, for arrays, tables, and domains, `contains` searches the indices.
- `contains` works syntactically, i.e., mathematically equivalent objects are considered to be equal only if they are syntactically identical. See example 2.
- `contains` does not descend recursively into subexpressions; use `has` to achieve this. See example 3.
- `contains(`s, object`)` returns `TRUE` if `object` is an element of the set `s`. Otherwise, it returns `FALSE`.
- `contains(`l, object`)` returns the position of `object` in the list `l` as a positive integer if `object` is an entry of `l`. Otherwise, the return value is `0`. If more than one entry of `l` is equal to `object`, then the index of the first occurrence is returned.

  By passing a third argument `i` to `contains`, you can specify a position in the list where the search is to start. Then entries with index less than `i` are not taken into account. If `i` is out of range, then the return value is `0`.

  Cf. examples 4 and 5.

- `contains(`t, object`)` returns `TRUE` if the array, table, or domain `t` has an entry corresponding to the index `object`. Otherwise, it returns `FALSE`. Cf. example 6.
- `contains` is a function of the system kernel.

#### Example 1

`contains` may be used to test if a set contains a given element:

    >> contains({a, b, c}, a), contains({a, b, c}, 2)

                                    TRUE, FALSE

#### Example 2

`contains` works syntactically, i.e., mathematically equivalent objects are considered to be equal only if they are syntactically identical. In this example `contains` returns `FALSE` since `y*(x + 1)` and `y*x + y` are different representations of the same mathematical expression:

    >> contains({y*(x + 1)}, y*x + y)

                                       FALSE

#### Example 3

`contains` does not descend recursively into the operands of its first argument. In the following example, `c` is not an element of the set, and therefore `FALSE` is returned:

    >> contains({a, b, c + d}, c)

                                       FALSE

If you want to test whether a given expression is contained somewhere inside a complex expression, please use `has`:

    >> has({a, b, c + d}, c)

                                       TRUE

#### Example 4

`contains` applied to a `list` returns the position of the specified object in the list:

    >> contains([a, b, c], b)

                                         2

If the list does not contain the object, `0` is returned:

    >> contains([a, b, c], d)

                                         0

#### Example 5

`contains` returns the position of the first occurrence of the given object in the list if it occurs more than once:

    >> l := [a, b, a, b]: contains(l, b)

                                         2

A starting position for the search may be given as optional third argument:

    >> contains(l, b, 1), contains(l, b, 2),
       contains(l, b, 3), contains(l, b, 4)

                                    2, 2, 4, 4

If the third argument is out of range, then the return value is `0`:

    >> contains(l, b, -1), contains(l, b, 0), contains(l, b, 5)

                                      0, 0, 0

#### Example 6

For tables, `contains` returns `TRUE` if the second argument is a valid index in the table. The entries stored in the table are not considered:

    >> t := table(13 = value): contains(t, 13), contains(t, value)

                                    TRUE, FALSE

Similarly, `contains` tests if an `array` has a value for a given index. The array `a` has a value corresponding to the index `(1, 1)`, but none for the index `(1, 2)`:

    >> a := array(1..3, 1..2, (1, 1) = x, (2, 1) = PI):
       contains(a, (1, 1)), contains(a, (1, 2))

                                    TRUE, FALSE

`contains` is not intended for testing if an array contains a given value:

    >> contains(a, PI)

          Error: Index dimension mismatch [array]

Even if the dimensions match, the index must not be out of range:

    >> contains(a, (4, 4))

          Error: Illegal argument [array]

#### Example 7

`contains` may be used to test, whether a `domain` has the specified `slot`:

    >> T := newDomain("T"):  T::index := value:
       contains(T, index), contains(T, value)

                                   FALSE, FALSE

There is no entry corresponding to the slot `index` in `T`. Please keep in mind that the syntax `T::index` is equivalent to `slot(T,` "index"):

    >> contains(T, "index")

                                       TRUE

#### Example 8

Users can overload `contains` for their own domains. For illustration, we create a new domain `T` and supply it with an `"`contains" slot, which tests is the set of entries of an element contains the given value `idx`:

    >> T := newDomain("T"):
       T::contains := (e, idx) -> contains({extop(e)}, idx):

If we now call `contains` with an object of domain type `T`, the slot routine `T::contains` is invoked:

    >> e := new(T, 1, 2): contains(e, 2), contains(e, 3)

                                    TRUE, FALSE

#### Changes

- no changes

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