{The S-Lang C Library Reference}: SLsearch interface Functions

Next Previous Contents

## 3. SLsearch interface Functions

## 3.1 SLsearch_new

Synopsis

  Create an SLsearch_Type object

Usage

  `SLsearch_Type *SLsearch_new (SLuchar_Type *key, int search_flags)`

Description

  The `SLsearch_new` function instantiates an `SLsearch_Type` object for use in ordinary searches (non-regular expression) by the functions in the SLsearch interface. The first argument `key` is a pointer to a null terminated string that specifies the character string to be searched. This character string may not contain any embedded null characters.

  The second argument `search_flags` is used to specify how the search is to be performed. It is a bit-mapped integer whose value is constructed by the bitwise-or of zero or more of the following:

  > `

  >        SLSEARCH_CASELESS
  >          The search shall be performed in a case-insensitive manner.

  >        SLSEARCH_UTF8
  >          Both the search string and the text to be searched is UTF-8
  >          encoded.

  > `

  Upon sucess, the function returns the newly created object, and `NULL` otherwise. When the search object is nolonger needed, it should be freed via the `SLsearch_delete` function.

See Also

  `SLsearch_delete, SLsearch_forward, SLsearch_backward`

## 3.2 SLsearch_delete

Synopsis

  Free the memory associated with a SLsearch_Type object

Usage

  `SLsearch_delete (SLsearch_Type *)`

Description

  This function should be called to free the memory associated with a `SLsearch_Type` object created by the `SLsearch_new` function. Failure to do so will result in a memory leak.

See Also

  `SLsearch_new, SLsearch_forward, SLsearch_backward`

## 3.3 SLsearch_forward

Synopsis

  Search forward in a buffer

Usage

  `SLuchar_Type SLsearch_forward (st, pmin, pmax)`

  > `

  >        SLsearch_Type *st;
  >        SLuchar_Type *pmin, *pmax;

  > `

Description

  The `SLsearch_forward` function searches forward in the buffer defined by the pointers `pmin` and `pmax`. The starting point for the search is at the beginning of the buffer at `pmin`. At no point will the bytes at `pmax` and beyond be examined. The first parameter `st`, obtained by a prior call to `SLsearch_new`, specifies the object to found. be found from a previous call to `SLsearch_new`.

  If the object was found, the pointer to the beginning of it will be returned. Otherwise, `SLsearch_forward` will return `NULL`. The length of the object may be obtained via the `SLsearch_match_len` function.

Notes

  This function uses the Boyer-Moore search algorithm when possible.

See Also

  `SLsearch_new, SLsearch_backward, SLsearch_delete, SLsearch_match_len`

## 3.4 SLsearch_backward

Synopsis

  Search backward in a buffer

Usage

  `SLuchar_Type SLsearch_forward (st, pmin, pstart, pmax)`

  > `

  >        SLsearch_Type *st;
  >        SLuchar_Type *pmin, *pstart, *pmax;

  > `

Description

  The `SLsearch_forward` function searches backward in the buffer defined by the pointers `pmin` and `pmax`. The starting point for the search is at the position `pstart`. At no point will the bytes at `pmax` and beyond be examined. The first parameter `st`, obtained by a prior call to `SLsearch_new`, specifies the object to found.

  If the object was found, the pointer to the beginning of it will be returned. Otherwise, `SLsearch_forward` will return `NULL`. The length of the object may be obtained via the `SLsearch_match_len` function.

Notes

  This function uses the Boyer-Moore search algorithm when possible.

  It is possible for the end of match to appear after the point where the search began (`pstart`).

See Also

  `SLsearch_new, SLsearch_forward, SLsearch_delete, SLsearch_match_len`

## 3.5 SLsearch_match_len

Synopsis

  Get the length of the previous match

Usage

  `unsigned int SLsearch_match_len (SLsearch_Type *st)`

Description

  The `SLsearch_match_len` function returns the length of the match from the most recent search involving the specified `SLsearch_Type` object. If the most recent search was unsuccessful, the function will return 0.

See Also

  `SLsearch_forward, SLsearch_backward, SLsearch_new, SLsearch_delete`

Next Previous Contents