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)