NAMES

AllocateTextBuffer, BackwardScanTextBuffer, CopyTextBufferBlock, EndCurrentTextBufferWord, FreeTextBuffer, ForwardScanTextBuffer, GetTextBufferBlock, GetTextBufferBuffer, GetTextBufferChar, GetTextBufferLine, GetTextBufferLocation, IncrementTextBufferLocation, LastTextBufferLocation, LastTextBufferPosition, LineOfPosition, LocationOfPosition, NextLocation, NextTextBufferWord, PositionOfLine, PositionOfLocation, PreviousLocation, PreviousTextBufferWord, ReadFileIntoTextBuffer, ReadFileIntoBuffer, ReadStringIntoTextBuffer, RegisterTextBufferScanFunctions, RegisterTextBufferWordDefinition, RegisterTextBufferUpdate, ReplaceBlockInTextBuffer, ReplaceCharInTextBuffer, SaveTextBuffer, StartCurrentTextBufferWord, TextBuffer Macros, UnregisterTextBufferUpdate

SYNOPSIS and DESCRIPTION

AllocateTextBuffer

Synopsis:

#include <textbuff.h>
  ...
extern TextBuffer ∗ AllocateTextBuffer(

char ∗filename,
TextUpdateFunction f,
XtPointer d);

The AllocateTextBuffer function is used to allocate a new TextBuffer.  After it allocates the structure itself, initializes the members of the structure, allocating storage, setting initial values, etc.  The routine also registers the update function provided by the caller.  This function normally need not be called by an application developer since the ReadFileIntoTextBuffer and ReadStringIntoTextBuffer functions call this routine before starting their operation.  The routine returns a pointer to the allocated TextBuffer.  The FreeTextBuffer function should be used to deallocate the storage allocated by this routine. 

BackwardScanTextBuffer

Synopsis:

The BackwardScanTextBuffer function is used to scan, towards the beginning of the buffer, for a given expression in the TextBuffer starting at location.  A ScanResult is returned which indicates

SCAN_NOTFOUND  The scan wrapped without finding a match.
SCAN_WRAPPED   A match was found at a location after the start location.
SCAN_FOUND     A match was found at a location before the start location.
SCAN_INVALID   Either the location or the expression was invalid.

CopyTextBufferBlock

Synopsis:

#include <textbuff.h>
  ...
extern int CopyTextBufferBlock(

TextBuffer ∗text,
char ∗buffer,
TextPosition start_position,
TextPosition end_position);

The CopyTextBufferBlock function is used to retrieve a text block from the text TextBuffer.  The block is defined as the characters between start_position and end_position inclusive.  It returns the number of bytes copied; if the parameters are invalid the return value is zero (0). 

NOTEThe storage for the copy is allocated by the caller.  It is the responsibility of the caller to ensure that enough storage is allocated to copy end_position - start_position + 1 bytes. 

EndCurrentTextBufferWord

Synopsis:

#include <textbuff.h>
  ...
extern TextLocation EndCurrentTextBufferWord(

TextBuffer ∗textBuffer,
TextLocation current);

The EndCurrentTextBufferWord function is used to locate the end of a word in the TextBuffer relative to a given current location.  The function returns the location of the end of the current word.  Note: this return value will equal the given current value if the current location is already at the end of a word. 

FreeTextBuffer

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern void FreeTextBuffer(

TextBuffer ∗text,
TextUpdateFunction f,
XtPointer d);

The FreeTextBuffer procedure is used to deallocate storage associated with a given TextBuffer.  Note: the storage is not actually freed if the TextBuffer is still associated with other update function/data pairs. 

ForwardScanTextBuffer

Synopsis:

The ForwardScanTextBuffer function is used to scan, towards the end of the buffer, for a given expression in the TextBuffer starting at location.  A ScanResult is returned which indicates

SCAN_NOTFOUND  The scan wrapped without finding a match.
SCAN_WRAPPED   A match was found at a location before the start location.
SCAN_FOUND     A match was found at a location after the start location.
SCAN_INVALID   Either the location or the expression was invalid.

GetTextBufferBlock

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern char ∗GetTextBufferBlock(

TextBuffer ∗text,
TextLocation start_location,
TextLocation end_location);

The GetTextBufferBlock function is used to retrieve a text block from the text TextBuffer.  The block is defined as the characters between start_location and end_location inclusive.  It returns a pointer to a string containing the copy.  If the parameters are invalid NULL is returned. 

NOTEThe storage for the copy is allocated by this routine.  It is the responsibility of the caller to free this storage when it becomes dispensible. 

GetTextBufferBuffer

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern Buffer ∗GetTextBufferBuffer(

TextBuffer ∗text,
TextLine line);

The GetTextBufferBuffer function is used to retrieve a pointer to the Buffer stored in TextBuffer text for line.  This pointer is volatile; subsequent calls to any TextBuffer routine may make it invalid.  If a more permanent copy of this Buffer is required the Buffer Utility CopyBuffer can be used to create a private copy of it. 

GetTextBufferChar

Synopsis:

#include <Xol/textbuff.h>
 . . .
