karoo::text Class Reference

This class implements thread-safe, memory efficient text strings. More...

#include <util.h>

Inheritance diagram for karoo::text:

List of all members.

Classes

class clonea

This class is a convenience class for containing a small block of memory which is a clone of the text string in a text object. More...

class text_data

This class is the class that holds the data which the text class uses.

Public Member Functions

text ()

Create an empty text object.

text (text_data *s)

Create a text object using an existing text_data object.

text (const text &s)

Copy constructor.

text (size_t length, char ch)

Create a text string that is made up of multiples of one character.

text (const char *str)

Construct a text object directly from a c_str.

text (const char *str, size_t length)

Create a text object from a string with a specified length (rather than '' terminated).

text (const text &str, size_t index, ssize_t length=-1)

Create a text object from a substring.

bool operator== (const text &c2) const

bool operator!= (const text &c2) const

bool operator< (const text &c2) const

bool operator> (const text &c2) const

bool operator<= (const text &c2) const

bool operator>= (const text &c2) const

const text & operator+= (const text &append)

const text & operator+= (const char *append)

const text & operator+= (const char append)

const text & operator= (const text &s)

const text & operator= (const char *s)

const text & operator= (char ch)

bool operator== (const hashable &ref) const

bool operator!= (const hashable &ref) const

bool operator>= (const hashable &ref) const

bool operator<= (const hashable &ref) const

bool operator> (const hashable &ref) const

bool operator< (const hashable &ref) const

bool substringCompare (const char *s, size_t ssz, size_t from) const

bool substringCompare (const char *s, size_t from) const

bool substringCompare (const text &s, size_t from) const

char operator[] (size_t index) const

Get a character from the string, by index.

char at (size_t index) const

Get a character from the string, by index.

char set (size_t index, char ch)

Set a particular character.

const text & append (const text &str)

Append to the end of this text string.

const text & append (const char *str)

Append to the end of this text string.

const text & append (const text &str, size_t index, ssize_t len=-1)

Append to the end of this text string, using a substring of another string.

const text & append (const char *str, size_t num)

Append to the end of this text string.

const text & append (size_t num, char ch)

Append characters to the end of the string.

const text & assign (const text &str)

This re-assigns the string with new text.

const text & assign (const char *str)

This re-assigns the string with new text.

const text & assign (const char *str, size_t num)

This re-assigns the string with new text.

const text & assign (const text &str, size_t index, ssize_t len=-1)

This re-assigns the string with a substring from another string.

const text & assign (size_t num, char ch)

This re-assigns the string with new text (a character repeated num times).

clonea c_str_clonea (size_t *bytes=NULL) const

Create a temporary copy of the string.

char * c_str_clone (size_t *bytes=NULL) const

Create a copy of this string's memory, allocated by malloc() This memory will need to be freed up by you.

char * new_clone (size_t *bytes=NULL) const

get a cloned c_str (array of characters) allocated freshly by new, and containing a copy of the text.

int atoi () const

Convert the string to an integer.

void clear ()

Make the string zero length.

bool empty () const

Check if the string is zero length.

ssize_t find (const text &str, size_t index=0) const

Get the starting index of a substring.

ssize_t find (const char *str, size_t index=0, ssize_t length=-1) const

Get the starting index of a substring.

ssize_t find (char ch, size_t index=0, char respect_quote= '\0') const

Get the starting index of a character.

ssize_t rfind (char ch, ssize_t from=-1) const

Get the starting index of a character, searching back from the end of the string.

size_t length () const

Get the length of the string.

size_t capacity () const

Get the current size of the buffer, this will always be larger than the string length, by at least 1.

text substr (size_t index, ssize_t length=-1)

Extract a substring from this text string.

void writeOut (ostream &out) const

Output this string to an output stream.

void erase (size_t from=0, ssize_t len=-1)

Remove some of the string.

void write (const char *buf, size_t sz)

