184
edits
Gecko:Overview: Difference between revisions
nsCAutoString -> nsAutoCString
m (→Style System: typo: s/caled/called/) |
(nsCAutoString -> nsAutoCString) |
||
| Line 637: | Line 637: | ||
=== String === | === String === | ||
XPCOM has string classes for representing sequences of characters. We have two parallel sets of classes, one for strings with 1-byte units (<code>char</code>, which may be signed or unsigned), and one for strings with 2-byte units (<code>PRUnichar</code>, always unsigned). The classes are named such that the class for 2-byte characters ends with <code>String</code> and the corresponding class for 1-byte characters ends with <code>CString</code> | XPCOM has string classes for representing sequences of characters. We have two parallel sets of classes, one for strings with 1-byte units (<code>char</code>, which may be signed or unsigned), and one for strings with 2-byte units (<code>PRUnichar</code>, always unsigned). The classes are named such that the class for 2-byte characters ends with <code>String</code> and the corresponding class for 1-byte characters ends with <code>CString</code>. 2-byte strings are almost always used to encode [http://en.wikipedia.org/wiki/UTF-16 UTF-16]. 1-byte strings are usually used to encode either [http://en.wikipedia.org/wiki/ASCII ASCII] or [http://en.wikipedia.org/wiki/UTF-8 UTF-8], but are sometimes also used to hold data in some other encoding or just byte sequences. | ||
The string classes distinguish, as part of the type hierarchy, between strings that must have a null-terminator at the end of their buffer (<code>ns[C]String</code>) and strings that are not required to have a null-terminator (<code>ns[C]Substring</code>). <code>ns[C]Substring</code> is the base of the string classes (since it imposes fewer requirements) and <code>ns[C]String</code> is a class derived from it. Functions taking strings as parameters should generally take one of these four types. | The string classes distinguish, as part of the type hierarchy, between strings that must have a null-terminator at the end of their buffer (<code>ns[C]String</code>) and strings that are not required to have a null-terminator (<code>ns[C]Substring</code>). <code>ns[C]Substring</code> is the base of the string classes (since it imposes fewer requirements) and <code>ns[C]String</code> is a class derived from it. Functions taking strings as parameters should generally take one of these four types. | ||
| Line 645: | Line 645: | ||
* adopted buffers (a buffer that the string class owns, but is not reference counted, because it came from somewhere else) | * adopted buffers (a buffer that the string class owns, but is not reference counted, because it came from somewhere else) | ||
* dependent buffers, that is, an underlying buffer that the string class does not own, but that the caller that constructed the string guarantees will outlive the string instance | * dependent buffers, that is, an underlying buffer that the string class does not own, but that the caller that constructed the string guarantees will outlive the string instance | ||
In addition, there is a special string class, <code> | In addition, there is a special string class, <code>nsAuto[C]String</code>, that ''additionally'' contains an internal 64-unit buffer (intended primarily for use on the stack), leading to a fourth ownership model: | ||
* storage within an auto string's stack buffer | * storage within an auto string's stack buffer | ||
Auto strings will prefer reference counting an existing reference-counted buffer over their stack buffer, but will otherwise use their stack buffer for anything that will fit in it. | Auto strings will prefer reference counting an existing reference-counted buffer over their stack buffer, but will otherwise use their stack buffer for anything that will fit in it. | ||