int GetTextBufferChar(

TextBuffer ∗text,
TextLocation location);

The GetTextBufferChar function is used to retrieve a character stored in the text TextBuffer at location.  It returns either the character itself or EOF if location is outside the range of valid locations within the TextBuffer. 

GetTextBufferLine

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern char ∗GetTextBufferLine(

TextBuffer ∗text,
TextLine lineindex);

The GetTextBufferLine function is used to retrieve the contents of line from the text TextBuffer.  It returns a pointer to a string containing the copy of the contents of the line or NULL if the line is outside the range of valid lines in text. 

NOTEThe storage for the copy is allocated by this routine.  It is the responsibility of the caller to free this storage when it becomes dispensable. 

GetTextBufferLocation

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern char ∗GetTextBufferLocation(

TextBuffer ∗text,
TextLine line_number,
TextLocation ∗location);

The GetTextBufferLocation function is used to retrieve the contents of the given line within the TextBuffer.  It returns a pointer to the character string.  If the line number is invalid a NULL pointer is returned.  If a non-NULL TextLocation pointer is supplied in the argument list the contents of this structure are modified to reflect the values corresponding to the given line. 

IncrementTextBufferLocation

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation IncrementTextBufferLocation(

TextBuffer ∗text,
TextLocation location,
TextLine line,
TextPosition offset);

The IncrementTextBufferLocation function is used to increment a location by either line lines and/or offset characters.  It returns the new location.  Note: if line or offset are negative the function performs a decrement operation.  If the starting location or the resulting location is invalid the starting location is returned without modification; otherwise the new location is returned. 

LastTextBufferLocation

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation LastTextBufferLocation(

TextBuffer ∗text);

The LastTextBufferLocation function returns the last valid TextLocation in the TextBuffer associated with text. 

LastTextBufferPosition

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextPosition LastTextBufferPosition(

TextBuffer ∗text);

The LastTextBufferPosition function returns the last valid TextPosition in the TextBuffer associated with text. 

LineOfPosition

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern int LineOfPosition(

TextBuffer ∗text,
TextPosition position);

The LineOfPosition function is used to translate a position in the text TextBuffer to a line index.  It returns the translated line index or EOF if the position is invalid. 

LocationOfPosition

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation LocationOfPosition(

TextBuffer ∗text,
TextPosition position);

The LocationOfPosition function is used to translate a position in the text TextBuffer to a TextLocation.  It returns the translated TextLocation.  If the position is invalid the Buffer pointer buffer is set to NULL and the line and offset members are set the the last valid location in the TextBuffer; otherwise buffer is set to a non-NULL (though useless) value. 

NextLocation

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation NextLocation(

TextBuffer ∗textBuffer,
TextLocation current);

The NextLocation function returns the TextLocation which follows the given current location in a TextBuffer.  If the current location points to the end of the TextBuffer this function wraps. 

NextTextBufferWord

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation NextTextBufferWord(

TextBuffer ∗textBuffer,
TextLocation current);

The NextTextBufferWord function is used to locate the beginning of the next word from a given current location in a TextBuffer.  If the current location is within the last word in the TextBuffer the function wraps to the beginning of the TextBuffer. 

PositionOfLine

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextPosition PositionOfLine(

TextBuffer ∗text,
TextLine lineindex);

The PositionOfLine function is used to translate a lineindex in the text TextBuffer to a TextPosition.  It returns the translated TextPosition or EOF if the lineindex is invalid. 

PositionOfLocation

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextPosition PositionOfLocation(

TextBuffer ∗text,
TextLocation location);

The PositionOfLocation function is used to translate a location in the text TextBuffer to a TextPosition.  The function returns the translated TextPosition or EOF if the location is invalid. 

PreviousLocation

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation PreviousLocation(

TextBuffer ∗textBuffer,
TextLocation current);

The PreviousLocation function returns the Location which precedes the given current location in a TextBuffer.  If the current location points to the beginning of the TextBuffer this function wraps. 

PreviousTextBufferWord

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation PreviousTextBufferWord(

TextBuffer ∗textBuffer,
TextLocation current);

The PreviousTextBufferWord function is used to locate the beginning of a word in a TextBuffer relative to a given current location.  It returns the location of the beginning of the word which precedes the given current location.  If the current location is within a word this function will skip over the current word.  If the current word is the first word in the TextBuffer the function wraps to the end of the buffer. 

ReadFileIntoTextBuffer

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextBuffer ∗ReadFileIntoTextBuffer(

char ∗filename,
TextUpdateFunction f,
XtPointer d);

The ReadFileIntoTextBuffer function is used to read the given file into a newly allocated TextBuffer.  The supplied TextUpdateFunction and data pointer are associated with this TextBuffer. 

ReadStringIntoTextBuffer

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextBuffer ∗ReadStringIntoTextBuffer(

char ∗string,
TextUpdateFunction f,
XtPointer d);

The ReadStringIntoTextBuffer function is used to copy the given string into a newly allocated TextBuffer.  The supplied TextUpdateFunction and data pointer are associated with this TextBuffer. 

