X11 Work Bench Toolkit  1.0
File Buffer 'helper' functions

Data Structures

struct  __file_help_buf__
 basic 'buffered I/O' object structure for 'FileBuf' APIs More...
 

Typedefs

typedef struct __file_help_buf__ file_help_buf_t
 basic 'buffered I/O' object structure for 'FileBuf' APIs More...
 

Enumerations

enum  __file_help_buf_flags__ {
  file_help_buf_dirty = 1, file_help_buf_reserved01 = 2, file_help_buf_reserved02 = 4, file_help_buf_reserved03 = 8,
  file_help_buf_reserved04 = 16, file_help_buf_reserved05 = 32, file_help_buf_reserved06 = 64, file_help_buf_reserved07 = 128,
  file_help_buf_reserved08 = 256, file_help_buf_last = 0x80000000L
}
 bit flags for file_help_buf_t 'iFlags' member More...
 

Functions

static __inline__ int FBIsFileBufDirty (const file_help_buf_t *pBuf)
 Inline function, returns TRUE if file_help_buf_t is 'dirty'. More...
 
file_help_buf_tFBGetFileBufViaHandle (int iHandle)
 Construct a file_help_buf_t from a file handle. More...
 
file_help_buf_tFBGetFileBufFromBuffer (const char *pBuf, long cbBuf)
 Construct a file_help_buf_t from a buffer. More...
 
file_help_buf_tFBGetFileBuf (const char *szFileName)
 Construct a file_help_buf_t from a file. More...
 
void FBDestroyFileBuf (file_help_buf_t *pFB)
 Destroy a file_help_buf_t object. More...
 
int FBParseFileBuf (file_help_buf_t *pFB)
 Parse or Re-Parse the data for a file_help_buf_t object. More...
 
int FBWriteFileBuf (const char *szFileName, const file_help_buf_t *pFB)
 Write the file_help_buf_t object's text data to a file using a filename. More...
 
int FBWriteFileBufHandle (int iHandle, const file_help_buf_t *pFB)
 Write the file_help_buf_t object's text data to a file using an open file handle. More...
 
void FBInsertIntoFileBuf (file_help_buf_t **ppBuf, long cbOffset, const void *pData, long cbData)
 Insert text into a file_help_buf_t object at a specific byte offset. More...
 
void FBDeleteFromFileBuf (file_help_buf_t *pBuf, long cbOffset, long cbDelFrom)
 Delete text from a file_help_buf_t object at a specific byte offset. More...
 
void FBInsertLineIntoFileBuf (file_help_buf_t **ppBuf, long lLineNum, const char *szLine)
 Insert a line of text into a file_help_buf_t object at a specific line index. More...
 
void FBDeleteLineFromFileBuf (file_help_buf_t *pBuf, long lLineNum)
 Delete a line of text from a file_help_buf_t object at a specific line index. More...
 
void FBReplaceLineInFileBuf (file_help_buf_t **ppBuf, long lLineNum, const char *szLine)
 Insert a line of text into a file_help_buf_t object at a specific line index. More...
 
static __inline__ int FBWriteFileFromBuffer (const char *szFileName, const char *pBuf, unsigned int cbBuf)
 Write a file from a regular buffer using a file name. More...
 

Detailed Description

Utility functions and structures associated with line-based buffered file I/O.

An abstracted set of API functions that allow you to manage line-based text editing using a basic structure as a 'File Buffer' object.

Typedef Documentation

basic 'buffered I/O' object structure for 'FileBuf' APIs

This structure is intended to assist implementing buffered I/O for files that contain multiple lines separated by linefeeds. A 'file edit' window or dialog control could use one of these objects to assist with displaying and editing text based on the contents of a file. It would also be possible to construct a file_help_buf_t object from a memory buffer as well as from a text file.

