Previous Page Next Page Contents

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

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




Do you have questions or comments?


Copyright © SciFace Software GmbH & Co. KG 2000