[thirdparty/sarg.git] / documentation / longline.txt

/*! \file util.c
\brief Various useful functions.
*/


/*! \def INITIAL_LINE_BUFFER_SIZE
The initial buffer size to allocate to read a long line from a text file.
*/


/*! \fn longline longline_create(void)
Prepare the buffer to read long text lines from a file.

\return The object create by the function. It must be freed
with a call to longline_destroy().
*/


/*! \fn void longline_reset(longline line)
Reset the internal state of the object to start a new reading on a new file.

\param line The object created by longline_create().
*/


/*! \fn char *longline_read(FILE *fp_in,longline line)
Read one long line of text from a file. If the buffer is too short, it is
expended until the line can fit in it.

The function always read as many bytes as can fit in the buffer and split the lines
to return one line at a time to the caller. The returned lines are always terminated
by a null ASCII character. The CR or LF are removed.

Any empty line is skipped.

\param fp_in The file to read.
\param line The object created by longline_create().

\return A pointer to the beginning of the string in the buffer or NULL if it is
the last string read.

\note If not enough memory is available to read the line, the program is terminated
with an error message.
*/


/*! \fn void longline_destroy(longline line)
Free the memory allocated by longline_create().

\param line The object to destroy.
*/
Commit	Line	Data
4ca814cc FM	1	/*! \file util.c
	2	\brief Various useful functions.
	3	*/
	4
	5
	6	/*! \def INITIAL_LINE_BUFFER_SIZE
	7	The initial buffer size to allocate to read a long line from a text file.
	8	*/
	9
	10
	11
	12
	13
	14
afaa3b67	15	/*! \fn longline longline_create(void)
4ca814cc FM	16	Prepare the buffer to read long text lines from a file.
4ca814cc FM	17
afaa3b67 FM	18	\return The object create by the function. It must be freed
	19	with a call to longline_destroy().
	20	*/
	21
	22
	23
	24
4ca814cc	25
afaa3b67 FM	26	/*! \fn void longline_reset(longline line)
afaa3b67 FM	27	Reset the internal state of the object to start a new reading on a new file.
4ca814cc	28
afaa3b67	29	\param line The object created by longline_create().
4ca814cc FM	30	*/
	31
	32
	33
	34
	35
afaa3b67	36	/! \fn char longline_read(FILE *fp_in,longline line)
4ca814cc FM	37	Read one long line of text from a file. If the buffer is too short, it is
	38	expended until the line can fit in it.
	39
	40	The function always read as many bytes as can fit in the buffer and split the lines
	41	to return one line at a time to the caller. The returned lines are always terminated
	42	by a null ASCII character. The CR or LF are removed.
	43
	44	Any empty line is skipped.
	45
	46	\param fp_in The file to read.
afaa3b67	47	\param line The object created by longline_create().
4ca814cc FM	48
	49	\return A pointer to the beginning of the string in the buffer or NULL if it is
	50	the last string read.
	51
	52	\note If not enough memory is available to read the line, the program is terminated
	53	with an error message.
	54	*/
	55
	56
	57
	58
	59
afaa3b67 FM	60	/*! \fn void longline_destroy(longline line)
afaa3b67 FM	61	Free the memory allocated by longline_create().
4ca814cc	62
afaa3b67	63	\param line The object to destroy.
4ca814cc	64	*/