String Class Reference

List of all members.

---

Detailed Description

A string of characters.

The String class represents a string of characters. Strings may be constructed from C strings, characters, numbers, and so forth. They may also be added together. The underlying character arrays are dynamically allocated; String operations allocate and free memory as needed. A String and its substrings generally share memory. Accessing a character by index takes O(1) time; so does creating a substring.

Initialization

The String implementation must be explicitly initialized before use; see static_initialize(). Explicit initialization is used because static constructors and other automatic initialization tricks don't work in the kernel. However, at user level, you can declare a String::Initializer object to initialize the library.

Out-of-memory strings

When there is not enough memory to create a particular string, a special "out-of-memory" string is returned instead. Out-of-memory strings are contagious: the result of any concatenation operation involving an out-of-memory string is another out-of-memory string. Thus, the final result of a series of String operations will be an out-of-memory string, even if the out-of-memory condition occurs in the middle.

Out-of-memory strings have zero characters, but they aren't equal to other empty strings. If s is a normal String (even an empty string), and oom is an out-of-memory string, then s < oom.

All out-of-memory strings are equal and share the same data(), which is different from the data() of any other string. See String::out_of_memory_data(). The String::make_out_of_memory() function returns an out-of-memory string.

Public Types
typedef int64_t	int_large_t
typedef uint64_t	uint_large_t
typedef const char *	const_iterator
typedef const_iterator	iterator
typedef int(String::*)	unspecified_bool_type () const
Public Member Functions
	String ()
	Construct an empty String (with length 0).
	String (const String &x)
	Construct a copy of the String x.
	String (const char *cstr)
	Construct a String containing the C string cstr.
	String (const char *s, int len)
	Construct a String containing the first len characters of string s.
	String (const char *begin, const char *end)
	Construct a String containing the characters from begin to end.
	String (bool x)
	Construct a String equal to "true" or "false" depending on the value of x.
	String (char c)
	Construct a String containing the single character c.
	String (unsigned char c)
	String (int x)
	Construct a base-10 string representation of x.
	String (unsigned x)
	String (long x)
	String (unsigned long x)
	String (int64_t x)
	String (uint64_t x)
	String (double x)
	Construct a base-10 string representation of x.
	~String ()
	Destroy a String, freeing memory if necessary.
int	length () const
	Return the string's length.
const char *	data () const
	Return a pointer to the string's data.
const_iterator	begin () const
	Return an iterator for the first character in the string.
const_iterator	end () const
	Return an iterator for the end of the string.
	operator unspecified_bool_type () const
	Return true iff the string is nonempty.
bool	operator! () const
	Return true iff the string is empty.
char	operator[] (int i) const
	Return the i th character in the string.
char	at (int i) const
	Return the i th character in the string.
char	front () const
	Return the first character in the string.
char	back () const
	Return the last character in the string.
const char *	c_str () const
	Null-terminate the string.
uint32_t	hashcode () const
	Returns a 32-bit hash function of this string's characters.
bool	equals (const char *s, int len) const
	Return true iff this string is equal to the data in s.
int	compare (const String &x) const
	Compare this string with string x.
int	compare (const char *s, int len) const
	Compare this string with the data in s.
String	substring (const char *begin, const char *end) const
	Return a substring of the current string starting at begin and ending before end.
String	substring (int pos, int len) const
	Return a substring of this string, consisting of the len characters starting at index pos.
String	substring (int pos) const
	Return the suffix of the current string starting at index pos.
int	find_left (char c, int start=0) const
	Search for a character in a string.
int	find_left (const String &x, int start=0) const
	Search for a substring in a string.
int	find_right (char c, int start=0x7FFFFFFF) const
	Search for a character in a string.
bool	starts_with (const String &x) const
	Return true iff this string begins with prefix x.
bool	starts_with (const char *s, int len) const
	Return true iff this string begins with the data in s.
String	lower () const
	Return a lowercased version of this string.
String	upper () const
	Return an uppercased version of this string.
String	printable () const
	Return a "printable" version of this string.
String	trim_space () const
	Return a substring with spaces trimmed from the end.
String	quoted_hex () const
	Return a hex-quoted version of the string.
String &	operator= (const String &x)
	Assign this string to x.
String &	operator= (const char *cstr)
	Assign this string to the C string cstr.
void	append (const char *s, int len)
	Append the first len characters of s to this string.
void	append (const char *begin, const char *end)
	Appends the data from begin to end to the end of this string.
