view.h File Reference

The main source of information for using the View Library. More...

#include "list.h"
#include "tuple.h"
#include "segment.h"

Go to the source code of this file.

Classes
struct	_IOElement
	A single IOElement provides the information necessary to output a single sub-segment. More...
struct	_IOVec
	The structure necessary to output an entire view's sub-segments. More...
struct	_view
	The View structure. More...
Typedefs
typedef _view	View
typedef _IOElement	IOElement
	A single IOElement. Used in each IOVec.
typedef _IOVec	IOVec
	The structure necessary to output an entire view's sub-segments.
Enumerations
enum	segtype { owned, borrowed }
Functions
void	view_Init (void *(*view_allocate)(size_t), void(*view_deallocate)(void *))
	Initialize the view memory allocation routines. The defaults are the system malloc and free. If those are acceptable, use of this function is not necessary.
View *	view_CreateBorrowed (char *input, unsigned int length)
	Create a new View object from a piece of data. The resulting View contains a "borrowed" reference to the data.
View *	view_CreateOwned (char *input, unsigned int length)
	Create a new View object from a piece of data. The resulting View "owns" the data it references.
void	view_Delete (View *view)
	Delete a view.
unsigned int	view_DeleteFront (View *view, unsigned int N)
	Delete the first N characters (bytes) of a view.
unsigned int	view_AppendData (View *view, char *input, unsigned int length)
	Append a new string of data to an existing view.
View *	view_Copy (const View *view)
	Copy a view.
View *	view_CopyFront (const View *view, unsigned int N)
	Copy the first N characters (bytes) of a view.
View *	view_ViewCat (View *v1, const View *v2)
	Concatenate two views together. Same semantics as strcat(), the first view in the argument list is modified and returned.
View *	view_Cut (View *v1, unsigned int cutIndex)
	Cut a view into two pieces.
unsigned int	view_ViewDelete (View *vParent, const View *vChild)
	Delete instances of Child in Parent.
unsigned int	view_GetChar (const View *view, unsigned int pos, char *retval)
	Get a byte from a view.
char *	view_CopyChunk (View *view, unsigned int begin, unsigned int end)
	Copy a chunk (piece) of a view.
unsigned int	view_DeleteChunk (View *view, unsigned int begin, unsigned int end)
	delete a chunk from a view.
unsigned int	view_Length (const View *view)
size_t	view_Strcspn (View *view, const char *charset, size_t s2Len)
	Span the complement of a view. Mimic the BSD C-Library strscpn functionality.
int	view_Strspn (View *view, const char *charset, size_t s2Len)
	Span the initial part of a view. Mimic the BSD C-Library strscpn functionality.
int	view_Strstr (View *view, const char *str2, size_t s2Len)
	Locate a substring within a View.
void	view_Print (View *view)
	Print out a view in readable form.
void	view_DebugPrint (View *view)
	Print out debugging information for a view.
IOVec *	view_IOVec (View *view)
	Get the IOVector of a View.
void	iovec_Delete (IOVec *iovec)
	Deleting a IOVec is a two step process, So here is a helper function to make life easier.

---

Detailed Description

The main source of information for using the View Library.

---

Typedef Documentation

typedef struct _view View

I do this to avoid having to use "struct" everywhere.

---

Enumeration Type Documentation

enum segtype

Used to identify the type of data pointers with the segments. They are either all owned (we can delete them), or they are borrowed (someone else will delete the data).

---

Function Documentation

void iovec_Delete (  IOVec *  iovec  )

Deleting a IOVec is a two step process, So here is a helper function to make life easier. Parameters: iovec  a pointer to an IOVec struct. Returns: void

unsigned int view_AppendData (  View *  view, char *  input, unsigned int  length )

Append a new string of data to an existing view. Returns: 0 for failure. 1 for success. Parameters: view  The view to append a new string segment to. input  The new string segment to append. length  The length of the new string segment to append. This is essential as the string segment may contain embedded NULLs and we cannot use strlen(). Note: Behavior is to create a new segment, and append it to the view. The new segment is viewable in its entirety. If the existing view is comprised of borrowed segments, then the a borrowed reference to the data will be used. If the existing view is comprised of owned segments, then a copy of the input data will be made.

View* view_Copy (  const View *  view  )

Copy a view. Returns: a new View pointer Parameters: view  the view to be copied. Note: This function copies the View object but NOT the underlying segments. They are reference counted.

char* view_CopyChunk (  View *  view, unsigned int  begin, unsigned int  end )

