contains -- test if an entry
exists in a container
Introductioncontains(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)
Parameterss |
- | a set |
l |
- | a list |
t |
- | an array, a table, or a domain |
object |
- | an arbitrary MuPAD object |
i |
- | an integer |
ReturnsFor sets, arrays, tables, or domains, contains returns
one of the Boolean values TRUE or FALSE. For lists, the return value is
a nonnegative integer.
s, l, t
Related
Functions
Detailscontains 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.
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
1contains 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
2contains 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
3contains 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
4contains 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
5contains 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
6For 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
7contains 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
8Users 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