void	append_fill (int c, int len)
	Append len copies of character c to this string.
char *	append_garbage (int len)
	Append len unknown characters to this string.
String &	operator+= (const String &x)
	Append a copy of x to the end of this string.
String &	operator+= (const char *cstr)
	Append a copy of the C string cstr to the end of this string.
String &	operator+= (char c)
	Append the character c to the end of this string.
bool	data_shared () const
	Return true iff the String's data is shared or immutable.
String	compact () const
	Return a compact version of this String.
char *	mutable_data ()
	Ensure the string's data is unshared and return a mutable pointer to it.
char *	mutable_c_str ()
	Null-terminate the string and return a mutable pointer to its data.
bool	out_of_memory () const
	Return true iff this is an out-of-memory string.
Static Public Member Functions
static void	static_initialize ()
	Initialize the String implementation.
static void	static_cleanup ()
	Clean up the String implementation.
static const String &	make_empty ()
	Return a const reference to an empty String.
static String	make_garbage (int len)
	Return a String containing len unknown characters.
static String	make_stable (const char *s, int len=-1)
	Return a String that directly references the first len characters of s.
static String	make_stable (const char *begin, const char *end)
	Return a String that directly references the character data in [begin, end).
static String	make_numeric (int_large_t x, int base=10, bool uppercase=true)
	Create and return a string representation of x.
static String	make_numeric (uint_large_t x, int base=10, bool uppercase=true)
static const String &	empty_string ()
	Return a const reference to an empty String.
static String	garbage_string (int len)
	Return a String containing len unknown characters.
static String	stable_string (const char *s, int len=-1)
	Return a String that directly references the first len characters of s.
static String	stable_string (const char *begin, const char *end)
	Return a String that directly references the character data in [begin, end).
static String	numeric_string (int_large_t x, int base=10, bool uppercase=true)
	Create and return a string representation of x.
static String	numeric_string (uint_large_t x, int base=10, bool uppercase=true)
static uint32_t	hashcode (const char *begin, const char *end)
	Return a 32-bit hash function of the characters in [begin, end).
static uint32_t	hashcode (const unsigned char *begin, const unsigned char *end)
static int	compare (const String &a, const String &b)
	Compare two strings.
static const String &	make_out_of_memory ()
	Return a const reference to an out-of-memory String.
static const char *	out_of_memory_data ()
	Return the data pointer used for out-of-memory strings.
Related Functions
(Note that these are not member functions.)
bool	operator== (const String &a, const String &b)
	Compares two strings for equality.
bool	operator== (const char *a, const String &b)
bool	operator== (const String &a, const char *b)
bool	operator!= (const String &a, const String &b)
	Compare two Strings for inequality.
bool	operator!= (const char *a, const String &b)
bool	operator!= (const String &a, const char *b)
bool	operator< (const String &a, const String &b)
	Compare two Strings.
bool	operator<= (const String &a, const String &b)
	Compare two Strings.
bool	operator> (const String &a, const String &b)
	Compare two Strings.
bool	operator>= (const String &a, const String &b)
	Compare two Strings.
String	operator+ (String a, const String &b)
	Concatenate the operands and return the result.
String	operator+ (String a, const char *b)
String	operator+ (const char *a, const String &b)
String	operator+ (String a, char b)
	Concatenate the operands and return the result.
Classes
class	Initializer
	Initializes the String implementation. More...

---

Constructor & Destructor Documentation

String::String

(

)

[inline]

Construct an empty String (with length 0).

String::String

(

const String &

x

)

[inline]

Construct a copy of the String x.

String::String

(

const char *

cstr

)

[inline]

Construct a String containing the C string cstr.

Parameters:

cstr

a null-terminated C string

Returns:

A String containing the characters of cstr, up to but not including the terminating null character.

If cstr equals String::out_of_memory_data(), returns an out-of-memory string.

String::String	(	const char *	s,
		int	len
	)			[inline]

Construct a String containing the first len characters of string s.

Parameters:

	s	a string
	len	number of characters to take from s. If len < 0, then takes strlen(s) characters.

Returns:

A String containing len characters of s.

If s equals String::out_of_memory_data(), returns an out-of-memory string.

String::String	(	const char *	begin,
		const char *	end
	)			[inline]

Construct a String containing the characters from begin to end.

Parameters:

	begin	first character in string (begin iterator)
	end	pointer one past last character in string (end iterator)

