lionkor / string

A feature-rich modern C++ string class

String v2.0

Full rewrite of this simple modern String class / library. Incompatible with v1.0 which can be found here.

The v2.0 is not fully done yet

Unit tests are in test/.

Documentation

Full documentation can be found here: Full documentation.

How to use

There are 2 ways to use this library:

1 Compile with your project

1. clone this repository (recursively).
2. add String/include to your include directories.
3. include String.h and add String/src/String.cpp to your source files (for an example look at CMakeLists.txt).
4. compile with at least -std=c++17.

2 Compile as library, link (linux/unix)

1. clone this repository (recursively).

2. go into the cloned repository directory.

3. run cmake && make String. This will create libString.a.

4. add String/include to your include directories

5. link against libString.a.

   Example with gcc, assuming String was cloned into the same directory that main.cpp is in and libString.a has been built:

   g++ main.cpp -o myprogram -lString -L./String -I./String/include

Major features

• String::format - Described below.
• String::split - Splits the String into parts, using a char or String as delimiter.
• String::replace - Replaces all instances of a char or String with another char or String.
• String::startswith - Tests whether the String starts with another substring.
• String::endswith - Tests whether the String ends with another substring.
• String::insert and String::erase - Inserts or erases chars or Strings into or from the String.

For the full list of functions and features, check out the documentation.

String::format

A static method allowing for simple and fast formatting. Allows any type T with an overload to ostream& operator(ostream&, T) to be formatted into the String correctly. Because of this, it also supports all primitive types.

Examples:

const char* name = "Dave";
const int age = 35;
String test = String::format("Name: ", name, ", Age: ", age);
// -> "Name: Dave, City: New York, Age: 35"

If your type correctly overloads ostream& operator(ostream&, T), you can pass your type to String::format.

You can pass a String::Format instance to set formatting options similar to std::ios::fmtflags. This allows setting precision, base, width, fill, etc.

Example:

String::Format fmt;
fmt.precision    = 3;
fmt.width        = 10;
fmt.alignment    = String::Format::Align::Right;
String my_string = String::format(".", fmt, 3.53214, " |", fmt, 5.2436, " |");
std::cout << my_string << std::endl;

will output:

.        3.53 |      5.24 |

FAQ

How do you run the tests?

After cloning the repo, head into the cloned String directory and run cmake and then make StringTest. You can then execute ./StringTest.

Is std::string not good?

std::string is very good. Still, I always thought its interface was very inconsistent, using iterators here and indices there, and following very few std library conventions. String is supposed to allow for more Python- or C#-like string interactions, making it feel more like a primitive type than a complicated container, yet also supporting it being treated just like a normal std::vector.

TL;DR: I just want a string that gives me an iterator when I call String::find and has intuitive methods like .replace and .split.

Is it faster / slower than std::string?

Generally, it's probably slower, as is to be expected at this point in development. Construction is just as fast as std::string, for any string long enough so that SSO doesn't kick in for std::string. This is not a performance library, it's a convenience library. If you think std::vector is fast enough, then this library is probably fast enough.

How do you convert to std::string or char*?

Since String is not null-terminated, conversion is rather slow. Options for conversion are, from fastest to slowest:

1. Append '\0', access String::data(), do stuff, then String::erase the '\0'. This is super fast, won't copy any data, and you can just use it like a regular const char*. This is only useful if the String is only used by one thread and is not const. Attention: This will cause huge troubles if you attempt to use the String after adding a '\0' without erasing it again, as the size will have increased by one (since we treat '\0' as a normal character). This is the fastest, but also the most error-prone way. Not recommended.

2. Use String::to_std_string. This copies the data into a std::string, which might be faster than method nr. 3, as this might use SSO. The returned std::string is a copy.

3. Use String::to_c_string. This allocates a buffer with new[], wraps it in a std::unique_ptr, copies the chars into it and returns that std::unique_ptr. You can then access the char* with .get(). This is probably the slowest way, but it will give you back a self-memory-managing buffer, so it's pretty neat. I was thinking about a raw pointer return, but that just wants to leak memory.

For more information on those functions read the documentation.

Why std::vector?

I don't like std::string, I do like std::vector.

Where did open issues go?

Closed, since the code that was responsible for them was nuked.

string's Issues

join

Thanks for your nice lib
I cant find join for vectors of strings or someting like that.
How can i join strings in an easy way?

Memory leak caused by to_c_string()

String::to_c_string() uses std::unique_ptr<char> instead of std::unique_ptr<char[]> causing the underlying buffer to be freed with delete instead of delete[].

Allocating many small strings causes crash

Too many SSO'd strings cause weird crashes at the moment.

For now the workaround is to set the MAX_ALLOC to something like 1 to basically disable SSO altogether.

It's being worked on.