String Class Reference

The String class represents a not-null-terminated string. More...

#include <String.h>

Classes
struct	Format
	Specifies the formatting of a String::format operation. More...

Public Types
using	Iterator = std::vector< char >::iterator
	Iterators used to iterate over the String. More...
using	ConstIterator = std::vector< char >::const_iterator
using	ReverseIterator = std::vector< char >::reverse_iterator
using	ConstReverseIterator = std::vector< char >::const_reverse_iterator

Public Member Functions
	String ()
	New empty string, equivalent to "". More...
	String (std::nullptr_t)
	New string from nullptr -> empty string. More...
	String (char c)
	New string with only the char c. More...
	String (const char *cstr)
	New string with cstr as content. More...
	String (ConstIterator from, ConstIterator to)
	New string from another string's iterators. More...
	String (const String &)=default
	String (String &&)=default
String &	operator= (const String &)=default
	operator std::string () const
	Implicit conversion to std::string allowed. More...
Iterator	begin ()
	Begin iterator. Points to the first char in the string. More...
ConstIterator	begin () const
	Const begin iterator. Points to the first char in the string. More...
Iterator	end ()
	End iterator. points at the position past the end of the string. More...
ConstIterator	end () const
	Const end iterator. points at the position past the end of the string. More...
char &	at (std::size_t i)
	Accesses the character at position i in the string. More...
char	at (std::size_t i) const
	Accesses the character at position i in the string. More...
bool	empty () const noexcept
	True if the string is empty, i.e. has length 0. More...
std::size_t	size () const noexcept
	Size or length of the string. More...
std::size_t	length () const noexcept
	Length or size of the string. More...
std::unique_ptr< char[]>	to_c_string () const
	A unique_ptr managed char[] containing a copy of the data of the string, guaranteed to be null-terminated. More...
std::string	to_std_string () const
	A copy of this string represented as a std::string. More...
void	clear () noexcept
	Clears the contents of the string, resulting string will be the empty string. More...
void	insert (ConstIterator iter, char c)
	Inserts a char before the position pointed to by the iterator. May invalidate iterators. More...
void	insert (ConstIterator iter, const String &s)
	Inserts the string before the position pointed to by the iterator. May invalidate iterators. More...
void	insert (ConstIterator iter, ConstIterator begin, ConstIterator end)
	Inserts the part of the string specified by the begin and end iterators before the position pointed to by the "iter" iterator. May invalidate iterators. More...
void	erase (ConstIterator iter)
	Removes the element pointed to by the iterator. Invalidates iterators. More...
void	erase (ConstIterator from, ConstIterator to)
	Removes elements between from and to. Invalidates iterators. More...
void	erase (ConstIterator iter, std::size_t n)
	Removes n elements starting at the iterator position. Invalidates iterators. More...
String	substring (ConstIterator from, ConstIterator to) const
	A copy of the chars between from and to, as a new string. More...
String	substring (ConstIterator start, std::size_t n) const
	A copy of the first n chars from start, as a new string. More...
Iterator	find (char c)
	Finds the first occurance of char c in the string. Returns end() if nothing was found. More...
ConstIterator	find (char c) const
	Finds the first occurance of char c in the string. Returns end() if nothing was found. More...
Iterator	find (char c, Iterator start)
	Finds the first occurance of char c in the string after start. Returns end() if nothing was found. More...
ConstIterator	find (char c, ConstIterator start) const
	Finds the first occurance of char c in the string after start. Returns end() if nothing was found. More...
Iterator	find (const String &)
	Finds the first occurance of the string inside this string. More...
ConstIterator	find (const String &) const
	Finds the first occurance of the string inside this string. More...
Iterator	find (const String &, Iterator start)
	Finds the first occurance of the string after start inside this string. More...
ConstIterator	find (const String &, ConstIterator start) const
	Finds the first occurance of the string after start inside this string. More...
bool	contains (const String &) const
	Whether this string contains the substring. More...
bool	startswith (const String &) const
	Whether this string starts with the substring. More...
bool	endswith (const String &) const
	Whether this string ends with the substring. More...
bool	equals (const String &) const
	Does a case-sensitive comparison between the chars of both strings. Same as String::operator==(const String&). More...