Returns:

A String containing the characters from begin to end.

Returns a null string if begin >= end. If begin equals String::out_of_memory_data(), returns an out-of-memory string.

String::String

(

bool

x

)

[inline, explicit]

Construct a String equal to "true" or "false" depending on the value of x.

String::String

(

char

c

)

[inline, explicit]

Construct a String containing the single character c.

String::String

(

int

x

)

[explicit]

Construct a base-10 string representation of x.

String::String

(

double

x

)

[explicit]

Construct a base-10 string representation of x.

Note:

This function is only available at user level.

String::~String

(

)

[inline]

Destroy a String, freeing memory if necessary.

---

Member Function Documentation

void String::static_initialize

(

)

[static]

Initialize the String implementation.

Deprecated:

Initializing or cleaning up the String implementation is no longer necessary.

In previous versions, this function needed to be called before any String functionality was used. It currently does nothing.

void String::static_cleanup

(

)

[static]

Clean up the String implementation.

Deprecated:

Initializing or cleaning up the String implementation is no longer necessary.

In previous versions, this function was called to release memory allocated by the String implementation. It currently does nothing.

static const String& String::make_empty

(

)

[inline, static]

Return a const reference to an empty String.

May be quicker than String::String().

String String::make_garbage

(

int

len

)

[static]

Return a String containing len unknown characters.

String String::make_stable	(	const char *	s,
		int	len = -1
	)			[static]

Return a String that directly references the first len characters of s.

This function is suitable for static constant strings whose data is known to stay around forever, such as C string constants. If len < 0, treats s as a null-terminated C string.

Warning:

The String implementation may access s[len], which should remain constant even though it's not part of the String.

static String String::make_stable	(	const char *	begin,
		const char *	end
	)			[inline, static]

Return a String that directly references the character data in [begin, end).

Parameters:

	begin	pointer to the first character in the character data
	end	pointer one beyond the last character in the character data (but see the warning)

This function is suitable for static constant strings whose data is known to stay around forever, such as C string constants. Returns an empty string if begin >= end.

Warning:

The String implementation may access *end, which should remain constant even though it's not part of the String.

String String::make_numeric	(	int_large_t	x,
		int	base = 10,
		bool	uppercase = true
	)			[static]

Create and return a string representation of x.

Parameters:

	x	number
	base	base; must be 8, 10, or 16, defaults to 10
	uppercase	if true, then use uppercase letters in base 16

const String & String::empty_string

(

)

[inline, static]

Return a const reference to an empty String.

Deprecated:

Use make_empty() instead.

String String::garbage_string

(

int

len

)

[inline, static]

Return a String containing len unknown characters.

Deprecated:

Use make_garbage() instead.

String String::stable_string	(	const char *	s,
		int	len = -1
	)			[inline, static]

Return a String that directly references the first len characters of s.

Deprecated:

Use make_stable() instead.

String String::stable_string	(	const char *	begin,
		const char *	end
	)			[inline, static]

Return a String that directly references the character data in [begin, end).

Deprecated:

Use make_stable() instead.

String String::numeric_string	(	int_large_t	x,
		int	base = 10,
		bool	uppercase = true
	)			[inline, static]

Create and return a string representation of x.

Deprecated:

Use make_numeric() instead.

int String::length

(

)

const [inline]

Return the string's length.

const char* String::data

(

)

const [inline]

Return a pointer to the string's data.

Only the first length() characters are valid, and the string data might not be null-terminated.

const_iterator String::begin

(

)

const [inline]

Return an iterator for the first character in the string.

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

See also:

String::data

const_iterator String::end

(

)

const [inline]

Return an iterator for the end of the string.

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

String::operator unspecified_bool_type

(

)

const [inline]

Return true iff the string is nonempty.

bool String::operator!

(

)

const [inline]

Return true iff the string is empty.

char String::operator[]

(

int

i

)

const [inline]

Return the i th character in the string.

Does not check bounds.

See also:

String::at

char String::at

(

int

i

)

const [inline]

Return the i th character in the string.

Checks bounds: an assertion will fail if i is less than 0 or not less than length().

See also:

String::operator[]

char String::front

(

)

const [inline]

Return the first character in the string.

Does not check bounds. Same as (*this)[0].

char String::back

(

)

const [inline]

Return the last character in the string.

Does not check bounds. Same as (*this)[length() - 1].

const char* String::c_str

(

)

const [inline]

