Contents

• Public Functions
• Static Public Members
• Related Non-Members
• Detailed Description

Detailed Description

TheQStringRef class provides a thin wrapper aroundQString substrings.

QStringRef provides a read-only subset of theQString API.

A string reference explicitly references a portion of astring() with a givensize(), starting at a specificposition(). CallingtoString() returns a copy of the data as a realQString instance.

This class is designed to improve the performance of substring handling when manipulating substrings obtained from existingQString instances.QStringRef avoids the memory allocation and reference counting overhead of a standardQString 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 usingQStringRef instead ofQString sinceQStringRef requires attention to be paid to memory management issues, potentially making code more complex to write and maintain.

Warning: AQStringRef 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 an empty string reference.

QStringRef::QStringRef(constQString * string,int position,int length)

Constructs a string reference to the range of characters in the givenstring specified by the startingposition andlength in characters.

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

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

QStringRef::QStringRef(constQString * string)

Constructs a string reference to the givenstring.

QStringRef::QStringRef(constQStringRef & other)

Constructs a copy of theother string reference.

QStringRef::~QStringRef()

Destroys the string reference.

Since this class is only used to refer to string data, and does not take ownership of it, no memory is freed when instances are destroyed.

QStringRef QStringRef::appendTo(QString * string) const

Appends the string reference tostring, and returns a new reference to the combined string data.

constQChar QStringRef::at(int position) const

Returns the character at the given indexposition in the string reference.

Theposition must be a valid index position in the string (i.e., 0 <=position <size()).

void QStringRef::clear()

Clears the contents of the string reference by making it null and empty.

See alsoisEmpty() andisNull().

[static]int QStringRef::compare(constQStringRef & s1, constQString & s2,Qt::CaseSensitivity cs = Qt::CaseSensitive)

Compares the strings1 with the strings2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

Ifcs isQt::CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

This function was introduced in Qt 4.5.

