Method search()

Method search

int search(string haystack, string|int needle, int|void start)
int search(array haystack, mixed needle, int|void start)
mixed search(mapping haystack, mixed needle, mixed|void start)
mixed search(object haystack, mixed needle, mixed|void start)

Description

Search for needle in haystack.

Parameter haystack

Item to search in. This can be one of:

`string`	When `haystack` is a string `needle` must be a string or an int, and the first occurrence of the string or int is returned.
`array`	When `haystack` is an array, `needle` is compared only to one value at a time in `haystack`.
`mapping`	When `haystack` is a mapping, search() tries to find the index connected to the data `needle`. That is, it tries to lookup the mapping backwards.
`object`	When `haystack` is an object implementing lfun::_search(), the result of calling lfun::_search() with `needle` and `start` will be returned. If `haystack` is an object that doesn't implement lfun::_search() it is assumed to be an Iterator, and implement Iterator()->index(), Iterator()->value(), and Iterator()->next(). search() will then start comparing elements with `==() until a match with `needle` is found. If `needle` is found `haystack` will be advanced to the element, and the iterator index will be returned. If `needle` is not found, `haystack` will be advanced to the end.

Parameter start

If the optional argument start is present search is started at this position.

Returns

Returns the position of needle in haystack if found.

If not found the returned value depends on the type of haystack:

`string\|array`	`-1`.
`mapping\|Iterator`	UNDEFINED.
`object`	The value returned by lfun::_search().

Note

If start is supplied to an iterator object without an lfun::_search(), haystack will need to implement Iterator()->set_index().

Note

For mappings and object UNDEFINED will be returned when not found. In all other cases -1 will be returned when not found.