Copy a chunk (piece) of a view. Returns: 0:failure char pointer to the copied chunk on success. Parameters: view  a pointer to a View object. begin  the index to begin the copy operation. end  the index to end the copy operation. Note: View indices begin at 0, and end at view_Length() - 1. So, to copy an entire view do something like: oo = view_CopyChunk(view, 0, view_Length(view)-1);

View* view_CopyFront (  const View *  view, unsigned int  N )

Copy the first N characters (bytes) of a view. Returns: a new View pointer Parameters: view  the view to be copied. N  the number of characters to copy. Note: If N is zero, then the copy operation returns an empty view. This function copies the View object but NOT the underlying segments. They are reference counted.

View* view_CreateBorrowed (  char *  input, unsigned int  length )

Create a new View object from a piece of data. The resulting View contains a "borrowed" reference to the data. Parameters: input  The raw input string/data. length  The length of the data. Returns: Pointer to a new View object. 0 if failed. Note: We can't rely upon strlen to get the data length as the data might contain NULLs. THIS IS REALLY IMPORTANT!!! The newly created view contains a reference to the address of the data. We are "borrowing" the data. If you are using the "borrowed" semantics you cannot do anything before view_Delete() is called that would cause the address to become invalid or reference some other data. Results are undefined in that event. If the above caution did not make sense, you should be using view_CreateOwned().

View* view_CreateOwned (  char *  input, unsigned int  length )

Create a new View object from a piece of data. The resulting View "owns" the data it references. Parameters: input  The raw input string/data. length  The length of the data. Returns: Pointer to a new View object. 0 if failed. Notes: 1: We can't rely upon strlen to get the data length as the data might contain NULLs. 2: This version of view_Create() owns the resulting data reference. Thus, it does not matter where the data came from (heap or stack) or when it is modified as view_CreateOwned MAKES A COPY of the data.

View* view_Cut (  View *  v1, unsigned int  cutIndex )

Cut a view into two pieces. Returns: 0 if there is an error View * upon success. The view pointer is the first half of the original view. Parameters: v1  The view that will be cut into two views. cutIndex  The view location of the cut. Note: The view (v1) is cut into two pieces. v1 is the front-half. The return view pointer is the back-half of the original view.

void view_DebugPrint (  View *  view  )

Print out debugging information for a view. Parameters: view  the view to print out. Returns: void

void view_Delete (  View *  view  )

Delete a view. Parameters: view  pointer to a View object. Returns: void Note: There is only 1 Delete method for all View objects.

unsigned int view_DeleteChunk (  View *  view, unsigned int  begin, unsigned int  end )

delete a chunk from a view. Parameters: view  the view to delete a piece from. begin  the beginning index of the deleted chunk. end  the ending index of the deleted chunk. Returns: 0 success 1 failure Note: The view index values are in view coordinates. Deleted chunks of a view are not recoverable.

unsigned int view_DeleteFront (  View *  view, unsigned int  N )

Delete the first N characters (bytes) of a view. Returns: 0, failure 1, success Parameters: view  the view to delete from. N  the number of character positions to delete from the view. Note: This function operates on the View "in-place".

unsigned int view_GetChar (  const View *  view, unsigned int  pos, char *  retval )

Get a byte from a view. Parameters: view  a pointer to a View object. pos  the position of the character you want to get. Equivalent to the array index. retval  the address of a character that the desired character can be stuffed into. The caller is responsible for allocating this byte. 1 byte, is all this function will every write at the retval address. Returns: 0 success 1 failure, most likely the pos is out of range of the view. 2 failure, most likely the pos is out of range of a sub-segment.

void view_Init (  void *(*  view_allocate)(size_t), void(*  view_deallocate)(void *) )

Initialize the view memory allocation routines. The defaults are the system malloc and free. If those are acceptable, use of this function is not necessary. Parameters: view_allocate  A function pointer to the allocation function you wish to use. This function must have the same semantics as the C-library malloc(): void *malloc(size_t size) view_deallocate  A function pointer to the de-allocation function you wish to use. The function must have the same semantics as the C-library free(): void free(void *ptr) Returns: void Note: If view_Init() is not used, the allocation defaults to malloc() and the deallocation defaults to free(). For examples, look in the test directory.

IOVec* view_IOVec (  View *  view  )

