Super String

These methods deal with accessing or manipulating ranges of characters. Such as:

• substring - a range of characters that can be copied or assigned to.
• get - copy a range of characters.
• set - change some of a string's characters.
• cut - remove and return a range of characters.
• paste - insert some characters.
• removeRange - delete a range of characters.
• replaceRange - replace a range of characters with some others.
• reverse - reverse the order.
• sort - sort by character value.
• fill - fill a range with some value.
• repeat - fill with a string.

They operate on a range of characters. There are three kinds of ranges:

int beg, int len	where beg is the starting position, len the number of characters.
Pair<int> beglen	with beglen._0 the start and beglen._1 the length. See Supporting Classes
std::vector <Pair<int>> beglen	multiple ranges can be operated on.

A buffer is either:

• a block of memory, ready for some other operation or agent to use.
• an arbitrary region of memory, on which string operations may be performed in place.

What constitutes a buffer operation is a little loose:

• some constraint for being well behaved is violated.
• value semantics are violated.
• primarily concerned with raw bytes.
• getting bytes in or out of the string in an unusual or low-level manner.
• directly accessing a Super String's representation.

A region (also reference) has a representation that points to an internal part of its parent string. The advantages are that no copying need be done to refer to a part of a string and that the parent may be manipulated via this part of itself, perhaps with simplified logic. A region is a buffer in that there is not an extra null-termination byte. Also a copy of a reference is a reference not a separate string. It is ill-behaved in that it is invalidated when the parent goes out of scope, is deleted, or assigned a different value. Value semantics are violated here.

Note: to create a buffer of, say, size 10 use

SS s (SS::Buffer(10))

SS s(10)

When Super String allocates the memory for its representation it always allocates an additional byte for zero termination. Since a non zero terminated Super String can be easily constructed with these methods generalized code to handle Super Strings should not assume zero termination.

How to use it

Predefined Find Objects

A type is considered fully supported if an object of that type can convert to and from a Super String, be assigned to or concatenated with a Super String, and compared to a Super String using any relational operator. This section describes the mechanism to accomplish these operations. Here are the types currently fully supported:

Arbitrary types can be added by means of non-member functions that are called by the appropriate template member function. For example, to allow an object of type X to convert to a Super String supply a SSconvert (X, SS&), rather than X::operator SS().

These function implement Super String support for a given type. Additional supported types can be added by the user. It is not required that all these functions be supplied. SSconvert is typically the most useful. Note that a problematic template <class T> SS::operator T() could be defined.

Binary operations with Super String are implemented as member template functions for Super String on the left; as non-member template functions for Super String on the right. Concatenation is performed by converting the operand to Super String and concatenating the strings. Thus, the corresponding SSconvert must be defined.

Relational operators require the definition of the appropriate SScompare. This additional function allows more flexibility and potentially greater performance than converting the operand to string and then comparing as strings. Comparisons are assumed to commute.

Bounds Checking

An out of range single character access is considered definitely to be an error.

Bounds Adjusting

Some of Super String's methods allow negative lengths and/or starting points that lie outside the string. This is to facilitate usage in algorithms that generate endpoints that are out of range or arbitrarily ordered. Thus it is not necessary to manually truncate and order the range before use. The tradeoff for this feature is reduced error detection.

The range will be normalized into a valid range. A range completely outside of the string is a null operation. Methods that operate on a range include get, set, cut, removeRange, replaceRange, and operator(). A out of range position for paste will result in a prepend or an append.

An out of range multiple character access is considered possibly correct.

Some member functions throw exceptions. The root of the exception hierarchy is SS::Error, so catching it will also catch the rest. A char const * what() const method will give a descriptive error message. The exception can be caught as a reference or a value, i.e.

catch (SS::Error error)

Integral constants are currently implemented as enums.

We can't get perfect compatibility here. If user code tries to reallocate the string or truncate by embedding a null the change won't be reflected in the string object. char* strings compare as pointers, not as values. Taking the address of a string object does not result in the address of a char*. A string object cannot also be an iterator the way a char* can.

How

Why

• Use with legacy C code.
• Use with non-legacy code that happens to use char*.
• An efficient way to transfer data among different systems or disparate objects.

As an example of the last, consider that many string classes allow conversion both to and from char*; the data flows easy from one to the next.

Details

• Legacy (or other) code may have non const correct prototyped functions and assignments.
• Changing the characters of a char* string is a fairly common operation.
• The string object can manage memory for a buffer; something else can fill it.

Caveats

• Assignment to a string object results in a copy of the char* string.
• The + operators don't result in an incremented char*, they append.
• The ==, !=, >, <, >=, and <= operators compare values not pointers.
• *, !, -, ++, and -- are not defined. If they were they might not work in the same way as char*

• External memory management for the internal representation of the string is not supported. Specifically new, delete, malloc, and free cannot be performed.
• Embedding a '0' externally will not change the recorded length of the string. However, the length will be changed with regard to any further zero terminated logic.
• Changing the zero termination byte will have the usual bad results, but only with zero terminated logic.