/*
** buffer.h
**
**	Written by Peter Sutton, May 2007.
*/

#ifndef BUFFER_H
#define BUFFER_H

/* All operations below work with a Buffer structure. Users of these routines
** don't need to know the internals, so they are not given here.
** A buffer is a data storage area where incoming data is appended, and
** remembered until consumed. The routines below manage the memory allocated
** appopriately.
*/
typedef struct Buffer Buffer;

/* buf_create()
**	Create a buffer, of the given initial storage capacity. Returns a 
**	pointer to the buffer.
*/
Buffer* buf_create(int initialSize);

/* buf_delete()
**	Delete the given buffer, reclaiming all memory used by the buffer. The
** 	buffer must not be used after deletion. (If the buffer argument is 
** 	a null pointer, no action is taken.)
*/
void buf_delete(Buffer* buffer);

/* buf_append()
**	Append the given bytes (the first numBytes pointed to by data) to 
** 	the buffer.
*/
void buf_append(Buffer* buffer, char* data, int numBytes);

/* buf_append_from_fd()
**	Performs a read() operation on the given fd, with any data returned
**	being appended to the buffer. The maximum number of bytes read/appended
**	is as specified. The return value is that from the read() call.
*/
int buf_append_from_fd(Buffer* buffer, int fd, int maxBytes);

/* buf_get_data()
**	Returns a pointer to the first unread byte in the buffer. If a 
**	number of bytes are read, then you should call buf_consume() to 
**	indicate this to the buffer. (The data pointed to will be of the
**	length given by buf_num_bytes_stored(). The byte after this will be 
** 	null character so the return value from this function can be used
** 	as a string if desired.
*/
char* buf_get_data(Buffer* buffer);

/* buf_num_bytes_stored()
**	Returns the number of bytes stored in the buffer that have not 
** 	yet been consumed
*/
int buf_num_bytes_stored(Buffer* buffer);

/* buf_consume()
**	Indicate that the given number of bytes have been read from the buffer.
*/
void buf_consume(Buffer* buffer, int bytesConsumed);

/* buf_extract_line()
**	If there is a newline in the data stored in the buffer, then return
**	a pointer to that line. The line returned will have the newline \n
**	removed (along with a previous carriage return \r if any) and will be
**	null terminated. The data will be marked as consumed, so that the 
**	next time buf_get_data() is called, the following data will be
**	returned. (The pointer returned by this function is a pointer into
**	the data space and is only valid until the next call to a buf_*()
**	function.) 
**	If there is no newline in the data, then a NULL pointer is returned
**	and the buffer is not changed in any way.
*/
char* buf_extract_line(Buffer* buf);

#endif