typedef struct __file_help_buf__
{
struct __file_help_buf__ *pPrev; // pointer to 'previous' item in linked list (NULL for owner object)
struct __file_help_buf__ *pNext; // pointer to 'next' item in linked list (NULL for last object)
long lBufferSize; // size of entire buffer
long lBufferCount; // number of bytes of valid data
long lLineCount; // number of lines in 'cData' when ppLineBuf not NULL
long lLineBufSize; // size of memory block pointed to by 'ppLineBuf'
int iFlags; // various bit flags
char **ppLineBuf; // array of pointers to beginning of each line (WBAlloc'd TODO: make it part of 'cData'?)
char cData[sizeof(char *)]; // the data itself (aligned to size of a pointer)

TODO: 'ppLineBuf' should point to an area within cData. If 'pNext' is valid, subsequent lines could be pointed to by the 'ppLineBuf' within the structure pointed to by 'pNext'. In this way line pointers can be re-structured without re-allocating memory. Additionally, there is no reason why lines must be contiguous, so inserting and removing lines can make use of the additional allocated space pointed to by 'pNext'.
As it would become fragmented, it would also be a good idea to re-build the structure periodically using FBParseFileBuf()

Enumeration Type Documentation

bit flags for file_help_buf_t 'iFlags' member

These are the bit flag definitions for the file_help_buf_t 'iFlags' member

Definition at line 160 of file file_help.h.

Function Documentation

void FBDeleteFromFileBuf ( file_help_buf_t pBuf,
long  cbOffset,
long  cbDelFrom 
)

Delete text from a file_help_buf_t object at a specific byte offset.

Parameters
pBufA valid pointer to a file_help_buf_t
cbOffsetThe offset within the text for insertion. This must NOT split MBCS or UTF-8 characters!
cbDelFromThe number of bytes of text to remove. This must NOT split MBCS or UTF-8 characters!

Use this function to delete a specified number of bytes of text from a file_help_buf_t object at a specific byte offset
This function sets the 'dirty' flag.

Definition at line 434 of file file_help.c.

void FBDeleteLineFromFileBuf ( file_help_buf_t pBuf,
long  lLineNum 
)

Delete a line of text from a file_help_buf_t object at a specific line index.

Parameters
pBufA valid pointer to a file_help_buf_t
lLineNumThe 0-based line index at which to perform the delete. An index greater than or equal to the total number of lines will be ignored.

Use this function to delete a line of text from a file_help_buf_t object at a specific 0-based line number.
This function sets the 'dirty' flag.
NOTE: this is a line-based abstraction for FBDeleteFromFileBuf(). Automatically re-parses as needed

Definition at line 525 of file file_help.c.

void FBDestroyFileBuf ( file_help_buf_t pFB)

Destroy a file_help_buf_t object.

Parameters
pFBA valid pointer to a file_help_buf_t

Use this function to destroy a file_help_buf_t constructured by one of the 'FB' constructor utilities FBGetFileBufViaHandle(), FBGetFileBufFromBuffer(), or FBGetFileBuf().

Definition at line 186 of file file_help.c.

file_help_buf_t* FBGetFileBuf ( const char *  szFileName)

Construct a file_help_buf_t from a file.

Parameters
szFileNameAn ASCII string containing the file name
Returns
A valid pointer to a file_help_buf_t, or NULL on error

Use this function to construct a file_help_buf_t from a named file. On success the function returns a valid pointer, that must be subsequently destroyed using FBDestroyFileBuf().
On error, this function returns a NULL pointer.

Definition at line 106 of file file_help.c.

file_help_buf_t* FBGetFileBufFromBuffer ( const char *  pBuf,
long  cbBuf 
)

Construct a file_help_buf_t from a buffer.

Parameters
pBufA pointer to a memory buffer that contains the text data
cbBufThe length of the data pointed to by 'pBuf'
Returns
A valid pointer to a file_help_buf_t, or NULL on error

Use this function to construct a file_help_buf_t from a buffer. Suitable for 'memory only' operations. On success the function returns a valid pointer, that must be subsequently destroyed using FBDestroyFileBuf().
On error, this function returns a NULL pointer.

Definition at line 159 of file file_help.c.

file_help_buf_t* FBGetFileBufViaHandle ( int  iHandle)

Construct a file_help_buf_t from a file handle.

Parameters
iHandleA handle to an open file (must allow random access).
Returns
A valid pointer to a file_help_buf_t, or NULL on error

Use this function to construct a file_help_buf_t from a file handle. On success the function returns a valid pointer, that must be subsequently destroyed using FBDestroyFileBuf().
On error, this function returns a NULL pointer.

Definition at line 123 of file file_help.c.

void FBInsertIntoFileBuf ( file_help_buf_t **  ppBuf,
long  cbOffset,
const void *  pData,
long  cbData 
)

Insert text into a file_help_buf_t object at a specific byte offset.

Parameters
ppBufA valid pointer to a pointer variable for a file_help_buf_t object
This parameter is also used for the returned pointer to the file_help_buf_t, which may change as needed.
cbOffsetThe offset within the text for insertion. This must NOT split MBCS or UTF-8 characters!
pDataA pointer to the text data to be inserted
cbDataThe number of bytes of text data to insert.

Use this function to insert a specific number of bytes of text into a file_help_buf_t object at a specific byte offset.
This function sets the 'dirty' flag.

Definition at line 406 of file file_help.c.

void FBInsertLineIntoFileBuf ( file_help_buf_t **  ppBuf,
long  lLineNum,
const char *  szLine 
)

Insert a line of text into a file_help_buf_t object at a specific line index.

Parameters
ppBufA valid pointer to a pointer variable for a file_help_buf_t object
This parameter is also used for the returned pointer to the file_help_buf_t, which may change as needed.
lLineNumThe 0-based line index at which to perform the insert. Specifying an index greater than or equal to the total number of lines inserts the line at the end of the text.
szLineA pointer to a line of ASCII text. An ending line feed, if missing, is implied.

Use this function to insert a line of text into a file_help_buf_t object at a specific 0-based line number.
This function sets the 'dirty' flag.
NOTE: this is a line-based abstraction for FBInsertIntoFileBuf(). Automatically re-parses as needed

Definition at line 461 of file file_help.c.

static __inline__ int FBIsFileBufDirty ( const file_help_buf_t pBuf)
static

Inline function, returns TRUE if file_help_buf_t is 'dirty'.

Parameters
pBufA valid pointer to a file_help_buf_t
Returns
Non-zero if the buffer has the 'dirty' flag set, zero otherwise.

Use this function (in lieu of directly checking iFlags) to determine if the contents of the file_help_buf_t is 'dirty' and needs to be written to disk.

Definition at line 184 of file file_help.h.

int FBParseFileBuf ( file_help_buf_t pFB)

Parse or Re-Parse the data for a file_help_buf_t object.

Parameters
pFBA valid pointer to a file_help_buf_t
Returns
0 on success, non-zero on error

Use this function to parse or re-parse the data within the file_help_buf_t object. This will re-allocate memory as needed to accomplish the desired goal.
The function returns 0 on success, non-zero on error.
The resulting parsed data is placed into the 'ppLineBuf' member.

Definition at line 209 of file file_help.c.

void FBReplaceLineInFileBuf ( file_help_buf_t **  ppBuf,
long  lLineNum,
const char *  szLine 
)

Insert a line of text into a file_help_buf_t object at a specific line index.

Parameters
ppBufA valid pointer to a pointer variable for a file_help_buf_t object
This parameter is also used for the returned pointer to the file_help_buf_t, which may change as needed.
lLineNumThe 0-based line index at which to replace text. Specifying an index greater than or equal to the total number of lines inserts the line at the end of the text, similar to FBInsertLineIntoFileBuf().
szLineA pointer to a line of ASCII text. An ending line feed, if missing, is implied.

Use this function to replace a line of text within a file_help_buf_t object at a specific 0-based line number.
This function sets the 'dirty' flag.
NOTE: this is a line-based abstraction for both FBInsertIntoFileBuf() and FBDeleteFromFileBuf(). Automatically re-parses as needed.

Definition at line 561 of file file_help.c.

int FBWriteFileBuf ( const char *  szFileName,
const file_help_buf_t pFB 
)

Write the file_help_buf_t object's text data to a file using a filename.

Parameters
szFileNameAn ASCII file name to which to write the text data (an existing file of the same name will be overwritten)
pFBA valid pointer to a file_help_buf_t
Returns
0 on success, non-zero on error

Use this function to write the text data for a file_help_buf_t object into a file using the filename. This also clears the 'dirty' flag.
The function returns 0 on success, non-zero on error.

Definition at line 281 of file file_help.c.

int FBWriteFileBufHandle ( int  iHandle,
const file_help_buf_t pFB 
)

Write the file_help_buf_t object's text data to a file using an open file handle.

Parameters
iHandleAn open file handle to the output file (requires random access)
pFBA valid pointer to a file_help_buf_t
Returns
0 on success, non-zero on error

Use this function to write the text data for a file_help_buf_t object into a file using an open file handle. This also clears the 'dirty' flag.
The function returns 0 on success, non-zero on error.

Definition at line 303 of file file_help.c.

static __inline__ int FBWriteFileFromBuffer ( const char *  szFileName,
const char *  pBuf,
unsigned int  cbBuf 
)
static

Write a file from a regular buffer using a file name.

Parameters
szFileNameA const pointer to a 0-byte terminated string containing a file name
pBufA const pointer to a buffer containing data to write, or NULL if no data is to be written
cbBufThe byte count to write from 'pBuf'.
Returns
A value of zero if successful, non-zero on error

Definition at line 371 of file file_help.h.