Efficiently build up Strings from pieces. More...

Public Types
typedef const char *	const_iterator

typedef char *	iterator

typedef int(StringAccum::*	unspecified_bool_type) () const

Public Member Functions
	StringAccum ()
	Construct an empty StringAccum (with length 0).

	StringAccum (int capacity)
	Construct a StringAccum with room for at least capacity characters.

	StringAccum (const String &str)
	Construct a StringAccum containing the characters in str.

	StringAccum (const StringAccum &x)
	Construct a StringAccum containing a copy of x.

	~StringAccum ()
	Destroy a StringAccum, freeing its memory.

StringAccum &	operator= (const StringAccum &x)
	Assign this StringAccum to x.

const char *	data () const
	Return the contents of the StringAccum.

char *	data ()

int	length () const
	Return the length of the StringAccum.

int	capacity () const
	Return the StringAccum's current capacity.

const char *	c_str ()
	Null-terminate this StringAccum and return its data.

	operator unspecified_bool_type () const
	Test if the StringAccum contains characters.

bool	empty () const
	Test if the StringAccum is empty.

bool	operator! () const
	Test if the StringAccum is empty.

const_iterator	begin () const
	Return an iterator for the first character in the StringAccum.

iterator	begin ()

const_iterator	end () const
	Return an iterator for the end of the StringAccum.

iterator	end ()

char	operator[] (int i) const
	Return the ith character in the string.

char &	operator[] (int i)
	Return a reference to the ith character in the string.

char	front () const
	Return the first character in the string.

char &	front ()
	Return a reference to the first character in the string.

char	back () const
	Return the last character in the string.

char &	back ()
	Return a reference to the last character in the string.

bool	out_of_memory () const
	Test if the StringAccum is out-of-memory.

void	assign_out_of_memory ()
	Change this StringAccum into an out-of-memory StringAccum.

void	clear ()
	Clear the StringAccum's comments.

char *	reserve (int n)
	Reserve space for at least n characters.

void	set_length (int len)
	Set the StringAccum's length to len.

int	resize (int len)
	Set the StringAccum's length to len.

void	adjust_length (int delta)
	Adjust the StringAccum's length.

char *	extend (int nadjust, int nreserve=0)
	Reserve space and adjust length in one operation.

void	pop_back (int n=1)
	Remove characters from the end of the StringAccum.

void	append (char c)
	Append character c to the StringAccum.

void	append (unsigned char c)

bool	append_utf8 (int ch)
	Append Unicode character ch encoded in UTF-8.

void	append (const char *cstr)
	Append the null-terminated C string s to this StringAccum.

void	append (const char *s, int len)
	Append the first len characters of s to this StringAccum.

void	append (const unsigned char *s, int len)

void	append (const char first, const char last)
	Append the data from first to last to the end of this StringAccum.

void	append (const unsigned char first, const unsigned char last)

void	append_fill (int c, int len)
	Append len copies of character c to the StringAccum.

void	append_numeric (String::intmax_t x, int base=10, bool uppercase=true)
	Append string representation of x to this StringAccum.

void	append_numeric (String::uintmax_t x, int base=10, bool uppercase=true)

StringAccum &	snprintf (int n, const char *format,...) CLICK_SNPRINTF_ATTR
	Append result of snprintf() to this StringAccum.

String	take_string ()
	Return a String object with this StringAccum's contents.

void	swap (StringAccum &x)
	Swap this StringAccum's contents with x.

void	forward (int delta)

Related Symbols
(Note that these are not member symbols.)
StringAccum &	operator<< (StringAccum &sa, char c)
	Append character c to StringAccum sa.

StringAccum &	operator<< (StringAccum &sa, unsigned char c)
	Append character c to StringAccum sa.

StringAccum &	operator<< (StringAccum &sa, const char *cstr)
	Append null-terminated C string cstr to StringAccum sa.

StringAccum &	operator<< (StringAccum &sa, bool x)
	Append "true" or "false" to sa, depending on x.

StringAccum &	operator<< (StringAccum &sa, short x)
	Append decimal representation of x to sa.

StringAccum &	operator<< (StringAccum &sa, const String &str)
	Append the contents of str to sa.

StringAccum &	operator<< (StringAccum &sa, const StringAccum &x)
	Append the contents of x to sa.

StringAccum &	operator<< (StringAccum &sa, long i)
	Append decimal representation of i to sa.

StringAccum &	operator<< (StringAccum &sa, unsigned long u)
	Append decimal representation of u to sa.

