history: Searching the History List

1 
1 2.3.5 Searching the History List
1 --------------------------------
1 
1 These functions allow searching of the history list for entries
1 containing a specific string.  Searching may be performed both forward
1 and backward from the current history position.  The search may be
1 "anchored", meaning that the string must match at the beginning of the
1 history entry.
1 
1  -- Function: int history_search (const char *string, int direction)
1      Search the history for STRING, starting at the current history
1      offset.  If DIRECTION is less than 0, then the search is through
1      previous entries, otherwise through subsequent entries.  If STRING
1      is found, then the current history index is set to that history
1      entry, and the value returned is the offset in the line of the
1      entry where STRING was found.  Otherwise, nothing is changed, and a
1      -1 is returned.
1 
1  -- Function: int history_search_prefix (const char *string, int
1           direction)
1      Search the history for STRING, starting at the current history
1      offset.  The search is anchored: matching lines must begin with
1      STRING.  If DIRECTION is less than 0, then the search is through
1      previous entries, otherwise through subsequent entries.  If STRING
1      is found, then the current history index is set to that entry, and
1      the return value is 0.  Otherwise, nothing is changed, and a -1 is
1      returned.
1 
1  -- Function: int history_search_pos (const char *string, int direction,
1           int pos)
1      Search for STRING in the history list, starting at POS, an absolute
1      index into the list.  If DIRECTION is negative, the search proceeds
1      backward from POS, otherwise forward.  Returns the absolute index
1      of the history element where STRING was found, or -1 otherwise.
1