Detailed Description

A string reference explicitly references a portion of a string() with a given size(), starting at a specific position(). Calling toString() returns a copy of the data as a real QString instance.

This class is designed to improve the performance of substring handling when manipulating substrings obtained from existing QString instances. QStringRef avoids the memory allocation and reference counting overhead of a standard QString by simply referencing a part of the original string. This can prove to be advantageous in low level code, such as that used in a parser, at the expense of potentially more complex code.

For most users, there are no semantic benefits to using QStringRef instead of QString since QStringRef requires attention to be paid to memory management issues, potentially making code more complex to write and maintain.

Warning: A QStringRef is only valid as long as the referenced string exists. If the original string is deleted, the string reference points to an invalid memory location.

We suggest that you only use this class in stable code where profiling has clearly identified that performance improvements can be made by replacing standard string operations with the optimized substring handling provided by this class.

Member Function Documentation

QStringRef::QStringRef ()

Constructs a string reference to the range of characters in the given string specified by the starting position and length in characters.

Warning: This function exists to improve performance as much as possible, and performs no bounds checking. For program correctness, position and length must describe a valid substring of string.

This means that the starting position must be positive or 0 and smaller than string's length, and length must be positive or 0 but smaller than the string's length minus the starting position; i.e, 0 <= position < string->length() and 0 <= length <= string->length() - position must both be satisfied.

Returns a Unicode representation of the string reference. Since the data stems directly from the referenced string, it is not null-terminated unless the string reference includes the string's null terminator.

Related Non-Members

bool operator< ( const QStringRef & s1, const QStringRef & s2 )

The comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. Consider sorting user-interface strings using the QString::localeAwareCompare() function.

bool operator<= ( const QStringRef & s1, const QStringRef & s2 )

Returns true if string reference s1 is lexically less than or equal to string reference s2; otherwise returns false.

The comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. Consider sorting user-interface strings using the QString::localeAwareCompare() function.

bool operator> ( const QStringRef & s1, const QStringRef & s2 )

The comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. Consider sorting user-interface strings using the QString::localeAwareCompare() function.

bool operator>= ( const QStringRef & s1, const QStringRef & s2 )

The comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. Consider sorting user-interface strings using the QString::localeAwareCompare() function.