StringAccum &	operator<< (StringAccum &sa, double d)
	Append decimal representation of d to sa.

StringAccum &	operator<< (StringAccum &sa, const void *ptr)
	Append hexadecimal representation of ptr's value to sa.

Detailed Description

Efficiently build up Strings from pieces.

Like the String class, StringAccum represents a string of characters. However, unlike a String, a StringAccum is inherently mutable, and efficiently supports building up a large string from many smaller pieces.

StringAccum objects support operator<<() operations for most fundamental data types. A StringAccum is generally built up by operator<<(), and then turned into a String by the take_string() method. Extracting the String from a StringAccum does no memory allocation or copying; the StringAccum's memory is donated to the String.

Out-of-memory StringAccums

When there is not enough memory to add requested characters to a StringAccum object, the object becomes a special "out-of-memory" StringAccum. Out-of-memory objects are contagious: the result of any concatenation operation involving an out-of-memory StringAccum is another out-of-memory StringAccum. Calling take_string() on an out-of-memory StringAccum returns an out-of-memory String.

Note that appending an out-of-memory String to a StringAccum does not make the StringAccum out-of-memory.

Constructor & Destructor Documentation

◆ StringAccum() [1/4]

StringAccum::StringAccum ( )

inline

Construct an empty StringAccum (with length 0).

◆ StringAccum() [2/4]

StringAccum::StringAccum ( int capacity )

inlineexplicit

Construct a StringAccum with room for at least capacity characters.

Parameters

capacity initial capacity