Write to the string (as if it is a stream).

void write (const char *val)

Write to the string (as if it is a stream).

void write (const text &val)

Write to the string (as if it is a stream).

void write (char val)

Write to the string (as if it is a stream).

void write (bool val)

Write to the string (as if it is a stream).

void write (uint32_t val)

Write to the string (as if it is a stream).

void write (uint64_t val)

Write to the string (as if it is a stream).

void write (int32_t val)

Write to the string (as if it is a stream).

void write (int64_t val)

Write to the string (as if it is a stream).

void write (double val)

Write to the string (as if it is a stream).

void write (long double val)

Write to the string (as if it is a stream).

text & operator<< (const text &str)

text & operator<< (const char *str)

text & operator<< (char val)

text & operator<< (bool val)

text & operator<< (uint16_t val)

text & operator<< (uint32_t val)

text & operator<< (uint64_t val)

text & operator<< (int16_t val)

text & operator<< (int32_t val)

text & operator<< (int64_t val)

text & operator<< (float val)

text & operator<< (double val)

text & operator<< (long double val)

text & appendDateString (time_t secs)

Format a date string and append it to this text string.

uint32_t getHash () const

Get an integer hash value.

time_t parseDate () const

Parse a date string (such as the format used in HTTP headers).

time_t parseRFC850Date () const

Parse an RFC850 formatted date string (such as the format used in HTTP headers).

time_t parseRFC1123Date () const

Parse an RFC1123 formatted date string (such as the format used in HTTP headers).

time_t parseasctimeDate () const

Parse an asctime formatted date string (such as the format used in HTTP headers).

hashable * clone () const

Create a clone of this string.

text replace (char c, const char *s, size_t num) const

Create a text string that is a copy of this string, except to replace any instances of the specified character.

Protected Member Functions

void lock () const

This convenience function is provided so that other text objects can lock on this object's semaphore.

void unlock () const

This convenience function is provided so that other text objects can release the lock.

Protected Attributes

karoo_mutex sem

This lock is used to ensure than concurrent reads/modifications of the test_data don't occur.

text_data * data

this is a pointer to the actual text data

Friends

text operator+ (const text &s1, const text &s2)

text operator+ (const char *s, const text &s2)

text operator+ (char c, const text &s2)

text operator+ (const text &s1, const char *s)

text operator+ (const text &s1, char c)

Detailed Description

This class implements thread-safe, memory efficient text strings.

Constructor & Destructor Documentation

karoo::text::text ( text_data * s )

Create a text object using an existing text_data object.

Parameters:

s

the text_data object which will be referenced by this new text object.

karoo::text::text ( const text & s )

Copy constructor.

This will re-reference the same data, rather than copy it.

karoo::text::text	(	size_t	length,
		char	ch
	)

Create a text string that is made up of multiples of one character.

Parameters:

	length	the number of characters in the string.
	ch	the character to be repeated

karoo::text::text ( const char * str )

Construct a text object directly from a c_str.

Parameters:

str

the '' terminated string to create the text from.

karoo::text::text	(	const char *	str,
		size_t	length
	)

Create a text object from a string with a specified length (rather than '' terminated).

Parameters:

	str	the string to create the text from
	length	the length of the string

karoo::text::text	(	const text &	str,
		size_t	index,
		ssize_t	length = `-1`
	)

Create a text object from a substring.

Parameters:

	str	the string to get the substring from
	index	the first character's index
	length	the number of characters to copy, after and including the index. If length is -1, then go right to the end of str.

Member Function Documentation

const text& karoo::text::append	(	size_t	num,
		char	ch
	)

Append characters to the end of the string.

Parameters:

	length	the number of repeats if the character
	ch	the character to be repeated

const text& karoo::text::append	(	const char *	str,
		size_t	num
	)

Append to the end of this text string.

Parameters:

	str	the string to append to the end.
	num	the number of characters to append from str