bool	operator== (const String &) const
	Does a case-sensitive comparison between the chars of both strings. More...
bool	operator!= (const String &) const
	Does a case-sensitive comparison between the chars of both strings. More...
String &	operator+= (const String &)
	Appends the given string to this string. More...
String	operator+ (const String &) const
	Creates a new string by appending a string to this string. More...
void	replace (char to_replace, char replace_with)
	Replaces all instances of to_replace with replace_with in the string. More...
void	replace (const String &to_replace, const String &replace_with)
	Replaces all instances of to_replace with replace_with in the string. More...
void	replace (const String &to_replace, const String &replace_with, std::size_t n)
	Replaces n instances of to_replace with replace_with in the string. More...
std::vector< String >	split (char delim, std::size_t expected_splits=2) const
	Splits the String into substrings delimited by delim. More...
std::vector< String >	split (const String &delim, std::size_t expected_splits=2) const
	Splits the String into substrings delimited by the String delim. More...
void	reserve (std::size_t size)
	Grows the capacity to fit size many characters. Does not change the size of the string. More...
std::size_t	capacity () const
	Capacity of the string's underlying allocated memory. More...
void	shrink_to_fit () noexcept
	Shrinks capacity to be equal to size, thus freeing memory in some cases. Not guaranteed, as it's implementation dependent. More...
char *	data () noexcept
	Raw pointer to the data of this String. Keep in mind that this is NOT null-terminated. More...
const char *	data () const noexcept
	Raw const pointer to the data of this String. Keep in mind that this is NOT null-terminated. More...

Static Public Member Functions
template<class... Args>
static String	format (Args &&... things)
	Constructs a string from non-string arguments. More...

Friends
std::ostream &	operator<< (std::ostream &, const String &)
std::istream &	operator>> (std::istream &is, String &s)

Detailed Description

The String class represents a not-null-terminated string.

Author

lionkor (Lion Kortlepel)

A String class without many of the inconsistencies that std::string brings, and many helper functions, making it more alike Python or .NET strings.

Implemented as a wrapper around a std::vector<char> for safety, simplicity and speed. This means that any <algorithm> calls should work as expected.

Attention

String is not null-terminated. If a null-terminated string is needed, it's very simple to convert to a std::string or c-string via String::to_c_string and String::to_std_string.

Member Typedef Documentation

ConstIterator

using String::ConstIterator = std::vector<char>::const_iterator

ConstReverseIterator

using String::ConstReverseIterator = std::vector<char>::const_reverse_iterator

Iterator

using String::Iterator = std::vector<char>::iterator

Iterators used to iterate over the String.

Attention

Do not rely on these iterators being aliases for std::vector iterators. This might change at any point. Treat them as their own types.

ReverseIterator

using String::ReverseIterator = std::vector<char>::reverse_iterator

Constructor & Destructor Documentation

String() [1/7]

String::String

(

)

New empty string, equivalent to "".

String() [2/7]

String::String

(

std::nullptr_t

)

New string from nullptr -> empty string.

String() [3/7]

String::String ( char  c )

explicit

New string with only the char c.

String() [4/7]

String::String

(

const char *

cstr

)

New string with cstr as content.

String() [5/7]

String::String	(	String::ConstIterator	from,
		String::ConstIterator	to
	)

New string from another string's iterators.

String() [6/7]

String::String ( const String &  )

default

String() [7/7]

String::String ( String &&  )

default

Member Function Documentation

at() [1/2]

char & String::at

(

std::size_t

i

)

Accesses the character at position i in the string.

Exceptions

std::out_of_range

if i is an invalid index

at() [2/2]

char String::at

(

std::size_t

i

)

const

Accesses the character at position i in the string.

Exceptions

std::out_of_range

if i is an invalid index

begin() [1/2]

String::Iterator String::begin

(

)

Begin iterator. Points to the first char in the string.

begin() [2/2]

String::ConstIterator String::begin

(

)

const

Const begin iterator. Points to the first char in the string.

capacity()

std::size_t String::capacity

(

)

const

Capacity of the string's underlying allocated memory.

The String's size may grow up to this capacity without any reallocation taking place.

clear()

void String::clear ( )

noexcept

Clears the contents of the string, resulting string will be the empty string.

