Data Structures
struct	tag_file_help_buf
	basic 'buffered I/O' object structure for 'FileBuf' APIs More...

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

Enumerations
enum	tag_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_t *	FBGetFileBufViaHandle (int iHandle)
	Construct a file_help_buf_t from a file handle. More...

file_help_buf_t *	FBGetFileBufFromBuffer (const char *pBuf, long cbBuf)
	Construct a file_help_buf_t from a buffer. More...

file_help_buf_t *	FBGetFileBuf (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.

header file: file_help.h

Typedef Documentation

◆ file_help_buf_t

file_help_buf_t

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 tag_file_help_buf
{
  struct tag_file_help_buf *pPrev; // pointer to 'previous' item in linked list (NULL for owner object)
  struct tag_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)
} file_help_buf_t;

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()

header file: file_help.h

Enumeration Type Documentation

◆ tag_file_help_buf_flags

enum tag_file_help_buf_flags

bit flags for file_help_buf_t 'iFlags' member

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

header file: file_help.h

Definition at line 184 of file file_help.h.

Function Documentation

◆ FBDeleteFromFileBuf()

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

pBuf	A valid pointer to a file_help_buf_t
cbOffset	The offset within the text for insertion. This must NOT split MBCS or UTF-8 characters!
cbDelFrom	The 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.

header file: file_help.h

Definition at line 434 of file file_help.c.

◆ FBDeleteLineFromFileBuf()

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

pBuf	A valid pointer to a file_help_buf_t
lLineNum	The 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

header file: file_help.h

Definition at line 525 of file file_help.c.

◆ FBDestroyFileBuf()

void FBDestroyFileBuf ( file_help_buf_t * pFB )

Destroy a file_help_buf_t object.

Parameters

pFB	A 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().

header file: file_help.h

Definition at line 186 of file file_help.c.

◆ FBGetFileBuf()

file_help_buf_t* FBGetFileBuf ( const char * szFileName )

Construct a file_help_buf_t from a file.

Parameters

szFileName An 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 .\n On error, this function returns a NULL pointer.

header file: file_help.h

Definition at line 106 of file file_help.c.

◆ FBGetFileBufFromBuffer()

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

Construct a file_help_buf_t from a buffer.

Parameters

pBuf	A pointer to a memory buffer that contains the text data
cbBuf	The 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 .\n On error, this function returns a NULL pointer.

header file: file_help.h

Definition at line 159 of file file_help.c.

◆ FBGetFileBufViaHandle()

file_help_buf_t* FBGetFileBufViaHandle ( int iHandle )

Construct a file_help_buf_t from a file handle.

Parameters

iHandle A 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 .\n On error, this function returns a NULL pointer.

header file: file_help.h

Definition at line 123 of file file_help.c.

◆ FBInsertIntoFileBuf()

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

ppBuf	A 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.
cbOffset	The offset within the text for insertion. This must NOT split MBCS or UTF-8 characters!
pData	A pointer to the text data to be inserted
cbData	The 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.

header file: file_help.h

Definition at line 406 of file file_help.c.

◆ FBInsertLineIntoFileBuf()

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

ppBuf	A 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.
lLineNum	The 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.
szLine	A 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

header file: file_help.h

Definition at line 461 of file file_help.c.

◆ FBIsFileBufDirty()

static __inline__ int FBIsFileBufDirty ( const file_help_buf_t * pBuf )

static

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

Parameters

pBuf	A 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.

header file: file_help.h

Definition at line 210 of file file_help.h.

◆ FBParseFileBuf()

int FBParseFileBuf ( file_help_buf_t * pFB )

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

Parameters

pFB	A 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.

header file: file_help.h

Definition at line 209 of file file_help.c.

◆ FBReplaceLineInFileBuf()

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

ppBuf	A 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.
lLineNum	The 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().
szLine	A 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.

header file: file_help.h

Definition at line 561 of file file_help.c.

◆ FBWriteFileBuf()

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

szFileName	An ASCII file name to which to write the text data (an existing file of the same name will be overwritten)
pFB	A 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.
header file: file_help.h

Definition at line 281 of file file_help.c.

◆ FBWriteFileBufHandle()

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

iHandle	An open file handle to the output file (requires random access)
pFB	A 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.
header file: file_help.h

Definition at line 303 of file file_help.c.

◆ FBWriteFileFromBuffer()

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

szFileName	A const pointer to a 0-byte terminated string containing a file name
pBuf	A const pointer to a buffer containing data to write, or NULL if no data is to be written
cbBuf	The byte count to write from 'pBuf'.

Returns: A value of zero if successful, non-zero on error

header file: file_help.h

Definition at line 423 of file file_help.h.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ file_help_buf_t

Enumeration Type Documentation

◆ tag_file_help_buf_flags

Function Documentation

◆ FBDeleteFromFileBuf()

◆ FBDeleteLineFromFileBuf()

◆ FBDestroyFileBuf()

◆ FBGetFileBuf()

◆ FBGetFileBufFromBuffer()

◆ FBGetFileBufViaHandle()

◆ FBInsertIntoFileBuf()

◆ FBInsertLineIntoFileBuf()

◆ FBIsFileBufDirty()

◆ FBParseFileBuf()

◆ FBReplaceLineInFileBuf()

◆ FBWriteFileBuf()

◆ FBWriteFileBufHandle()

◆ FBWriteFileFromBuffer()