|  | Home · All Classes · Modules

# QStringRef Class Reference
[QtCore module]

The QStringRef class provides a thin wrapper around QString substrings. More...

### Methods

- __init__ (self)
- __init__ (self, QString aString, int aPosition, int aSize)
- __init__ (self, QString aString)
- __init__ (self, QStringRef other)
- QStringRef appendTo (self, QString string)
- QChar at (self, int i)
- clear (self)
- int compare (self, QString other, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int compare (self, QStringRef other, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int compare (self, QLatin1String other, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- QChar constData (self)
- bool contains (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- bool contains (self, QLatin1String str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- bool contains (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int count (self)
- int count (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int count (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- QChar data (self)
- bool endsWith (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- bool endsWith (self, QLatin1String str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- bool endsWith (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int indexOf (self, QString str, int from = 0, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int indexOf (self, QLatin1String str, int from = 0, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int indexOf (self, QStringRef str, int from = 0, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- bool isEmpty (self)
- bool isNull (self)
- int lastIndexOf (self, QString str, int from = -1, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int lastIndexOf (self, QLatin1String str, int from = -1, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int lastIndexOf (self, QStringRef str, int from = -1, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int length (self)
- int localeAwareCompare (self, QString s)
- int localeAwareCompare (self, QStringRef s)
- int position (self)
- int size (self)
- bool startsWith (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- bool startsWith (self, QLatin1String str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- bool startsWith (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- QString string (self)
- QByteArray toAscii (self)
- QByteArray toLatin1 (self)
- QByteArray toLocal8Bit (self)
- QString toString (self)
- list-of-int toUcs4 (self)
- QByteArray toUtf8 (self)
- QChar unicode (self)

### Static Methods

- int compare (QStringRef s1, QString s2, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int compare (QStringRef s1, QStringRef s2, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int compare (QStringRef s1, QLatin1String s2, Qt.CaseSensitivity cs = Qt.CaseSensitive)
- int localeAwareCompare (QStringRef s1, QString s2)
- int localeAwareCompare (QStringRef s1, QStringRef s2)

### Special Methods

- bool __eq__ (self, QStringRef s2)
- bool __eq__ (self, QString s2)
- bool __eq__ (self, QLatin1String s2)
- bool __ge__ (self, QStringRef s2)
- bool __gt__ (self, QStringRef s2)
- bool __le__ (self, QStringRef s2)
- __len__ (self)
- bool __lt__ (self, QStringRef s2)
- bool __ne__ (self, QStringRef s2)
- bool __ne__ (self, QString s2)
- bool __ne__ (self, QLatin1String s2)
- str __str__ (self)

## Detailed Description

The QStringRef class provides a thin wrapper around QString substrings.

QStringRef provides a read-only subset of the QString API.

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.

## Method Documentation

### QStringRef.__init__ (self)

Constructs an empty string reference.

### QStringRef.__init__ (self, QString aString, int aPosition, int aSize)

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.

### QStringRef.__init__ (self, QString aString)

Constructs a string reference to the given string.

### QStringRef.__init__ (self, QStringRef other)

Constructs a copy of the other string reference.

### QStringRef QStringRef.appendTo (self, QString string)

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

### QChar QStringRef.at (self, int i)

Returns the character at the given index position in the string reference.

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

### QStringRef.clear (self)

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

See also isEmpty() and isNull().

### int QStringRef.compare (self, QString other, Qt.CaseSensitivity cs = Qt.CaseSensitive)

Compares the string s1 with the string s2 and returns an integer less than, equal to, or greater than zero if s1 is less than, equal to, or greater than s2.

If cs is Qt.CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

This function was introduced in Qt 4.5.

### int QStringRef.compare (self, QStringRef other, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This is an overloaded function.

Compares the string s1 with the string s2 and returns an integer less than, equal to, or greater than zero if s1 is less than, equal to, or greater than s2.

If cs is Qt.CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

This function was introduced in Qt 4.5.

### int QStringRef.compare (self, QLatin1String other, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This is an overloaded function.

Compares the string s1 with the string s2 and returns an integer less than, equal to, or greater than zero if s1 is less than, equal to, or greater than s2.

If cs is Qt.CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

This function was introduced in Qt 4.5.

### int QStringRef.compare (QStringRef s1, QString s2, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This is an overloaded function.

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

If cs is Qt.CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

Equivalent to `compare(*this, other, cs)`.

This function was introduced in Qt 4.5.

See also QString.compare().

### int QStringRef.compare (QStringRef s1, QStringRef s2, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This is an overloaded function.

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

If cs is Qt.CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

Equivalent to `compare(*this, other, cs)`.

This function was introduced in Qt 4.5.

See also QString.compare().

### int QStringRef.compare (QStringRef s1, QLatin1String s2, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This is an overloaded function.

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

If cs is Qt.CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

Equivalent to `compare(*this, other, cs)`.

This function was introduced in Qt 4.5.

See also QString.compare().

### QChar QStringRef.constData (self)

Same as unicode().

### bool QStringRef.contains (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also indexOf() and count().

### bool QStringRef.contains (self, QLatin1String str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads contains().

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

### bool QStringRef.contains (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads contains().

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also indexOf() and count().

### int QStringRef.count (self)

Returns the number of characters referred to by the string reference. Equivalent to size() and length().

See also position() and string().

### int QStringRef.count (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also QString.count(), contains(), and indexOf().

### int QStringRef.count (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads count().

Returns the number of occurrences of the character ch in the string reference.

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also QString.count(), contains(), and indexOf().

### QChar QStringRef.data (self)

Same as unicode().

### bool QStringRef.endsWith (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also QString.endsWith() and startsWith().

### bool QStringRef.endsWith (self, QLatin1String str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads endsWith().

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also QString.endsWith() and endsWith().

### bool QStringRef.endsWith (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads endsWith().

This function was introduced in Qt 4.8.

See also QString.endsWith() and endsWith().

### int QStringRef.indexOf (self, QString str, int from = 0, Qt.CaseSensitivity cs = Qt.CaseSensitive)

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

If from 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 also QString.indexOf(), lastIndexOf(), contains(), and count().

### int QStringRef.indexOf (self, QLatin1String str, int from = 0, Qt.CaseSensitivity cs = Qt.CaseSensitive)

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

If from 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 also QString.indexOf(), lastIndexOf(), contains(), and count().

### int QStringRef.indexOf (self, QStringRef str, int from = 0, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads indexOf().

Returns the index position of the first occurrence of the character ch in the string reference, searching forward from index position from. Returns -1 if ch could not be found.

This function was introduced in Qt 4.8.

See also QString.indexOf(), lastIndexOf(), contains(), and count().

### bool QStringRef.isEmpty (self)

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

A string reference is empty if its size is zero.

See also size().

### bool QStringRef.isNull (self)

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

See also size().

### int QStringRef.lastIndexOf (self, QString str, int from = -1, Qt.CaseSensitivity cs = Qt.CaseSensitive)

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also QString.lastIndexOf(), indexOf(), contains(), and count().

### int QStringRef.lastIndexOf (self, QLatin1String str, int from = -1, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads lastIndexOf().

Returns the index position of the last occurrence of the character ch, searching backward from position from.

This function was introduced in Qt 4.8.

See also QString.lastIndexOf(), indexOf(), contains(), and count().

### int QStringRef.lastIndexOf (self, QStringRef str, int from = -1, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads lastIndexOf().

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also QString.lastIndexOf(), indexOf(), contains(), and count().

### int QStringRef.length (self)

Returns the number of characters referred to by the string reference. Equivalent to size() and count().

See also position() and string().

### int QStringRef.localeAwareCompare (self, QString s)

Compares s1 with s2 and returns an integer less than, equal to, or greater than zero if s1 is less than, equal to, or greater than s2.

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 also compare() and QTextCodec.locale().

### int QStringRef.localeAwareCompare (self, QStringRef s)

This is an overloaded function.

Compares s1 with s2 and returns an integer less than, equal to, or greater than zero if s1 is less than, equal to, or greater than s2.

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 (QStringRef s1, QString s2)

This is an overloaded function.

Compares this string with the other string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than the other 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 (QStringRef s1, QStringRef s2)

This is an overloaded function.

Compares this string with the other string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than the other 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 (self)

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

See also size() and string().

### int QStringRef.size (self)

Returns the number of characters referred to by the string reference. Equivalent to length() and count().

See also position() and string().

### bool QStringRef.startsWith (self, QString str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

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

If cs is Qt.CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See also QString.startsWith() and endsWith().

### bool QStringRef.startsWith (self, QLatin1String str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads startsWith().

This function was introduced in Qt 4.8.

See also QString.startsWith() and endsWith().

### bool QStringRef.startsWith (self, QStringRef str, Qt.CaseSensitivity cs = Qt.CaseSensitive)

This function overloads startsWith().

This function was introduced in Qt 4.8.

See also QString.startsWith() and endsWith().

### QString QStringRef.string (self)

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

See also unicode().

### QByteArray QStringRef.toAscii (self)

Returns an 8-bit representation of the string as a QByteArray.

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

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 also toLatin1(), toUtf8(), toLocal8Bit(), and QTextCodec.

### QByteArray QStringRef.toLatin1 (self)

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

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 also toAscii(), toUtf8(), toLocal8Bit(), and QTextCodec.

### QByteArray QStringRef.toLocal8Bit (self)

Returns the local 8-bit representation of the string as a QByteArray. 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 as toLatin1().

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 also toAscii(), toLatin1(), toUtf8(), and QTextCodec.

### QString QStringRef.toString (self)

Returns a copy of the string reference as a QString object.

If the string reference is not a complete reference of the string (meaning that position() is 0 and size() equals string()->size()), this function will allocate a new string to return.

See also string().

### list-of-int QStringRef.toUcs4 (self)

Returns a UCS-4/UTF-32 representation of the string as a QVector<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 also toAscii(), toLatin1(), toLocal8Bit(), and QTextCodec.

### QByteArray QStringRef.toUtf8 (self)

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

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

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 also toAscii(), toLatin1(), toLocal8Bit(), and QTextCodec.

### QChar QStringRef.unicode (self)

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 also string().

### bool QStringRef.__eq__ (self, QStringRef s2)

### bool QStringRef.__eq__ (self, QString s2)

### bool QStringRef.__eq__ (self, QLatin1String s2)

### bool QStringRef.__ge__ (self, QStringRef s2)

### bool QStringRef.__gt__ (self, QStringRef s2)

### bool QStringRef.__le__ (self, QStringRef s2)

### QStringRef.__len__ (self)

### bool QStringRef.__lt__ (self, QStringRef s2)

### bool QStringRef.__ne__ (self, QStringRef s2)

### bool QStringRef.__ne__ (self, QString s2)

### bool QStringRef.__ne__ (self, QLatin1String s2)

### str QStringRef.__str__ (self)