• defined in header "String/String.h"

The class cave::String provides support for strings in the engine. cave::String is used to store characters dynamically as std::string.

• Element access

• Capacity

• Operations

• Search

• Constants

• Non-member functions
  • Input / output

String();						// (1)
String(const char* s);			// (2)
String(const String& other);	// (3)

Constructs new string from a variety of data sources

1. Default constructor. Constructs empty string (zero size and capacity). If no allocator is supplied, allocator is obtained from the Core Memory Pool.
2. Constructs the string with the contents initialized with a copy of the null-terminated character string pointer to by s. The length of the string is determined by the first null character.
3. Copy constructor. Constructs the string with a copy of the contents of other.

1. Constant
2. Linear in length of s
3. Linear in size of other

#include "String/String.h"

int main()
{
	{
		cave::String string;
		assert(string.GetLength() == 0ul);
	}

	{
		cave::String string("C-style\0string");
		std::cout << string << '\n';	// "C-style"
	}

	{
		cave::String const other("Hello");
		cave::String string(other);
		std::cout << string << '\n';	// "Hello"
	}

	return 0;
}

Output:

C-style
Hello

String& operator=(const String& str);	// (1)
String& operator=(const char* s);		// (2)

Replaces the contents of the string

1. Replaces the contents with a copy of str
2. Replaces the contents with those of null-terminated character string pointed to by s

*this

1. Linear in size of str
2. Linear in size of s

#include "String/String.h"

int main()
{
	cave::String str1;
	cave::String str2("alpha");

	// (1) operator=(const cave::String&);
	str1 = str2;
	std::cout << str1 << ' '	// "alpha"
			  << str2 << '\n';	// "alpha"

	// (2) operator=(const char*);
	str1 = "beta";
	std::cout << str1 << '\n';	// "beta"

	return 0;
}

Possible output:

alpha alpha
beta

const char* GetCString() const;

Returns a pointer to a null-terminated character array with data equivalend to those stored in the string. Writing to the character array access through GetCString() is undefined behavior.

(none)

Pointer to the underlying character storage.

Constant

The pointer obtained from GetCString() may only be treated as a pointer to a null-terminated character string if the string object does not contain other null characters.

#include <cstring>

#include "String/String.h"

int main()
{
	cave::String const s("Hello");
	assert(s.GetLength() == std::strlen(s.GetCString()));
	assert('\0' == *(s.GetCString() + s.GetLength()));

	return 0;
}

size_t GetLength() const;

• Returns the number of characters in the string

(none)

The number of characters in the string

Constant

The elements are bytes (objets of type char), which are not the same as characters if a multibye encoding such as UTF-8 is used.

• Samples/Main.cpp

#include "Debug/Log.h"

int main()
{
    cave::String string("Hello, World!");
	assert(string.GetLength() == 13);

    return 0;
}

bool RemoveAt(size_t index);

Removes specified characters from the string. Removes the character at index

true if removal was successful, false if otherwise.

#include "String/String.h"

int main()
{
	cave::String s = "This is an example";
	std::cout << s << '\n';

	s.RemoveAt(0);	// Remove 'T'
	std::cout << s << '\n';

	return 0;
}

Output:

This is an example
his is an example

void Append(const char* s);

Appends additional characters to the string. Appends the null-terminated character string pointed to by s. The length of the string is determined by the first null character using strlen(s).

*this

Linear in size of s

#include "String/String.h

int main()
{
	cave::String str = "string";
	const char* cPtr = "C-string";
	const char cArr[] = "Two and one";

	cave::String output;

	// Append a whole C-string
	output.append(cPtr);
	std::cout << output << '\n';

	return 0;
}

Output:

C-string

String& operator+=(const String& str);	// (1)
String& operator+=(const char* s);		// (2)

Appends additional characters to the string.

1. Appends string str
2. Appends the null-terminated character string pointed to by s

*this

1. Linear in size of str
2. Linear in size of s

#include "String/String.h"

int main()
{
	cave::String str;
	std::cout << str << '\n';	// empty string

	str += "This";
   std::cout << str << '\n';
 
   str += cave::String(" is a");
   std::cout << str << '\n';
 
   str += {' ','s','t','r','i','n','g','.'};
   std::cout << str << '\n';
}

