mirror of
https://github.com/lcn2/calc.git
synced 2025-08-16 01:03:29 +03:00
125 lines
3.7 KiB
Plaintext
125 lines
3.7 KiB
Plaintext
NAME
|
|
search - search for an element satisfying a specified condition
|
|
|
|
SYNOPSIS
|
|
search(a, b [, [c] [, [d] ] ])
|
|
|
|
TYPES
|
|
a matrix, list, association or file
|
|
b string if a is a file, otherwise any
|
|
c integer, defaults to zero or current file-position
|
|
d integer, defaults to size(a) or current file-position
|
|
|
|
return nonnegative integer or null value
|
|
|
|
DESCRIPTION
|
|
|
|
Negative values of c and nonpositive values for d are treated as
|
|
offsets from size(a), i.e. as if c were replaced by size(a) + c,
|
|
and d by size(a) + d. Any such adjustment is assumed in the following
|
|
description.
|
|
|
|
|
|
For Non-file a:
|
|
|
|
For a matrix, list, or association a,
|
|
search(a, b, c, d) returns, if it exists, the least index i for which
|
|
c <= i < d, 0 <= i < size(a), and, if accept() has not been defined,
|
|
a[[i]] == b, or if accept() has been defined, accept(a[[i]], b)
|
|
tests as nonzero. The null value is returned if there is no such i.
|
|
|
|
For example, to search for the first a[[i]] > b an appropriate
|
|
accept() function is given by:
|
|
|
|
define accept(v,b) = (v > b);
|
|
|
|
To restore the original behavior of search(), one may then use
|
|
|
|
define accept(v, b) = (v == b).
|
|
|
|
Since the addresses (rather than values) of a and b are passed,
|
|
the values of v = x[[i]] and b may be changed during execution
|
|
of search(a, b, c, d), e.g. if accept(v,b) has been defined by
|
|
|
|
define accept(v,b) = (v > b ? v-- : b++);
|
|
|
|
|
|
For a is a file-stream:
|
|
|
|
c defaults to the current file-position if there are just two
|
|
arguments (a,b) or if there are four arguments as in (a,b, ,d)
|
|
where d is an integer. Otherwise c defaults to zero.
|
|
|
|
d defaults to the current file-position or size(a) according as
|
|
the number of arguments (indicated by commas) is four or less
|
|
than four.
|
|
|
|
If a is a file, a string formed by n successive characters in a
|
|
is considered to occur at the file position
|
|
of the first character. E.g. if a has the characters "123456",
|
|
the string "345" is said to occur at position 2.
|
|
|
|
The file is searched forwards from file-position pos = c for
|
|
a match with b (not including the terminating '\0').
|
|
Only characters with file-positions less than d are considered,
|
|
so the effective interval for the first-character position pos
|
|
for a matching string is limited by both c <= pos <= d - strlen(b)
|
|
and 0 <= pos < size(a) - strlen(b).
|
|
|
|
The function returns pos if a match is found, and the reading position
|
|
for the stream after the search will then correspond to the position of
|
|
the terminating '\0' for the string b.
|
|
|
|
The null value is returned if no match is found. If c, d, size(a)
|
|
and strlen(b) are such that no match is possible, no reading of the
|
|
file occurs and the current file-position is not changed. In a case
|
|
where characters are read, the final file-position will be
|
|
min(d, size(a)) - strlen(b) + 1,
|
|
i.e. the file will be at the first position where a match is impossible
|
|
because the specified search region has insufficient remaining characters.
|
|
|
|
EXAMPLE
|
|
> L = list(2,"three",4i)
|
|
> search(L,"three")
|
|
1
|
|
> search(L,"threes")
|
|
> search(L, 4i, 4)
|
|
> search(L, 4i, 1)
|
|
2
|
|
|
|
> f = fopen("foo", "w+")
|
|
> fputs(f, "This file has 28 characters.")
|
|
> rewind(f)
|
|
> search(f, "ha")
|
|
10
|
|
> ftell(f)
|
|
12
|
|
> search(f, "ha")
|
|
18
|
|
> search(f, "ha")
|
|
> search(f, "ha",)
|
|
10
|
|
> search(f, "ha", 12)
|
|
18
|
|
> search(f, "ha", -10)
|
|
18
|
|
> search(f, "ha", ,)
|
|
10
|
|
> search(f, "ha", 11, 19)
|
|
> ftell(f)
|
|
18
|
|
> search(f, "ha", 11, 20)
|
|
18
|
|
> search(f, "ha", 5, 500)
|
|
10
|
|
|
|
LIMITS
|
|
none
|
|
|
|
LIBRARY
|
|
none
|
|
|
|
SEE ALSO
|
|
assoc, list, mat, rsearch
|
|
|