[static]int QStringRef::compare(constQStringRef & s1, constQStringRef & s2,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This is an overloaded function.

Compares the strings1 with the strings2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

Ifcs isQt::CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

This function was introduced in Qt 4.5.

[static]int QStringRef::compare(constQStringRef & s1,QLatin1String s2,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This is an overloaded function.

Compares the strings1 with the strings2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

Ifcs isQt::CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

This function was introduced in Qt 4.5.

int QStringRef::compare(constQString & other,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This is an overloaded function.

Compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than theother string.

Ifcs isQt::CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

Equivalent tocompare(*this, other, cs).

This function was introduced in Qt 4.5.

See alsoQString::compare().

int QStringRef::compare(constQStringRef & other,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This is an overloaded function.

Compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than theother string.

Ifcs isQt::CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

Equivalent tocompare(*this, other, cs).

This function was introduced in Qt 4.5.

See alsoQString::compare().

int QStringRef::compare(QLatin1String other,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This is an overloaded function.

Compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than theother string.

Ifcs isQt::CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

Equivalent tocompare(*this, other, cs).

This function was introduced in Qt 4.5.

See alsoQString::compare().

constQChar * QStringRef::constData() const

Same asunicode().

bool QStringRef::contains(constQString & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if this string reference contains an occurrence of the stringstr; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoindexOf() andcount().

bool QStringRef::contains(QChar ch,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscontains().

Returns true if this string contains an occurrence of the characterch; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

bool QStringRef::contains(constQStringRef & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscontains().

Returns true if this string reference contains an occurrence of the string referencestr; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoindexOf() andcount().

bool QStringRef::contains(QLatin1String str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscontains().

Returns true if this string reference contains an occurrence of the stringstr; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4,8.

See alsoindexOf() andcount().

int QStringRef::count() const

Returns the number of characters referred to by the string reference. Equivalent tosize() andlength().

See alsoposition() andstring().

int QStringRef::count(constQString & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the number of (potentially overlapping) occurrences of the stringstr in this string reference.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::count(),contains(), andindexOf().

int QStringRef::count(QChar ch,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscount().

Returns the number of occurrences of the characterch in the string reference.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::count(),contains(), andindexOf().

int QStringRef::count(constQStringRef & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscount().

Returns the number of (potentially overlapping) occurrences of the string referencestr in this string reference.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::count(),contains(), andindexOf().

constQChar * QStringRef::data() const

Same asunicode().

bool QStringRef::endsWith(constQString & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if the string reference ends withstr; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::endsWith() andstartsWith().

bool QStringRef::endsWith(QChar ch,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsendsWith().

Returns true if the string reference ends withch; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::endsWith() andendsWith().

bool QStringRef::endsWith(QLatin1String str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsendsWith().

This function was introduced in Qt 4.8.

See alsoQString::endsWith() andendsWith().

bool QStringRef::endsWith(constQStringRef & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsendsWith().

This function was introduced in Qt 4.8.

See alsoQString::endsWith() andendsWith().

int QStringRef::indexOf(constQString & str,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the first occurrence of the stringstr in this string reference, searching forward from index positionfrom. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Iffrom is -1, the search starts at the last character; if it is -2, at the next to last character and so on.

This function was introduced in Qt 4.8.

See alsoQString::indexOf(),lastIndexOf(),contains(), andcount().

int QStringRef::indexOf(QLatin1String str,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the first occurrence of the stringstr in this string reference, searching forward from index positionfrom. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Iffrom is -1, the search starts at the last character; if it is -2, at the next to last character and so on.

This function was introduced in Qt 4.8.

See alsoQString::indexOf(),lastIndexOf(),contains(), andcount().

int QStringRef::indexOf(QChar ch,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsindexOf().

Returns the index position of the first occurrence of the characterch in the string reference, searching forward from index positionfrom. Returns -1 ifch could not be found.

This function was introduced in Qt 4.8.

See alsoQString::indexOf(),lastIndexOf(),contains(), andcount().

int QStringRef::indexOf(constQStringRef & str,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsindexOf().

Returns the index position of the first occurrence of the string referencestr in this string reference, searching forward from index positionfrom. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::indexOf(),lastIndexOf(),contains(), andcount().

bool QStringRef::isEmpty() const

Returns true if the string reference has no characters; otherwise returns false.

A string reference is empty if its size is zero.

See alsosize().

bool QStringRef::isNull() const

Returns true ifstring() returns a null pointer or a pointer to a null string; otherwise returns true.

See alsosize().

int QStringRef::lastIndexOf(constQString & str,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the last occurrence of the stringstr in this string reference, searching backward from index positionfrom. Iffrom is -1 (default), the search starts at the last character; iffrom is -2, at the next to last character and so on. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::lastIndexOf(),indexOf(),contains(), andcount().

int QStringRef::lastIndexOf(QChar ch,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadslastIndexOf().

Returns the index position of the last occurrence of the characterch, searching backward from positionfrom.

This function was introduced in Qt 4.8.

See alsoQString::lastIndexOf(),indexOf(),contains(), andcount().

int QStringRef::lastIndexOf(QLatin1String str,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadslastIndexOf().

Returns the index position of the last occurrence of the stringstr in this string reference, searching backward from index positionfrom. Iffrom is -1 (default), the search starts at the last character; iffrom is -2, at the next to last character and so on. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::lastIndexOf(),indexOf(),contains(), andcount().

int QStringRef::lastIndexOf(constQStringRef & str,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadslastIndexOf().

Returns the index position of the last occurrence of the string referencestr in this string reference, searching backward from index positionfrom. Iffrom is -1 (default), the search starts at the last character; iffrom is -2, at the next to last character and so on. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::lastIndexOf(),indexOf(),contains(), andcount().

int QStringRef::length() const

Returns the number of characters referred to by the string reference. Equivalent tosize() andcount().

See alsoposition() andstring().

[static]int QStringRef::localeAwareCompare(constQStringRef & s1, constQString & s2)

Comparess1 withs2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

On Mac OS X, this function compares according the "Order for sorted lists" setting in the International prefereces panel.

This function was introduced in Qt 4.5.

See alsocompare() andQTextCodec::locale().

[static]int QStringRef::localeAwareCompare(constQStringRef & s1, constQStringRef & s2)

This is an overloaded function.

Comparess1 withs2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

This function was introduced in Qt 4.5.

int QStringRef::localeAwareCompare(constQString & other) const

This is an overloaded function.

Compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than theother string.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

This function was introduced in Qt 4.5.

int QStringRef::localeAwareCompare(constQStringRef & other) const

This is an overloaded function.

Compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than theother string.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

This function was introduced in Qt 4.5.

int QStringRef::position() const

Returns the starting position in the referenced string that is referred to by the string reference.

See alsosize() andstring().

int QStringRef::size() const

Returns the number of characters referred to by the string reference. Equivalent tolength() andcount().

See alsoposition() andstring().

bool QStringRef::startsWith(constQString & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if the string reference starts withstr; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::startsWith() andendsWith().

bool QStringRef::startsWith(QLatin1String str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsstartsWith().

This function was introduced in Qt 4.8.

See alsoQString::startsWith() andendsWith().

bool QStringRef::startsWith(constQStringRef & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsstartsWith().

This function was introduced in Qt 4.8.

See alsoQString::startsWith() andendsWith().

bool QStringRef::startsWith(QChar ch,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsstartsWith().

Returns true if the string reference starts withch; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoQString::startsWith() andendsWith().

constQString * QStringRef::string() const

Returns a pointer to the string referred to by the string reference, or 0 if it does not reference a string.

See alsounicode().

QByteArray QStringRef::toAscii() const

Returns an 8-bit representation of the string as aQByteArray.

If a codec has been set usingQTextCodec::setCodecForCStrings(), it is used to convert Unicode to 8-bit char; otherwise this function does the same astoLatin1().

Note that, despite the name, this function does not necessarily return an US-ASCII (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.

This function was introduced in Qt 4.8.

See alsotoLatin1(),toUtf8(),toLocal8Bit(), andQTextCodec.

QByteArray QStringRef::toLatin1() const

Returns a Latin-1 representation of the string as aQByteArray.

The returned byte array is undefined if the string contains non-Latin1 characters. Those characters may be suppressed or replaced with a question mark.

This function was introduced in Qt 4.8.

See alsotoAscii(),toUtf8(),toLocal8Bit(), andQTextCodec.

QByteArray QStringRef::toLocal8Bit() const

Returns the local 8-bit representation of the string as aQByteArray. The returned byte array is undefined if the string contains characters not supported by the local 8-bit encoding.

QTextCodec::codecForLocale() is used to perform the conversion from Unicode. If the locale encoding could not be determined, this function does the same astoLatin1().

If this string contains any characters that cannot be encoded in the locale, the returned byte array is undefined. Those characters may be suppressed or replaced by another.

This function was introduced in Qt 4.8.

See alsotoAscii(),toLatin1(),toUtf8(), andQTextCodec.

QString QStringRef::toString() const

Returns a copy of the string reference as aQString object.

If the string reference is not a complete reference of the string (meaning thatposition() is 0 andsize() equalsstring()->size()), this function will allocate a new string to return.

See alsostring().

QVector<uint> QStringRef::toUcs4() const

Returns a UCS-4/UTF-32 representation of the string as aQVector<uint>.

UCS-4 is a Unicode codec and is lossless. All characters from this string can be encoded in UCS-4.

This function was introduced in Qt 4.8.

See alsotoAscii(),toLatin1(),toLocal8Bit(), andQTextCodec.

QByteArray QStringRef::toUtf8() const

Returns a UTF-8 representation of the string as aQByteArray.

UTF-8 is a Unicode codec and can represent all characters in a Unicode string likeQString.

However, in the Unicode range, there are certain codepoints that are not considered characters. The Unicode standard reserves the last two codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF, inclusive, as non-characters. If any of those appear in the string, they may be discarded and will not appear in the UTF-8 representation, or they may be replaced by one or more replacement characters.

This function was introduced in Qt 4.8.

See alsotoAscii(),toLatin1(),toLocal8Bit(), andQTextCodec.

constQChar * QStringRef::unicode() const

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.

See alsostring().

QStringRef & QStringRef::operator=(constQStringRef & other)

Assigns theother string reference to this string reference, and returns the result.

QStringRef & QStringRef::operator=(constQString * string)

Constructs a string reference to the givenstring and assigns it to this string reference, returning the result.

Related Non-Members

booloperator<(constQStringRef & s1, constQStringRef & s2)

Returns true if string references1 is lexically less than string references2; 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 theQString::localeAwareCompare() function.

booloperator<=(constQStringRef & s1, constQStringRef & s2)

Returns true if string references1 is lexically less than or equal to string references2; 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 theQString::localeAwareCompare() function.

booloperator==(constQStringRef & s1, constQStringRef & s2)

Returns true if string references1 is lexically equal to string references2; otherwise returns false.

booloperator==(constQString & s1, constQStringRef & s2)

Returns true if strings1 is lexically equal to string references2; otherwise returns false.

booloperator==(constQLatin1String & s1, constQStringRef & s2)

Returns true if strings1 is lexically equal to string references2; otherwise returns false.

booloperator>(constQStringRef & s1, constQStringRef & s2)

Returns true if string references1 is lexically greater than string references2; 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 theQString::localeAwareCompare() function.

booloperator>=(constQStringRef & s1, constQStringRef & s2)

Returns true if string references1 is lexically greater than or equal to string references2; 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 theQString::localeAwareCompare() function.