If capacity == 0, the StringAccum is created empty. If capacity is too large (so that capacity bytes of memory can't be allocated), the StringAccum falls back to a smaller capacity (possibly zero).

◆ StringAccum() [3/4]

StringAccum::StringAccum ( const String & str )

inline

Construct a StringAccum containing the characters in str.

◆ StringAccum() [4/4]

StringAccum::StringAccum ( const StringAccum & x )

inline

Construct a StringAccum containing a copy of x.

◆ ~StringAccum()

StringAccum::~StringAccum ( )

inline

Destroy a StringAccum, freeing its memory.

Member Function Documentation

◆ operator=()

StringAccum & StringAccum::operator= ( const StringAccum & x )

inline

Assign this StringAccum to x.

◆ data() [1/2]

const char * StringAccum::data ( ) const

inline

Return the contents of the StringAccum.

Returns: The StringAccum's contents.

The returned data() value points to length() bytes of writable memory (unless the StringAccum itself is const).

◆ data() [2/2]

char * StringAccum::data ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ length()

int StringAccum::length ( ) const

inline

Return the length of the StringAccum.

◆ capacity()

int StringAccum::capacity ( ) const

inline

Return the StringAccum's current capacity.

The capacity is the maximum length the StringAccum can hold without incurring a memory allocation. Returns -1 for out-of-memory StringAccums.

◆ c_str()

const char * StringAccum::c_str ( )

Null-terminate this StringAccum and return its data.

Note that the null character does not contribute to the StringAccum's length(), and later append() and similar operations can overwrite it. If appending the null character fails, the StringAccum becomes out-of-memory and the returned value is a null string.

◆ operator unspecified_bool_type()

StringAccum::operator unspecified_bool_type ( ) const

inline

Test if the StringAccum contains characters.

◆ empty()

bool StringAccum::empty ( ) const

inline

Test if the StringAccum is empty.

◆ operator!()

bool StringAccum::operator! ( ) const

inline

Test if the StringAccum is empty.

Returns true iff length() == 0.

◆ begin() [1/2]

StringAccum::const_iterator StringAccum::begin ( ) const

inline

Return an iterator for the first character in the StringAccum.

StringAccum iterators are simply pointers into string data, so they are quite efficient.

See also: StringAccum::data

◆ begin() [2/2]

StringAccum::iterator StringAccum::begin ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ end() [1/2]

StringAccum::const_iterator StringAccum::end ( ) const

inline

Return an iterator for the end of the StringAccum.

The return value points one character beyond the last character in the StringAccum.

◆ end() [2/2]

StringAccum::iterator StringAccum::end ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ operator[]() [1/2]

char StringAccum::operator[] ( int i ) const

inline

Return the ith character in the string.

Parameters

i	character index

Precondition: 0 <= i < length()

◆ operator[]() [2/2]

char & StringAccum::operator[] ( int i )

inline

Return a reference to the ith character in the string.

Parameters

i	character index

Precondition: 0 <= i < length()

◆ front() [1/2]

char StringAccum::front ( ) const

inline

Return the first character in the string.

Precondition: length() > 0

◆ front() [2/2]

char & StringAccum::front ( )

inline

Return a reference to the first character in the string.

Precondition: length() > 0

◆ back() [1/2]

char StringAccum::back ( ) const

inline

Return the last character in the string.

Precondition: length() > 0

◆ back() [2/2]

char & StringAccum::back ( )

inline

Return a reference to the last character in the string.

Precondition: length() > 0

◆ out_of_memory()

bool StringAccum::out_of_memory ( ) const

inline

Test if the StringAccum is out-of-memory.

◆ assign_out_of_memory()

void StringAccum::assign_out_of_memory ( )

Change this StringAccum into an out-of-memory StringAccum.

◆ clear()

void StringAccum::clear ( )

inline

Clear the StringAccum's comments.

All characters in the StringAccum are erased. Also resets the StringAccum's out-of-memory status.

◆ reserve()

char * StringAccum::reserve ( int n )

inline

Reserve space for at least n characters.

Returns: a pointer to at least n characters, or null if allocation fails

Precondition: n >= 0

reserve() does not change the string's length(), only its capacity(). In a frequent usage pattern, code calls reserve(), passing an upper bound on the characters that could be written by a series of operations. After writing into the returned buffer, adjust_length() is called to account for the number of characters actually written.

◆ set_length()

void StringAccum::set_length ( int len )

inline

Set the StringAccum's length to len.

Parameters

len	new length in characters

Precondition: 0 <= len <= capacity()

See also: adjust_length

◆ resize()

int StringAccum::resize ( int len )

Set the StringAccum's length to len.

Precondition: len >= 0

Returns: 0 on success, -ENOMEM on failure

◆ adjust_length()

void StringAccum::adjust_length ( int delta )

inline

Adjust the StringAccum's length.

Parameters

delta length adjustment

Precondition: If delta > 0, then length() + delta <= capacity(). If delta < 0, then length() + delta >= 0.

The StringAccum's length after adjust_length(delta) equals its old length plus delta. Generally adjust_length() is used after a call to reserve().

See also: set_length

◆ extend()

char * StringAccum::extend	(	int	nadjust,
		int	nreserve = `0`
	)

inline

Reserve space and adjust length in one operation.

Parameters

nadjust	number of characters to reserve and adjust length
nreserve	additional characters to reserve

Precondition: nadjust >= 0 and nreserve >= 0

This operation combines the effects of reserve(nadjust + nreserve) and adjust_length(nadjust). Returns the result of the reserve() call.

◆ pop_back()

void StringAccum::pop_back ( int n = 1 )

inline

Remove characters from the end of the StringAccum.

Parameters

n	number of characters to remove

Precondition: n >= 0 and n <= length()

Same as adjust_length(-n).

◆ append() [1/7]

void StringAccum::append ( char c )

inline

Append character c to the StringAccum.

Parameters

c	character to append

◆ append() [2/7]

void StringAccum::append ( unsigned char c )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ append_utf8()

bool StringAccum::append_utf8 ( int ch )

inline

Append Unicode character ch encoded in UTF-8.

Returns: true if character was valid.

Appends nothing if ch is not a valid Unicode character.

◆ append() [3/7]

void StringAccum::append ( const char * cstr )

inline

Append the null-terminated C string s to this StringAccum.

Parameters

s	data to append

◆ append() [4/7]

void StringAccum::append	(	const char *	s,
		int	len
	)

inline

Append the first len characters of s to this StringAccum.

Parameters

s	data to append
len	length of data

Precondition: len >= 0

◆ append() [5/7]

void StringAccum::append	(	const unsigned char *	s,
		int	len
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ append() [6/7]

void StringAccum::append	(	const char *	first,
		const char *	last
	)

inline

Append the data from first to last to the end of this StringAccum.

Does nothing if first >= last.

◆ append() [7/7]

void StringAccum::append	(	const unsigned char *	first,
		const unsigned char *	last
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ append_fill()

void StringAccum::append_fill	(	int	c,
		int	len
	)

Append len copies of character c to the StringAccum.

◆ append_numeric() [1/2]

void StringAccum::append_numeric	(	String::intmax_t	num,
		int	base = `10`,
		bool	uppercase = `true`
	)

Append string representation of x to this StringAccum.

Parameters

x	number to append
base	numeric base: must be 8, 10, or 16
uppercase	true means use uppercase letters in base 16

◆ append_numeric() [2/2]

void StringAccum::append_numeric	(	String::uintmax_t	num,
		int	base = `10`,
		bool	uppercase = `true`
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ snprintf()

StringAccum & StringAccum::snprintf	(	int	n,
		const char *	format,
			...
	)

Append result of snprintf() to this StringAccum.

Parameters

n	maximum number of characters to print
format	format argument to snprintf()

Returns: *this

The terminating null character is not appended to the string.

Note: The safe vsnprintf() variant is called if it exists. It does in the Linux kernel, and on modern Unix variants. However, if it does not exist on your machine, then this function is actually unsafe, and you should make sure that the printf() invocation represented by your arguments will never write more than n characters, not including the terminating null.

◆ take_string()

String StringAccum::take_string ( )

Return a String object with this StringAccum's contents.

This operation donates the StringAccum's memory to the returned String. After a call to take_string(), the StringAccum object becomes empty, and any future append() operations may cause memory allocations. If the StringAccum is out-of-memory, the returned String is also out-of-memory, but the StringAccum's out-of-memory state is reset.

◆ swap()

void StringAccum::swap ( StringAccum & x )

Swap this StringAccum's contents with x.

Friends And Related Symbol Documentation

◆ operator<<() [1/11]

StringAccum & operator<<	(	StringAccum &	sa,
		char	c
	)

never

Returns: sa

Note: Same as sa.append(c).

◆ operator<<() [2/11]

StringAccum & operator<<	(	StringAccum &	sa,
		unsigned char	c
	)

Returns: sa

Note: Same as sa.append(c).

◆ operator<<() [3/11]

StringAccum & operator<<	(	StringAccum &	sa,
		const char *	cstr
	)

Returns: sa

Note: Same as sa.append(cstr).

◆ operator<<() [4/11]

StringAccum & operator<<	(	StringAccum &	sa,
		bool	x
	)

Returns: sa

◆ operator<<() [5/11]

StringAccum & operator<<	(	StringAccum &	sa,
		short	x
	)

Returns: sa

◆ operator<<() [6/11]

StringAccum & operator<<	(	StringAccum &	sa,
		const String &	str
	)

Returns: sa

◆ operator<<() [7/11]

StringAccum & operator<<	(	StringAccum &	sa,
		const StringAccum &	x
	)

Returns: sa

◆ operator<<() [8/11]

StringAccum & operator<<	(	StringAccum &	sa,
		long	i
	)

Returns: sa

◆ operator<<() [9/11]

StringAccum & operator<<	(	StringAccum &	sa,
		unsigned long	u
	)

Returns: sa

◆ operator<<() [10/11]

StringAccum & operator<<	(	StringAccum &	sa,
		double	d
	)

Returns: sa

◆ operator<<() [11/11]

StringAccum & operator<<	(	StringAccum &	sa,
		const void *	ptr
	)

Returns: sa

The documentation for this class was generated from the following files:

include/click/straccum.hh
lib/straccum.cc

Public Types

Public Member Functions

Related Symbols

Detailed Description

Out-of-memory StringAccums

Constructor & Destructor Documentation

◆ StringAccum() [1/4]

◆ StringAccum() [2/4]

◆ StringAccum() [3/4]

◆ StringAccum() [4/4]

◆ ~StringAccum()

Member Function Documentation

◆ operator=()

◆ data() [1/2]

◆ data() [2/2]

◆ length()

◆ capacity()

◆ c_str()

◆ operator unspecified_bool_type()

◆ empty()

◆ operator!()

◆ begin() [1/2]

◆ begin() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ front() [1/2]

◆ front() [2/2]

◆ back() [1/2]

◆ back() [2/2]

◆ out_of_memory()

◆ assign_out_of_memory()

◆ clear()

◆ reserve()

◆ set_length()

◆ resize()

◆ adjust_length()

◆ extend()

◆ pop_back()

◆ append() [1/7]

◆ append() [2/7]

◆ append_utf8()

◆ append() [3/7]

◆ append() [4/7]

◆ append() [5/7]

◆ append() [6/7]

◆ append() [7/7]

◆ append_fill()

◆ append_numeric() [1/2]

◆ append_numeric() [2/2]

◆ snprintf()

◆ take_string()

◆ swap()

Friends And Related Symbol Documentation

◆ operator<<() [1/11]

◆ operator<<() [2/11]

◆ operator<<() [3/11]

◆ operator<<() [4/11]

◆ operator<<() [5/11]

◆ operator<<() [6/11]

◆ operator<<() [7/11]

◆ operator<<() [8/11]

◆ operator<<() [9/11]

◆ operator<<() [10/11]

◆ operator<<() [11/11]