CXStringArgument

CXStringArgument is not a string class per se, but rather allows string data to be passed to a function without requiring a separate funtion prototype for each supported string class and without requiring a runtime data type transformation to a single string class. It is similar to passing a (const char* __nonnull) but encodes length data, which helps prevent buffer overruns and which allows the string payload to contain zero bytes. As with all cxsource framework string classes, this class does not enforce any particular text encoding but UTF-8 should be used if text is being stored.

 

The CXStringArgument class does not contain the payload, but rather references an existing payload as provided to the constructor. As such, the class is only useful for short-term use while the payload's owner remains in scope, and is not useful as a string container format.

 

The CXStringArgument object can be used as a forward iterator. Each forward step effectively removes one character from the start of the string payload, reducing the overall length. The CXStringArgument may be safely copy constructed and/or assigned.

 

Construction

A CXStringArgument object may be constructed from a variety of character sources. As a reminder, the resultant CXStringArgument object references the string payload passed to the constructor; it does not copy it and it does not take ownership.

// Construct an empty CXStringArgument.
CXStringArgument(void);

// Construct a CXStringArgument from an existing string 
// object or character range.
CXStringArgument(const CXString& argument);
template <uint BUFSIZE> CXStringArgument(const CXStringEditBase<BUFSIZE>& argument);
CXStringArgument(const char* __nullable argument);
CXStringArgument(const char* __nullable argument, size_t length);
CXStringArgument(const char* __nonnull argumentBegin, const char* __nonnull argumentEnd);
CXStringArgument(NSString* __nullable str;
CXStringArgument(NSData* __nullable str;

 

Accessors

Accessors to the string payload.

// Returns a C pointer to (current cursor position in the)   
// payload. This does not return a C string; there is no 
// zero termination byte.
const char* __nonnull GetUnterminatedStringBuffer(void) const;

// Returns the number of bytes of string payload (remaining) in
// this object.
size_t Length(void) const;

// Returns a reference to a specified character within
// the string payload. The position is a byte offset.
// 'pos' may range between [0..Length()-1] inclusive.
const char& operator[](size_t pos) const;

// Returns the first character of the string payload.
// If the payload has no (remaining) characters, this
// returns zero.
const char operator* (void) const;

// Returns true if the payload has zero (remaining)
// length.
bool IsEmpty(void) const;

 

Cursor

// Increment the cursor by the specified number of bytes.
// Negative cursor movement is not permitted.  This
// increments the start position in the payload, reducing
// the length equivalently.
CXStringArgument& operator++(void);
CXStringArgument operator++(int);
void operator+=(int op);
CXStringArgument operator+(int op);

 

Helper

// Tests whether the two objects are bytewise equal.
bool Equals(const CXStringArgument& rhs) const;

// Tests whether the two objects are equal, ignoring ascii character case.
bool EqualsAsciiCaseInsensitive(const CXStringArgument& rhs) const;

// Performs a strcmp()-style comparison of the two objects.
int CompareBinaryString(const CXStringArgument& rhs) const;

// Compares two strings and returns a stable sort ordering which
// does not necessarily follow any external ordering conventions.
int CompareSortString(const CXStringArgument& rhs) const;

// Returns the relative offset (in bytes) from this CXStringArgument to
// the other. Both objects should refer to the same payload. This is
// useful while iterating, for example.
signed_size_t GetOffsetTo(const CXStringArgument& rhs) const;