lines.c File Reference

A utility object for parsing a text file into its component lines. More...

#include "../library/lib.h"
#include "./lines.h"

Include dependency graph for lines.c:

Go to the source code of this file.

Data Structures
struct	lines
	The lines object context. More...

Macros
Private Macros – for internal object use only
#define	LF   10
#define	CR   13

Functions
void *	vpLinesCtor (exception *spEx, const char *cpInput, aint uiLength)
	The lines object constructor. More...
void	vLinesDtor (void *vpCtx)
	The lines object destructor. More...
abool	bLinesFindLine (void *vpCtx, aint uiOffset, aint *uipLine, aint *uipRelOffset)
	Find the line that the given character is in. More...
line *	spLinesFirst (void *vpCtx)
	Initialize an iterator over the lines. More...
line *	spLinesNext (void *vpCtx)
	Returns the next line of text from the iterator. More...
aint	uiLinesCount (void *vpCtx)
	Returns the number of lines of text. More...
aint	uiLinesLength (void *vpCtx)
	Returns the number of text characters. More...

Detailed Description

A utility object for parsing a text file into its component lines.

SABNF grammars and many other files used by parser applications are defined as "lines" of text or characters. Lines are typically ended with one or more of the ASCII control characters

• line feed, 0x0A, \n or LF
• carriage return, 0x0D, \r or CR
• 0x0D0A, \r\n or CRLF

This object provides facilities for iterating and finding lines. See vUtilConvertLineEnds() for an example of using this object to convert and normalize a file's line ends.

Definition in file lines.c.

Macro Definition Documentation

CR

#define CR   13

Definition at line 50 of file lines.c.

LF

#define LF   10

Definition at line 49 of file lines.c.

Function Documentation

bLinesFindLine()

abool bLinesFindLine	(	void *	vpCtx,
		aint	uiOffset,
		aint *	uipLine,
		aint *	uipRelOffset
	)

Find the line that the given character is in.

Parameters

vpCtx	Pointer to a lines context, previously returned from vpLinesCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
uiOffset	The zero-based offset of the character to find.
uipLine	Pointer to an integer, set to the line number that the character is in on return.
uipRelOffset	Pointer to an integer, on return, set to the offset of the character relative to the beginning of the line it is in.

Returns

True if the line is found, false if the line could not be found (i.e. uiOffset is beyond the last character of data).

Definition at line 146 of file lines.c.

spLinesFirst()

line* spLinesFirst

(

void *

vpCtx

)

Initialize an iterator over the lines.

Sets up the iterator and returns the first line.

Parameters

vpCtx

Pointer to a lines context, previously returned from vpLinesCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.

Returns

Pointer to the first line of text.

Definition at line 170 of file lines.c.

spLinesNext()

line* spLinesNext

(

void *

vpCtx

)

Returns the next line of text from the iterator.

Parameters

vpCtx

Pointer to a lines context, previously returned from vpLinesCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.

Returns

pointer to the next line of text on success, NULL if no further lines are available or on failure

Definition at line 185 of file lines.c.

uiLinesCount()

aint uiLinesCount

(

void *

vpCtx

)

Returns the number of lines of text.

Parameters

vpCtx

Pointer to a lines context, previously returned from vpLinesCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.

Returns

The number of lines of text.

Definition at line 202 of file lines.c.

uiLinesLength()

aint uiLinesLength

(

void *

vpCtx

)

Returns the number of text characters.

The number of all characters, including the line ending characters.

Parameters

vpCtx

Pointer to a lines context, previously returned from vpLinesCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.

Returns

The number of characters of text.

Definition at line 218 of file lines.c.

vLinesDtor()

void vLinesDtor

(

void *

vpCtx

)

The lines object destructor.

Releases all allocated memory and clears the context to prevent accidental reuse.

Parameters

vpCtx

A pointer to a valid lines context previously return from vpLinesCtor(). Silently ignored if NULL. However, if non-NULL it must be a valid lines context pointer. The application will silently exit with BAD_CONTEXT exit code if vpCtx is invalid.

Definition at line 123 of file lines.c.

vpLinesCtor()

void* vpLinesCtor	(	exception *	spEx,
		const char *	cpInput,
		aint	uiLength
	)

The lines object constructor.

Reads the character input and separates it into individual lines, generating a list of line structures, one for each line of text.

Parameters

spEx	Pointer to a valid exception structure initialized with XCTOR(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
cpInput	- pointer to the array of characters
uiLength	- the number of characters in the array

Returns

Pointer to the object context. Exception thrown on memory allocation failure.

Definition at line 85 of file lines.c.