Get the IOVector of a View. Parameters: view  the view to extract the IOVec from. Returns: an array of IOVec structs. zero upon error. Note: Below is an example that demonstrates use of view_IOVec() and its output. Note that since view sub-segments are NOT null-terminated, you cannot rely upon standard C-library functions (like printf) to output a view. iovec = view_IOVec(v1); for (i = 0; i < iovec->vecLength; i++) { printNChars(iovec->vec[i].ptr, iovec->vec[i].length); } void printNChars(char *foo, unsigned int len) { int i = 0; for (i = 0; i < len; i++) { putc(foo[i], stdout); } }

unsigned int view_Length (  const View *  view  )

Returns: total length of the view. Parameters: view  the view we want the length of.

void view_Print (  View *  view  )

Print out a view in readable form. Parameters: view  the view to print out. Returns: void

size_t view_Strcspn (  View *  view, const char *  charset, size_t  s2Len )

Span the complement of a view. Mimic the BSD C-Library strscpn functionality. The view_Strcspn() function spans the initial part of the view as as long as the characters from the view do not occur in the string charset (it spans the complement of charset). Since neither the view nor the charset is null-terminated, a third argument, s2Len must be supplied. Parameters: view  the view to search. charset  the string to use as the character set. s2Len  the length of the charset (s2) used in the comparison. Returns: an integer denoting the number of characters spanned in the view. Note: Despite the cryptic description, this function serves to find a character (anyone within charset) within a View. The span is the index that the character occurs at (+1). This implementation had different semantics than the C-library strcspn(). That is because we cannot rely upon a terminating NULL in s2.

int view_Strspn (  View *  view, const char *  charset, size_t  s2Len )

Span the initial part of a view. Mimic the BSD C-Library strscpn functionality. The view_Strspn() function spans the initial part of the view as as long as the characters from the view occur in the string charset (it spans the charset). Since neither the view nor the charset is null-terminated, a third argument, s2Len must be supplied. Parameters: view  the view to search. charset  the string to use as the character set. s2Len  the length of the charset (s2) used in the comparison. Returns: an integer denoting the number of characters spanned in the view. a negative value if any errors are encountered. Note: This implementation had different semantics than the C-library strcspn(). That is because we cannot rely upon a terminating NULL in s2.

int view_Strstr (  View *  view, const char *  str2, size_t  s2Len )

Locate a substring within a View. Parameters: view  the view to search. str2  the substring to locate. s2Len  the length of str2. Returns: an integer index denoting the beginning of the substring within the view.

View* view_ViewCat (  View *  v1, const View *  v2 )

Concatenate two views together. Same semantics as strcat(), the first view in the argument list is modified and returned. Returns: a View pointer: This is the result of the concatenate operations. 0 if there is an error. Parameters: v1  The view that will be modified and returned. v2  The view that will be concatenated onto the end of v1. Note: You cannot concatenate Views that have different data semantics. If v1 is a "borrowed" view, and v2 is a owned view, the operation will fail.

unsigned int view_ViewDelete (  View *  vParent, const View *  vChild )

Delete instances of Child in Parent. Returns: 0 if sucessful deletion. non-zero if failure. Note: This function will search the parent view for the existence of data in the child view. When such data is located, it is then deleted from the parent view. Any data from vChild that exists in vParent will be deleted, there does not have to be a 100% match. Existing data in the parent view must be a match not only in terms of the data, but in the memory location of that data. Thus, the child view must be a descendant of the parent view for this method to be relevant. A child view would normally be created through view functions like: view_Copy(), or view_ViewCat(). Illustration-1: exact sub-segment match. Parent ---------- ---------- ---------- 0123456789 seg-A seg-B seg-C b e Child ---------- 0123456789 seg-B b e Will result in: Parent ---------- ---------- seg-A seg-C Illustration-2: Partial sub-segment match. Parent ---------- ---------- ---------- 0123456789 seg-A seg-B seg-C b e Child ---------- 0123456789 seg-B b e Will result in: Parent ---------- ---- ---------- 0123 seg-A seg-B seg-C Illustration-3: Parent -------------- 0123456789ABCD seg-B b e Child -------------- 0123456789ABCD seg-B b e Will result in: Parent -------------- 0123456789ABCD seg-B b e Illustration-4: Parent --------------- 01234567890ABCD seg-B b e Child --------------- 01234567890ABCD seg-B b e Will result in: Parent ---- ------ 0123 90ABCD seg-B seg-B b e b e Illustration-5: Parent --------------- 01234567890ABCD seg-B b e Child --------------- 01234567890ABCD seg-B b e Will result in: Parent (no changes) --------------- 01234567890ABCD seg-B b e vParent is modified.

---