Output:

This
This is a
This is a string.

String operator+(const String& rhs) const;

Returns a string containing characters from itself followed by the characters from rhs.

A string containing the characters from itself followed by the characters from rhs.

#include <iostream>

#include "String/String.h"
 
int main()
{
    cave::String s1 = "Hello";
    cave::String s2 = "world";
    std::cout << s1 + ' ' + s2 + "!\n";
}

Output:

Hello world!

bool operator==(const String& rhs) const;

Compares the contents the string with another string.

• Two strings are equal if both the size of itself and rhs are equal and each character of itself has equivalent character in rhs at the same position.

Compares itself with another String objects

true if the corresponding comparison holds, false otherwise.

Linear in the size of the strings.

int32_t IndexOf(const char* s);

Finds the first substring equal to the given character sequence.

Finds the first substring equal to the character string pointed to by s. The length of the string is determined by the first null character using strlen(s)

Position of the first character of the found substring or NPOS if no such substring is found.

#include <iostream>

#include "String/String.h"

void Print(size_t n, cave::String const &s)
{
    if (n == -1)
	{
        std::cout << "not found\n";
    }
	else
	{
        std::cout << "found" << &s.GetCString()[n] << '\n';
    }
}
 
int main()
{
    size_t n;
    cave::String const s = "This is a string";
 
    // search from beginning of string
    n = s.IndexOf("is");
    Print(n, s);
}

Output:

found: is is a string

int32_t LastIndexOf(const char* s);

Finds the last substring equal to the given character sequence.

Finds the last substring equal to the character string pointed to by s. The length of the string is determined by the first null character using strlen(s).

Position of the first character of the found substring or NPOS if no such substring is found. Note that this is an offset from the string of the string, not the end.

If searching for an empty string(str.GetLength() is zero), NPOS is always returned.

#include <iostream>

#include "String/String.h"

void Print(size_t n, cave::String const &s)
{
    if (n == -1)
	{
        std::cout << "not found\n";
    }
	else
	{
        std::cout << "found: \"" << &s.GetCString()[n] << "\" at " << n << '\n';
    }
}
 
int main()
{
    cave::size_t n;
    cave::String const s = "This is a string";
 
    // search backwards from end of string
    n = s.LastIndexOf("is");
    Print(n, s);
}

Output:

found: "is a string" at 5

static constexpr size_t NPOS = -1ul;

This is a special value equal to the maximum value representable by the type size_t. The exact meaning depends on context, but it is generally used either as end of string indicator by functions that expects a string index or as the error indicator by the functions that return a string index.

Although the definition uses -1, size_t is an unsigned integer type, and the value of NPOS is the largest positive value it can hold, due to signed-to-unsigned implicit conversion. This is a portable way to specify the largest value of any unsigned type.

#include <iostream>

#include "String/String.h"
 
int main()
{
    // string search functions return npos if nothing is found
    cave::String s = "test";
    if(s.IndexOf("a") == cave::String::NPOS)
	{
        std::cout << "no \"a\" in \"test\"\n";
	}
}

Output:

no "a" in "test"

std::ostream& operator<<(std::ostream& os, const cave::String& str);

Behaves as a FormattedOutputFunction. After constructing and checking the sentry object, determines the output format padding as follows:

1. If str.GetLength() is not less than os.width(), uses the range [0, str.GetLength()) as-is
2. Otherwise, if (os.flags() & ios_base::adjustfield) == ios_base::left, places os.width() - str.GetLength() copies of the os.fill() character after the character sequence.
3. Otherwise, places os.width() - str.size() copies of the os.fill() character before the character sequence.

Then stored each character from the resulting sequence (the contents of str plus padding) to the output stream os as if by calling os.rdbuf()->sputn(seq, n), where n=std::max(os.width(), str.GetLength())

Finally, calls os.width(0) to cancel the effects of std::setw, if any.

os

#include <iostream>
#include <sstream>

#include "String/String.h"
 
int main()
{
    cave::String greeting = "Hello, whirled!";

    std::cout << greeting << '\n';
}

Output:

Hello, whirled!