contains()

bool String::contains

(

const String &

str

)

const

Whether this string contains the substring.

References end(), find(), and size().

data() [1/2]

const char * String::data ( ) const

noexcept

Raw const pointer to the data of this String. Keep in mind that this is NOT null-terminated.

data() [2/2]

char * String::data ( )

noexcept

Raw pointer to the data of this String. Keep in mind that this is NOT null-terminated.

empty()

bool String::empty ( ) const

noexcept

True if the string is empty, i.e. has length 0.

end() [1/2]

String::Iterator String::end

(

)

End iterator. points at the position past the end of the string.

end() [2/2]

String::ConstIterator String::end

(

)

const

Const end iterator. points at the position past the end of the string.

endswith()

bool String::endswith

(

const String &

str

)

const

Whether this string ends with the substring.

References begin(), end(), and size().

equals()

bool String::equals

(

const String &

str

)

const

Does a case-sensitive comparison between the chars of both strings. Same as String::operator==(const String&).

References begin(), end(), and size().

erase() [1/3]

void String::erase	(	String::ConstIterator	from,
		String::ConstIterator	to
	)

Removes elements between from and to. Invalidates iterators.

References begin(), empty(), and end().

erase() [2/3]

void String::erase

(

String::ConstIterator

iter

)

Removes the element pointed to by the iterator. Invalidates iterators.

References begin(), empty(), and end().

erase() [3/3]

void String::erase	(	String::ConstIterator	iter,
		std::size_t	n
	)

Removes n elements starting at the iterator position. Invalidates iterators.

References erase().

find() [1/8]

String::Iterator String::find

(

char

c

)

Finds the first occurance of char c in the string. Returns end() if nothing was found.

• c character to find, case-sensitive.

  Returns

  String::Iterator pointing to the found character, or end() if nothing was found.

find() [2/8]

String::ConstIterator String::find

(

char

c

)

const

Finds the first occurance of char c in the string. Returns end() if nothing was found.

• c character to find, case-sensitive.

  Returns

  String::ConstIterator pointing to the found character, or end() if nothing was found.

find() [3/8]

String::ConstIterator String::find	(	char	c,
		String::ConstIterator	start
	)		const

Finds the first occurance of char c in the string after start. Returns end() if nothing was found.

• c character to find, case-sensitive.
• start position from which to search from.

  Returns

  String::ConstIterator pointing to the found character, or end() if nothing was found.

find() [4/8]

String::Iterator String::find	(	char	c,
		String::Iterator	start
	)

Finds the first occurance of char c in the string after start. Returns end() if nothing was found.

• c character to find, case-sensitive.
• start position from which to search from.

  Returns

  String::Iterator pointing to the found character, or end() if nothing was found.

find() [5/8]

String::Iterator String::find

(

const String &

str

)

Finds the first occurance of the string inside this string.

Returns

String::Iterator pointing to the beginning of the found substring, or end() if nothing was found

References begin(), and end().

find() [6/8]

String::ConstIterator String::find

(

const String &

str

)

const

Finds the first occurance of the string inside this string.

Returns

String::ConstIterator pointing to the beginning of the found substring, or end() if nothing was found

References begin(), and end().

find() [7/8]

String::ConstIterator String::find	(	const String &	str,
		String::ConstIterator	start
	)		const

Finds the first occurance of the string after start inside this string.

Returns

String::ConstIterator pointing to the beginning of the found substring, or end() if nothing was found

References begin(), and end().

find() [8/8]

String::Iterator String::find	(	const String &	str,
		Iterator	start
	)

Finds the first occurance of the string after start inside this string.

Returns

String::Iterator pointing to the beginning of the found substring, or end() if nothing was found

References begin(), and end().

format()

template<class... Args>

static String String::format ( Args &&...  things )

inlinestatic

Constructs a string from non-string arguments.

Accepts and correctly formats any type T for which an overload for

std::ostream& operator<<(std::ostream&, T)

exists. Arguments will be appended to the String in order. Pass String::Format to specify floating point precision, width, fill chars, base, etc.

insert() [1/3]

void String::insert	(	String::ConstIterator	iter,
		char	c
	)

Inserts a char before the position pointed to by the iterator. May invalidate iterators.