RegisterTextBufferScanFunctions

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern void RegisterTextBufferScanFunctions(

char ∗(∗forward)(),
char ∗(∗backward)());

The RegisterTextBufferScanFunctions procedure provides the capability to replace the scan functions used by the ForwardScanTextBuffer and BackwardScanTextBuffer functions.  These functions are called as:

(∗forward)(string, curp, expression);
(∗backward)(string, curp, expression);

and are responsible for returning either a pointer to the begining of a match for the expression or NULL.  Calling this procedure with NULL function pointers reinstates the default regular expression facility. 

RegisterTextBufferWordDefinition

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern void RegisterTextBufferWordDefinition(

int (∗word_definition)());

The RegisterTextBufferWordDefinition procedure provides the capability to replace the word definition function used by the TextBuffer Utilities.  This function is called as:

(∗word_definition)(c);

The function is responsible for returning non-zero if the character c is considered a character that can occur in a word and zero otherwise.  Calling this function with NULL reinstates the default word definition which allows the following set of characters:

a-zA-Z0-9_

RegisterTextBufferUpdate

Synopsis:

#include<textbuff.h>
 . . .
extern void RegisterTextBufferUpdate(

TextBuffer ∗text,
TextUpdateFunction f,
XtPointer d);

The RegisterTextBufferUpdate procedure associates the TextUpdateFunction f and data pointer d with the given TextBuffer text.  This update function will be called whenever an update operation is performed on the TextBuffer.  See ReplaceBlockInTextBuffer for more details. 

NOTECalling this function increments a reference count mechanism used to determine when to actually free the TextBuffer.  Calling the function with a NULL value for the function circumvents this mechanism. 

ReplaceBlockInTextBuffer

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern EditResult ReplaceBlockInTextBuffer(

TextBuffer ∗text,
TextLocation ∗startloc,
TextLocation ∗endloc,
char ∗string,
TextUpdateFunction f,
XtPointer d);

The ReplaceBlockInTextBuffer function is used to update the contents of the TextBuffer associated with text.  The characters stored between startloc and endloc are deleted and the string is inserted after startloc.  If the edit succeeds the TextUpdateFunction f is called with the parameters: d, text, and 1; then any other different update functions associated with the TextBuffer are called with their associated data pointer, text, and 0.  This function records the operation performed in TextUndoItem structures.  The contents of these structures can be used to implement an undo function.  The contents can also be used to determine the type of operation performed.  A structure is allocated for both the delete and insert information.  The hints provided in these structures is the inclusive OR of:

TEXT_BUFFER_NOP
TEXT_BUFFER_INSERT_LINE
TEXT_BUFFER_INSERT_SPLIT_LINE
TEXT_BUFFER_INSERT_CHARS
TEXT_BUFFER_DELETE_START_LINE
TEXT_BUFFER_DELETE_END_LINE
TEXT_BUFFER_DELETE_START_CHARS
TEXT_BUFFER_DELETE_END_CHARS
TEXT_BUFFER_DELETE_JOIN_LINE
TEXT_BUFFER_DELETE_SIMPLE

ReplaceCharInTextBuffer

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern EditResult ReplaceCharInTextBuffer(

TextBuffer ∗text,
TextLocation ∗location,
int c,
TextUpdateFunction f,
XtPointer d);

The ReplaceCharInTextBuffer function is used to replace the character in the TextBuffer text at location with the character c. 

SaveTextBuffer

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern SaveResult SaveTextBuffer(

TextBuffer ∗text,
char ∗filename);

The SaveTextBuffer function is used to write the contents of the text TextBuffer to the file filename.  It returns a SaveResult which can be:

SAVE_FAILURE
SAVE_SUCCESS

StartCurrentTextBufferWord

Synopsis:

#include <Xol/textbuff.h>
 . . .
extern TextLocation StartCurrentTextBufferWord(

TextBuffer ∗textBuffer,
TextLocation current);

The StartCurrentTextBufferWord function is used to locate the beginning of a word in the TextBuffer relative to a given current location.  The function returns the location of the beginning of the current word.  Note: this return value will equal the given current value if the current location is the beginning of a word. 

TextBuffer Macros

The following macros are provided with the text buffer utilities. 

  Table 1 Text Buffer Macros
 

MacroReturns
=
BufferFilled(buffer)flag indicating whether  buffer  is filled
_
BufferLeft(buffer)number of unused elements in  buffer
_
BufferEmpty(buffer)flag indicating whether  buffer  is empty

UnregisterTextBufferUpdate

Synopsis:

#include<textbuff.h>
 . . .
extern int UnregisterTextBufferUpdate(

TextBuffer ∗text,
TextUpdateFunction f,
XtPointerr d);

The UnregisterTextBufferUpdate function disassociates the TextUpdateFunction f and data pointer d with the given TextBuffer text.  If the function/data pointer pair is not associated with the given TextBuffer zero is returned otherwise the association is dissolved and one is returned. 

SEE ALSO

buffer(3w), regularexpression(3w) textedit(3w) textfield(3w) textselection(3w) TextEdit(3w)

Version 3.0  —  Last change: 19 July 91