STRS(3X)

NAME
strs_setup, strs_match, strs_done, strs_search - string matching functions

SYNOPSIS

#include "str.h"

strs_h strs_setup( flags, pattern [, patlen] )
int flags ;
char *pattern ;

char *strs_match( handle, str, len )
strs_h handle ;
char *str ;
int len ;

void strs_done( handle )
strs_h handle ;

char *strs_search( flags, str, len, pattern [, patlen] )
int flags ;
char *str ;
int len ;
char *pattern ;

DESCRIPTION

These functions perform string matching. They have been designed with the assumption that one needs to find a certain pattern in a set of strings. It is also possible to use them to find if a pattern occurs in a specific string.

strs_setup() is used to specify the pattern to look for. It returns a handle which is used in subsequent string matching operations against the specified pattern. The flags argument has two parts: a search method and generic flags. The available search methods include the following algorithms:

    STRS_BF
        brute force algorithm (also called naive in the literature).

    STRS_RK
        Rabin-Karp algorithm (probabilistic).

    STRS_KMP
        Knuth-Morris-Pratt algorithm.

    STRS_SBM
        Simple Boyer-Moore (uses only the last occurrence heuristic).

    STRS_BMH
        This is the Boyer-Moore algorithm using the last occurrence heuristic as modified by Horspool (this is faster than the simple Boyer-Moore).

    STRS_SO
        Shift-Or algorithm (this algorithm works only for patterns whose length does not exceed the number of bits in a word).

The default algorithm is the brute force method. In practice, the fastest algorithm is the Boyer-Moore-Horspool one.

The flags that can be specified include:

    STRS_NOMALLOC
        do not allocate space for the pattern. This can be specified if the pattern space will be available during the matching phase (i.e. do not use this flag if the pattern space was malloc'ed and you free it before doing any matching).

    STRS_IGNCASE
        perform case-insensitive string matching (the default is case-sensitive matching).

    STRS_NOSWITCH
        disallows switching to another search method; a switch to the brute force algorithm happens if the length of the pattern is less than 4 or if the initialization of the specified search algorithm fails (for example, when using the shift-or algorithm with a very long pattern). When this flag is used, no switch happens.

    STRS_PATLEN
        is used to explicitly specify the length of the pattern (with the patlen argument); normally the pattern is assumed to be NUL-terminated.

strs_match() tries to match the string specified by str against the pattern identified by handle. Since the length of the string is given by the len argument the string does not need to be NUL-terminated. strs_done() should be invoked after all matching against the pattern identified by handle is done.

strs_search() is equivalent to:

    h = strs_setup( flags, pattern ) ;
    p = strs_match( h, str, len ) ;
    strs_done( h ) ;
    return( p ) ;

RETURN VALUES

strs_setup() returns a search handle on success or NULL on failure.

strs_match() and strs_search() return a pointer to the first occurrence of the pattern in the string or NULL if the pattern does not occur in the string.

SEE ALSO
Donald E. Knuth, James H. Morris, Vaughan R. Pratt. Fast pattern matching in strings. SIAM Journal on Computing, 6(2):323-350, 1977.

Richard M. Karp, Michael O. Rabin. Efficient randomized pattern-matching algorithms. Technical Report TR-31-81, Aiken Computation Laboratory, Harvard University, 1981.

Robert S. Boyer, J. Strother Moore. A fast string-searching algorithm. Communications of the ACM, 20(10):762-772, 1977.

N. Horspool. Practical fast searching in strings. Software - Practice and Experience, 10:501-506, 1980.

R. Baeza-Yates, G.H. Gonnet. A new approach to text searching. Proceedings of 12th SIGIR, June 1989.

Thomas H. Cormen, Charles E. Leiserson, Ronald L. Rivest. Introduction to Algorithms. McGraw-Hill 1990.