References end().

insert() [2/3]

void String::insert	(	String::ConstIterator	iter,
		const String &	s
	)

Inserts the string before the position pointed to by the iterator. May invalidate iterators.

References begin(), and end().

insert() [3/3]

void String::insert	(	String::ConstIterator	iter,
		String::ConstIterator	begin,
		String::ConstIterator	end
	)

Inserts the part of the string specified by the begin and end iterators before the position pointed to by the "iter" iterator. May invalidate iterators.

References begin(), and end().

length()

std::size_t String::length ( ) const

noexcept

Length or size of the string.

operator std::string()

String::operator std::string

(

)

const

Implicit conversion to std::string allowed.

operator!=()

bool String::operator!=

(

const String &

s

)

const

Does a case-sensitive comparison between the chars of both strings.

References equals().

operator+()

String String::operator+

(

const String &

s

)

const

Creates a new string by appending a string to this string.

References end(), and insert().

operator+=()

String & String::operator+=

(

const String &

s

)

Appends the given string to this string.

References end(), and insert().

operator=()

String& String::operator= ( const String &  )

default

operator==()

bool String::operator==

(

const String &

s

)

const

Does a case-sensitive comparison between the chars of both strings.

References equals().

replace() [1/3]

void String::replace	(	char	to_replace,
		char	replace_with
	)

Replaces all instances of to_replace with replace_with in the string.

replace() [2/3]

void String::replace	(	const String &	to_replace,
		const String &	replace_with
	)

Replaces all instances of to_replace with replace_with in the string.

References begin(), empty(), end(), erase(), find(), insert(), and size().

replace() [3/3]

void String::replace	(	const String &	to_replace,
		const String &	replace_with,
		std::size_t	n
	)

Replaces n instances of to_replace with replace_with in the string.

References begin(), empty(), end(), erase(), find(), insert(), and size().

reserve()

void String::reserve

(

std::size_t

size

)

Grows the capacity to fit size many characters. Does not change the size of the string.

Increases the capacity of the currently allocated memory to be able to hold size many characters before having to reallocate. Calling this before doing a lot of appending up to a known max length can increase performance significantly, as multiple allocations are avoided. Does not impact length.

References size().

shrink_to_fit()

void String::shrink_to_fit ( )

noexcept

Shrinks capacity to be equal to size, thus freeing memory in some cases. Not guaranteed, as it's implementation dependent.

size()

std::size_t String::size ( ) const

noexcept

Size or length of the string.

split() [1/2]

std::vector< String > String::split	(	char	delim,
		std::size_t	expected_splits = 2
	)		const

Splits the String into substrings delimited by delim.

• delim delimiter to be used
• expected_splits how many parts are expected. Setting this to a reasonable amount will speed up the split operation as memory can be reserved beforehand.

References begin(), end(), find(), and String().

split() [2/2]

std::vector< String > String::split	(	const String &	delim,
		std::size_t	expected_splits = 2
	)		const

Splits the String into substrings delimited by the String delim.

• delim delimiter string to be used
• expected_splits how many parts are expected. Setting this to a reasonable amount will speed up the split operation as memory can be reserved beforehand.

References begin(), empty(), end(), find(), size(), and String().

startswith()

bool String::startswith

(

const String &

str

)

const

Whether this string starts with the substring.

References begin(), end(), and size().

substring() [1/2]

String String::substring	(	String::ConstIterator	from,
		String::ConstIterator	to
	)		const

A copy of the chars between from and to, as a new string.

References String().

substring() [2/2]

String String::substring	(	String::ConstIterator	start,
		std::size_t	n
	)		const

A copy of the first n chars from start, as a new string.

References String().

to_c_string()

std::unique_ptr< char[]> String::to_c_string

(

)

const

A unique_ptr managed char[] containing a copy of the data of the string, guaranteed to be null-terminated.

to_std_string()

std::string String::to_std_string

(

)

const

A copy of this string represented as a std::string.

Friends And Related Function Documentation

operator<<

std::ostream& operator<< ( std::ostream &  os, const String &  s  )

friend

operator>>

std::istream& operator>> ( std::istream &  is, String &  s  )

friend

---

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

• include/String.h
• src/String.cpp