Null-terminate the string.

The terminating null character isn't considered part of the string, so this->length() doesn't change. Returns a corresponding C string pointer. The returned pointer is semi-temporary; it will persist until the string is destroyed or appended to.

uint32_t String::hashcode	(	const char *	begin,
		const char *	end
	)			[static]

Return a 32-bit hash function of the characters in [begin, end).

Uses Paul Hsieh's "SuperFastHash" algorithm, described at http://www.azillionmonkeys.com/qed/hash.html This hash function uses all characters in the string.

Invariant:

If end1 - begin1 == end2 - begin2 and memcmp(begin1, begin2, end1 - begin1) == 0, then hashcode(begin1, end1) == hashcode(begin2, end2).

uint32_t String::hashcode

(

)

const [inline]

Returns a 32-bit hash function of this string's characters.

Equivalent to String::hashcode(begin(), end()). Uses Paul Hsieh's "SuperFastHash."

Invariant:

If s1 == s2, then s1.hashcode() == s2.hashcode().

bool String::equals	(	const char *	s,
		int	len
	)			const

Return true iff this string is equal to the data in s.

Parameters:

	s	string data to compare to
	len	length of s

Same as String::compare(*this, String(s, len)) == 0. If len < 0, then treats s as a null-terminated C string.

See also:

String::compare(const String &a, const String &b)

static int String::compare	(	const String &	a,
		const String &	b
	)			[inline, static]

Compare two strings.

Parameters:

	a	first string to compare
	b	second string to compare

Returns 0 if a == b, negative if a < b in lexicographic order, and positive if a > b in lexicographic order. The lexicographic order treats all characters as unsigned.

int String::compare

(

const String &

x

)

const [inline]

Compare this string with string x.

Same as String::compare(*this, x).

See also:

String::compare(const String &a, const String &b)

int String::compare	(	const char *	s,
		int	len
	)			const

Compare this string with the data in s.

Parameters:

	s	string data to compare to
	len	length of s

Same as String::compare(*this, String(s, len)). If len < 0, then treats s as a null-terminated C string.

See also:

String::compare(const String &a, const String &b)

String String::substring	(	const char *	begin,
		const char *	end
	)			const [inline]

Return a substring of the current string starting at begin and ending before end.

Parameters:

	begin	pointer to the first substring character
	end	pointer one beyond the last substring character

Returns an empty string if begin >= end. Also returns an empty string if begin or end is out of range (i.e., either less than this->begin() or greater than this->end()), but this should be considered a programming error; a future version may generate a warning for this case.

String String::substring	(	int	pos,
		int	len
	)			const

Return a substring of this string, consisting of the len characters starting at index pos.

Parameters:

	pos	substring's first position relative to the string
	len	length of substring

If pos is negative, starts that far from the end of the string. If len is negative, leaves that many characters off the end of the string. If pos and len specify a substring that is partly outside the string, only the part within the string is returned. If the substring is beyond either end of the string, returns an empty string (but this should be considered a programming error; a future version may generate a warning for this case).

Note:

String::substring() is intended to behave like Perl's substr().

String String::substring

(

int

pos

)

const [inline]

Return the suffix of the current string starting at index pos.

If pos is negative, starts that far from the end of the string. If pos is so negative that the suffix starts outside the string, then the entire string is returned. If the substring is beyond the end of the string (pos > length()), returns an empty string (but this should be considered a programming error; a future version may generate a warning for this case).

Note:

String::substring() is intended to behave like Perl's substr().

int String::find_left	(	char	c,
		int	start = 0
	)			const

Search for a character in a string.

Parameters:

	c	character to search for
	start	initial search position

Return the index of the leftmost occurence of c, starting at index start and working up to the end of the string. Returns -1 if c is not found.

int String::find_left	(	const String &	x,
		int	start = 0
	)			const

Search for a substring in a string.

Parameters:

	x	substring to search for
	start	initial search position

Return the index of the leftmost occurence of the substring str, starting at index start and working up to the end of the string. Returns -1 if str is not found.

int String::find_right	(	char	c,
		int	start = 0x7FFFFFFF
	)			const

Search for a character in a string.

Parameters:

	c	character to search for
	start	initial search position

Return the index of the rightmost occurence of the character c, starting at index start and working back to the beginning of the string. Returns -1 if c is not found. start may start beyond the end of the string.

bool String::starts_with

(

const String &

x

)

const [inline]