const text& karoo::text::append	(	const text &	str,
		size_t	index,
		ssize_t	len = `-1`
	)

Append to the end of this text string, using a substring of another string.

Parameters:

	str	the string to use as the basis for the substring
	index	the starting point in the str value, to get the substring to be appended.
	len	the number of characters to append. If len is -1, then append all the characters (after the index) from str.

const text& karoo::text::append ( const char * str ) [inline]

Append to the end of this text string.

Parameters:

str

the string to append to the end.

const text& karoo::text::append ( const text & str ) [inline]

Append to the end of this text string.

Parameters:

str

the string to append to the end.

text& karoo::text::appendDateString ( time_t secs )

Format a date string and append it to this text string.

Parameters:

secs

the number of seconds since epoch

Returns:: a reference to this string

const text& karoo::text::assign	(	size_t	num,
		char	ch
	)

This re-assigns the string with new text (a character repeated num times).

Parameters:

	num	the number of times to repeat the character.
	the	character to repeat.

const text& karoo::text::assign	(	const text &	str,
		size_t	index,
		ssize_t	len = `-1`
	)

This re-assigns the string with a substring from another string.

Parameters:

	str	the string to get the substring from.
	index	the first character's index
	len	the number of characters to copy, after and including the index. If len is -1, then go right to the end of str.

const text& karoo::text::assign	(	const char *	str,
		size_t	num
	)

This re-assigns the string with new text.

Parameters:

	str	the string to copy.
	num	the number of characters in the string

const text& karoo::text::assign ( const char * str ) [inline]

This re-assigns the string with new text.

Parameters:

str

the string to copy.

const text& karoo::text::assign ( const text & str ) [inline]

This re-assigns the string with new text.

This will re-reference the same data, rather than copy it.

Parameters:

str

the string tp copy.

char karoo::text::at ( size_t index ) const

Get a character from the string, by index.

Parameters:

index

the index of the character in the string

Referenced by operator[]().

int karoo::text::atoi ( ) const

Convert the string to an integer.

Returns:: the integer that was represented in textual form in the string.

char* karoo::text::c_str_clone ( size_t * bytes = NULL ) const

Create a copy of this string's memory, allocated by malloc() This memory will need to be freed up by you.

Parameters:

bytes

if this is non-NULL, then the size of the string will be written here.

clonea karoo::text::c_str_clonea ( size_t * bytes = NULL ) const

Create a temporary copy of the string.

This avoids any race conditions, and it will automatically free its own memory when it goes out of scpope.

An important point to note is that you probably won't need to call this method directly, but rather use this: TEMP_STRING(str) ... where str is the text object. e.g.

 text path;
 ...
 ifstream is(TEMP_STRING(path), ios::binary);

This TEMP_STRING(str) is not a function, it is a macro, which calls text::c_str_clonea() to get a temporarily allocated string on the stack. There is no need to delete this, it is auto freed when the current stack frame is exited, exactly as in the case of a call to strdupa().

Parameters:

bytes

if this is non-NULL, then the size of the string will be written here.

size_t karoo::text::capacity ( ) const

Get the current size of the buffer, this will always be larger than the string length, by at least 1.

Returns:: the size of the buffer.

bool karoo::text::empty ( ) const

Check if the string is zero length.

Returns:: true if the string is empty.

void karoo::text::erase	(	size_t	from = `0`,
		ssize_t	len = `-1`
	)

Remove some of the string.

Parameters:

	from	the starting position to start erasing from
	len	the number of characters to erase

ssize_t karoo::text::find	(	char	ch,
		size_t	index = `0`,
		char	respect_quote = `'\0'`
	)			const

Get the starting index of a character.

