TextBuffer(3I)						    InterViews Reference Manual 					    TextBuffer(3I)

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 speci-
	      fied 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.  Back-
	      wardSearch  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  nega-
	      tive  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 charac-
	      ters  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)

InterViews							    23 May 1989 						    TextBuffer(3I)