NAME

       TextBuffer - operations on unstructured text

SYNOPSIS

       #include <InterViews/textbuffer.h>

DESCRIPTION

       TextBuffer  defines  common  editing, searching, and text movement operations on a buffer of unstructured
       text.  Text positions are specified by an index into the buffer and logically refer to positions  between
       characters.   For  example,  the position referred to by the index 0 is before the first character in the
       text.  Indices can be compared for equality or ordering, but they should not be used to  directly  access
       the buffer because TextBuffer might rearrange the text to improve the efficiency of some operations.

PUBLIC OPERATIONS

       TextBuffer(char* buffer, int length, int size)
       ~TextBuffer()
              Create  or  destroy  an  instance  of  TextBuffer.  All operations on the text contained in buffer
              should be performed through TextBuffer functions.  The text is assumed to be of length length, and
              the total available buffer size is size.

       int Search(Regexp* regexp, int index, int range, int stop)
       int ForwardSearch(Regexp* regexp, int index)
       int BackwardSearch(Regexp* regexp, int index)
              Search  for  a  match  with  the  regular  expression regexp, beginning at position index.  Search
              searches the part of the buffer specified by range and stop and returns the index of the beginning
              of  the  matched  text.   Positive  values  of range specify forward searches, and negative values
              specify backward searches.  In either case, the matched text will not extend beyond  the  position
              given  by  stop.  ForwardSearch searches for matches from index to the end of the text and returns
              the index of the end of the match.  BackwardSearch searches from index to the start  of  the  text
              and returns the index of the beginning of the match.  All three functions return a negative number
              if there was no match.

       int Match(Regexp* regexp, int index, int stop)
       boolean ForwardMatch(Regexp* regexp, int index)
       boolean BackwardMatch(Regexp* regexp, int index)
              Attempt to match the regular expression regexp at the position index.  Match returns the length of
              the matching string, or a negative number if there was no match.  Matching will not succeed beyond
              the position given by stop.  ForwardMatch looks for a match that begins at  index.   BackwardMatch
              looks for a match that ends at index.

       int Insert(int index, const char* string, int count)
       int Delete(int index, int count)
       int Copy(int index, char* buffer, int count)
              Edit  the  text in the buffer.  Insert inserts count characters from string at the position index.
              It returns the actual number of characters inserted, which might be less than count  if  there  is
              insufficient  space  in  the buffer.  Delete deletes count characters from the buffer.  A positive
              count deletes characters after index, and a negative value deletes character before index.  Delete
              returns  the  actual number of characters deleted, which might be less than count if index is near
              the beginning or the end of the text.  Copy copies count characters into buffer.  A positive count
              copies  characters after index and a negative count copies characters before index.  Count returns
              the actual number of characters copied.  It is the caller's responsibility to ensure  that  buffer
              contains sufficient space for the copied text.

       int Height()
       int Width()
       int Length()
              Return  information about the text.  Height returns the number of lines in the text, Width returns
              the number of characters in the longest line, and Length returns the total number of characters.

       const char* Text()
       const char* Text(int index)
       const char* Text(int index1, int index2)
       char Char (int index)
              Access the contents of the text.  Char returns the character  immediately  following  index.   The
              three  Text  calls  return pointers to character strings representing the text.  They make various
              guarantees about the format of the returned string.  With no parameters, Text returns a pointer to
              a string that contains the entire text of the buffer.  With a single parameter the string contains
              at least the text from index to the end of the line.  With two  parameters,  the  returned  string
              contains  at least the text between index1 and index2.  In any case, the returned string should be
              considered temporary and its contents subject to  change.   To  maximize  efficiency,  you  should
              prefer the more restricted forms of Text.

       int LineIndex(int line)
       int LinesBetween(int index1, int index2)
       int LineNumber(int index)
       int LineOffset (int index)
              Map  between  text  indices  and  line  and  offset positions.  LineIndex returns the index of the
              beginning of line  line.   LineNumber  returns  the  number  of  the  line  that  contains  index.
              LineOffset  returns  the  offset of index from the beginning of its containing line.  LinesBetween
              returns the difference between the numbers of the lines containings index1 and  index2;  a  return
              value  of  zero  indicates  that  index1  and  index2  are  on the same line, and a positive value
              indicates that the line containing index2 is after the line containing index1.  Lines are numbered
              starting from zero.

       int PreviousCharacter(int index)
       int NextCharacter(int index)
              Return the index immediately following or preceding index.  The returned value is never before the
              beginning or after the end of the text.

       boolean IsBeginningOfText(int index)
       int BeginningOfText()
       boolean IsEndOfText(int index)
       int EndOfText()
              Return the index of the beginning or end of the text, or query whether index is at  the  beginning
              or end of the text.

       boolean IsBeginningOfLine(int index)
       int BeginningOfLine(int index)
       int BeginningOfNextLine(int index)
       boolean IsEndOfLine(int index)
       int EndOfLine(int index)
       int EndOfPreviousLine(int index)
              Return information about the line structure of the text around index.  BeginningOfLine returns the
              index of the beginning of the line containing index.  BeginningOfNextLine returns the index of the
              beginning of the next line that begins after index.  EndOfLine returns the index of the end of the
              line containing index.  EndOfPreviousLine returns the index of the end of the last line that  ends
              before index.  The beginning of a line is logically immediately after a newline character, and the
              end of a line is logically immediately before a newline character.  The beginning and end  of  the
              text are considered to be the beginning and end of the first and last lines, respectively.

       boolean IsBeginningOfWord(int index)
       int BeginningOfWord(int index)
       int BeginningOfNextWord(int index)
       boolean IsEndOfWord(int index)
       int EndOfWord(int index)
       int EndOfPreviousWord(int index)
              Return information about the word structure of the text around index.  BeginningOfWord returns the
              index of the beginning of the word containing index.  BeginningOfNextWord return the index of  the
              beginning of the nest word that begins after index.  EndOfWord returns the index of the end of the
              word that contains index.  EndOfPreviousWord returns the index of the end of the  last  word  that
              ends  before  index.   A word is defined as a sequence of alpha-numeric characters.  The beginning
              and end of the text are considered to be the beginning and  end  of  the  first  and  last  words,
              respectively.

SEE ALSO

       Regexp(3I)