Return true iff this string begins with prefix x.

Same as String::starts_with(x.data(), x.length()).

bool String::starts_with	(	const char *	s,
		int	len
	)			const

Return true iff this string begins with the data in s.

Parameters:

	s	string data to compare to
	len	length of s

If len < 0, then treats s as a null-terminated C string.

See also:

String::compare(const String &a, const String &b)

String String::lower

(

)

const

Return a lowercased version of this string.

Translates the ASCII characters 'A' through 'Z' into their lowercase equivalents.

String String::upper

(

)

const

Return an uppercased version of this string.

Translates the ASCII characters 'a' through 'z' into their uppercase equivalents.

String String::printable

(

)

const

Return a "printable" version of this string.

Translates control characters 0-31 into "control" sequences, such as "^@" for the null character, and characters 127-255 into octal escape sequences, such as "\377" for 255.

String String::trim_space

(

)

const

Return a substring with spaces trimmed from the end.

String String::quoted_hex

(

)

const

Return a hex-quoted version of the string.

For example, the string "Abcd" would convert to "\<41626364>".

String& String::operator=

(

const String &

x

)

[inline]

Assign this string to x.

String& String::operator=

(

const char *

cstr

)

[inline]

Assign this string to the C string cstr.

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

Append the first len characters of s to this string.

Parameters:

	s	data to append
	len	length of data

If len < 0, treats s as a null-terminated C string.

void String::append	(	const char *	begin,
		const char *	end
	)			[inline]

Appends the data from begin to end to the end of this string.

Does nothing if begin >= end.

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

Append len copies of character c to this string.

char * String::append_garbage

(

int

len

)

Append len unknown characters to this string.

Returns:

Modifiable pointer to the appended characters.

The caller may safely modify the returned memory. Null is returned if the string becomes out-of-memory.

String& String::operator+=

(

const String &

x

)

[inline]

Append a copy of x to the end of this string.

Returns the result.

String& String::operator+=

(

const char *

cstr

)

[inline]

Append a copy of the C string cstr to the end of this string.

Returns the result.

String& String::operator+=

(

char

c

)

[inline]

Append the character c to the end of this string.

Returns the result.

bool String::data_shared

(

)

const [inline]

Return true iff the String's data is shared or immutable.

String String::compact

(

)

const [inline]

Return a compact version of this String.

The compact version shares no more than 256 bytes of data with any other non-stable String.

char * String::mutable_data

(

)

Ensure the string's data is unshared and return a mutable pointer to it.

char * String::mutable_c_str

(

)

Null-terminate the string and return a mutable pointer to its data.

See also:

String::c_str

bool String::out_of_memory

(

)

const [inline]

Return true iff this is an out-of-memory string.

static const String& String::make_out_of_memory

(

)

[inline, static]

Return a const reference to an out-of-memory String.

static const char* String::out_of_memory_data

(

)

[inline, static]

Return the data pointer used for out-of-memory strings.

The returned value may be dereferenced; it points to a null character.

---

Friends And Related Function Documentation

bool operator==	(	const String &	a,
		const String &	b
	)			[related]

Compares two strings for equality.

Returns true iff the two operands have the same lengths and the same characters in the same order. At most one of the operands can be a null-terminated C string.

See also:

String::compare

bool operator!=	(	const String &	a,
		const String &	b
	)			[related]

Compare two Strings for inequality.

Returns true iff !(a == b). At most one of the operands can be a null-terminated C string.

bool operator<	(	const String &	a,
		const String &	b
	)			[related]

Compare two Strings.

Returns true iff a < b in lexicographic order.

See also:

String::compare

bool operator<=	(	const String &	a,
		const String &	b
	)			[related]

Compare two Strings.

Returns true iff a <= b in lexicographic order.

See also:

String::compare

bool operator>	(	const String &	a,
		const String &	b
	)			[related]

Compare two Strings.

Returns true iff a > b in lexicographic order.

See also:

String::compare

bool operator>=	(	const String &	a,
		const String &	b
	)			[related]

Compare two Strings.

Returns true iff a >= b in lexicographic order.

See also:

String::compare

String operator+	(	String	a,
		const String &	b
	)			[related]

Concatenate the operands and return the result.

At most one of the two operands can be a null-terminated C string.

String operator+	(	String	a,
		char	b
	)			[related]

Concatenate the operands and return the result.

The second operand is a single character.

---

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

• include/click/string.hh
• lib/string.cc

---