naginterfaces.library.sort.charvec_​search

naginterfaces.library.sort.charvec_search(valid, ch, item, m1=1)

charvec_search examines an ordered vector of strings and returns the index of the first value equal to the sought-after item. Character items are compared according to the ASCII collating sequence.

For full information please refer to the NAG Library document for m01nc

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/m01/m01ncf.html

Parameters

validbool

If $valid$ is set to $True$ argument checking will be performed. If $valid$ is set to $False$ charvec_search will be called without argument checking, which includes checking that array $ch$ is sorted in ascending order and the function will return with no exception or warning is raised. See Further Comments for further details.

chstr, array-like, shape $\left(\text{m2}\right)$

Elements $m1-1$ to $\text{m2}-1$ contain character data to be searched.

itemstr

The sought-after item. Trailing space characters are ignored.

m1int, optional

Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.

The index of the first element of $ch$ to be searched.

Returns

ichint

Note: this argument represents an array index; the value returned will be base-1.

The index of the first value equal to the sought-after item.

Raises

NagValueError

(errno $2$)

On entry, $ch$ must be sorted in ascending order: $ch\text{element}⟨value⟩>\text{element}⟨value⟩$.

(errno $3$)

On entry, $m1=⟨value⟩$.

Constraint: $m1\ge 1$.

(errno $4$)

On entry, $m1=⟨value⟩$, $\text{m2}=⟨value⟩$.

Constraint: $\text{m2}\ge m1$.

(errno $5$)

On entry, the length of each element of $ch$ must be at most $255$: maximum string length $=⟨value⟩$.

Notes

charvec_search is based on Professor Niklaus Wirth’s implementation of the Binary Search algorithm (see Wirth (2004)), but with two modifications. First, if the sought-after item is less than the value of the first element of the array to be searched, $-1$ is returned. Second, if a value equal to the sought-after item is not found, the index of the immediate lower value is returned.

References

Wirth, N, 2004, Algorithms and Data Structures, 35–36, Prentice Hall