CXString

The CXString class is considered the "default" string class in the cxsource framework. It offers a reasonable compromise of capabilities. Other string classes are available for more specific uses where the standard tradeoffs are not suitable.

A CXString object nominally stores UTF-8 encoded text with a zero termination byte. Strings are stored using copy-on-write references, and string pooling may optionally be enabled using a compile-time flag. CXString objects do not distinguish "null" and "empty" strings.

 

CXString is optimised for storage, read-access performance, copy performance, and map lookup. It is not optimised for editing, either from a usability or performance perspective.

 

Construction

// Efficiently construct an empty string.
CXString(void);

// Construct from a cxsource string object.
CXString(const CXString &str);
CXString(CXString&& rhs);
CXString(const class CXStringEdit& str);
CXString(const CXStringArgument& cstr);

// Construct from a character range.
CXString(const CXStringArgument& begin, const CXStringArgument& end);
CXString(const char* __nullable ch, size_t len);
CXString(const char* __nonnull ch, const char* __nonnull end);

// Construct from Objective-C string or data objects.
CXString(NSString* __nullable str);
CXString(NSData* __nullable data);

// Construct from a printf-style format string.
static CXString Fromf(const char* __nonnull format, ...);

Equivalent assingment operators are also available.

 

Comparison

 

// Equality operators test for byte-for-byte equality.  
bool operator==(const CXString& other) const;
bool operator==(const char* __nullable other) const;
bool operator!=(const CXString& other) const;
bool operator!=(const char* __nullable other) const;
  
// Byte-for-byte sort operators.
bool operator<(const CXString& other) const;
bool operator<=(const CXString& other) const;
bool operator>(const CXString& other) const;
bool operator>=(const CXString& other) const;

// Optimise hash operator.
struct std::hash<CXString>;

// Optimised std::map comparison function, non-alphabetic ordering.
struct CXStringPooledMapCompare;

 

 

Helpers

 

// Returns the length in bytes of this string, not including the zero terminator.
size_t Length(void) const;

// Returns true if this string has a length of zero.
bool IsEmpty(void) const;

// Returns a C String pointer to this string's internal data.
const char* __nonnull c_str(void) const;

// Returns a copy of the specified substring.
CXString Copy(size_t startIndex, size_t endIndex) const;

// Removes the specified substring.
void Del(signed_size_t startIndex, signed_size_t endIndex);

// Returns a copy of the specified substring.
CXString Left(signed_size_t len) const;

// Returns a copy of the specified substring.
CXString Right(signed_size_t len) const;

// Returns a copy of the specified substring.
CXString RightOf(signed_size_t pos) const;

// Returns the byte index of first match of the specified glpyh at or after the specified startIndex. Returns -1 if no match.
signed_size_t Pos(char glyph, size_t startIndex = 0) const;

// Returns true if the specified string is a byte-for-byte match for the front of this string.
bool MatchesPrefix(const CXString &p_prefix) const;

// Returns a reference to the specified character within this string. Valid from 0..Length() inclusive.
const char& operator[](size_t pos) const;

 

 

 

Constants

 

// A Length=1 string which contains a zero byte.
static const CXString NULLCHAR;

// An empty string.
static const CXString EMPTY;

// An empty, zero-terminated C string.
static const char* __nonnull kEmptyCString;

 

Streamers

 

// Writes a CXString to a binary stream.
CX_STREAMER_TMPL CX_STREAMER_QUAL& operator<<(CX_STREAMER_QUAL &a_streamer, const CXString &a_string)

// Reads a CXString from a binary stream. This should only be used only trusted streams, as
// the resultant string could in theory be gigabytes in size.
CX_STREAMER_TMPL CX_STREAMER_QUAL& operator>>(CX_STREAMER_QUAL &a_streamer, CXString &o_string)