Parameters:

	ch	the character to search for
	index	the starting index in the string (don't look for the substring before this index)
	respect_quote	the quote character to respect, or a '' if quotes should be ignored

Returns:: the index of the substring, or -1 if not found.

ssize_t karoo::text::find	(	const char *	str,
		size_t	index = `0`,
		ssize_t	length = `-1`
	)			const

Get the starting index of a substring.

Parameters:

	str	the substring to search for
	index	the starting index in the string (don't look for the substring before this index)
	length	the length of the str to search for, or -1 if str is '' terminated

Returns:: the index of the substring, or -1 if not found.

ssize_t karoo::text::find	(	const text &	str,
		size_t	index = `0`
	)			const

Get the starting index of a substring.

Parameters:

	str	the substring to search for
	index	the starting index in the string (don't look for the substring before this index)

Returns:: the index of the substring, or -1 if not found.

uint32_t karoo::text::getHash ( ) const

Get an integer hash value.

This is a determinitstic hash, using the sdbm algorithm.

Returns:: the hash value.

size_t karoo::text::length ( ) const

Get the length of the string.

Returns:: the length of the string

char* karoo::text::new_clone ( size_t * bytes = NULL ) const

get a cloned c_str (array of characters) allocated freshly by new, and containing a copy of the text.

Parameters:

bytes

if non NULL, then the number of bytes (length of string) will be written here.

Returns:: the newly allocated c_str.

char karoo::text::operator[] ( size_t index ) const [inline]

Get a character from the string, by index.

Parameters:

index

the index of the character in the string

References at().

time_t karoo::text::parseasctimeDate ( ) const

Parse an asctime formatted date string (such as the format used in HTTP headers).

Returns:: the number of secods since epoch.

time_t karoo::text::parseDate ( ) const

Parse a date string (such as the format used in HTTP headers).

This auto determines the protocol.

Returns:: the number of secods since epoch.

time_t karoo::text::parseRFC1123Date ( ) const

Parse an RFC1123 formatted date string (such as the format used in HTTP headers).

Returns:: the number of secods since epoch.

time_t karoo::text::parseRFC850Date ( ) const

Parse an RFC850 formatted date string (such as the format used in HTTP headers).

Returns:: the number of secods since epoch.

text karoo::text::replace	(	char	c,
		const char *	s,
		size_t	num
	)			const

Create a text string that is a copy of this string, except to replace any instances of the specified character.

Parameters:

	c	the character to be replaced
	s	the character(s) to use as the replacement
	num	the number of characters in the replacement string

ssize_t karoo::text::rfind	(	char	ch,
		ssize_t	from = `-1`
	)			const

Get the starting index of a character, searching back from the end of the string.

Parameters:

	ch	the character to search for
	from	the caharacter position to search back from, or -1 if from the end

Returns:: the index of the substring, or -1 if not found.

char karoo::text::set	(	size_t	index,
		char	ch
	)

Set a particular character.

Parameters:

	index	the index of the character in the string
	ch	the new character value Note that this text class does not allow you to modify a character using the [] operator. This is because the [] operator does not return a reference to the character. References into the memory managed by a class immediately makes the class not thread-safe.

text karoo::text::substr	(	size_t	index,
		ssize_t	length = `-1`
	)

Extract a substring from this text string.

Parameters:

	index	the starting position within the text string
	length	the number of characters to copy, or if -1, go right to the end of the string

Returns:: the substring.

bool karoo::text::substringCompare	(	const text &	s,
		size_t	from
	)			const

Parameters:

	s	the string to compare with
	from	the position to start comparing with

Returns:: true if found

bool karoo::text::substringCompare	(	const char *	s,
		size_t	from
	)			const

Parameters:

	s	the string to compare with
	from	the position to start comparing with

Returns:: true if found

bool karoo::text::substringCompare	(	const char *	s,
		size_t	ssz,
		size_t	from
	)			const

Parameters:

	s	the string to compare with
	ssz	the lenth of the string to compare with
	from	the position to start comparing with

Returns:: true if found

void karoo::text::write ( long double val )