||ASCII case-insensitive comparator. (for Unicode case-insensitive
comparision, see nsUnicharUtils.h)
||Some macros for converting char16_t (UTF-16) to and from Unicode scalar
Note that UTF-16 represents all Unicode scalar values up to U+10FFFF by
using "surrogate pairs". These consist of a high surrogate, i.e. a code
point in the range U+D800 - U+DBFF, and a low surrogate, i.e. a code point
in the range U+DC00 - U+DFFF, like this:
U+D800 U+DC00 = U+10000
U+D800 U+DC01 = U+10001
U+DBFF U+DFFE = U+10FFFE
U+DBFF U+DFFF = U+10FFFF
These surrogate code points U+D800 - U+DFFF are not themselves valid Unicode
scalar values and are not well-formed UTF-16 except as high-surrogate /
||nsPrintfCString lets you create a nsCString using a printf-style format
string. For example:
NS_WARNING(nsPrintfCString("Unexpected value: %f", 13.917).get());
nsPrintfCString has a small built-in auto-buffer. For larger strings, it
will allocate on the heap.
See also nsCString::AppendPrintf().
||A helper function that allocates a buffer of the desired character type big
enough to hold a copy of the supplied string (plus a zero terminator).
@param aSource an string you will eventually be making a copy of
@return a new buffer which you must free with |free|.
||I guess all the routines in this file are all mis-named.
According to our conventions, they should be |NS_xxx|.
||A helper class that converts a UTF-16 string to ASCII in a lossy manner
||Alloc returns a pointer to a new string header with set capacity.
||This structure precedes the string buffers "we" allocate. It may be the
case that nsTAString::mData does not point to one of these special
buffers. The mDataFlags member variable distinguishes the buffer type.
When this header is in use, it enables reference counting, and capacity
tracking. NOTE: A string buffer can be modified only if its reference
count is 1.
||nsStringFwd.h --- forward declarations for string classes
Stores a null-terminated, immutable sequence of characters.
Subclass of nsTString that restricts string value to an immutable
character sequence. This class does not own its data, so the creator
of objects of this type must take care to ensure that a
nsTDependentString continues to reference valid memory for the
duration of its use.
A string class which wraps an external array of string characters. It
is the client code's responsibility to ensure that the external buffer
remains valid for a long as the string is alive.
nsDependentSubstring for wide characters
nsDependentCSubstring for narrow characters
||Portable safe sprintf code.
Code based on mozilla/nsprpub/src/io/prprf.c rev 3.7
Kipp E.B. Hickman <email@example.com> (original author)
Frank Yung-Fong Tang <firstname.lastname@example.org>
Daniele Nicolodi <email@example.com>
||This code was copied from xpcom/ds/nsTextFormatter r1.3
Memory model and Frozen linkage changes only.
-- Prasad <firstname.lastname@example.org>
Stores a null-terminated, immutable sequence of characters.
nsTString-lookalike that restricts its string value to a literal character
sequence. Can be implicitly cast to const nsTString& (the const is
essential, since this class's data are not writable). The data are assumed
to be static (permanent) and therefore, as an optimization, this class
does not have a destructor.
Try to avoid flat strings. |PromiseFlat[C]String| will help you as a last
resort, and this may be necessary when dealing with legacy or OS calls,
but in general, requiring a null-terminated array of characters kills many
of the performance wins the string classes offer. Write your own code to
use |nsA[C]String&|s for parameters. Write your string proccessing
algorithms to exploit iterators. If you do this, you will benefit from
being able to chain operations without copying or allocating and your code
will be significantly more efficient. Remember, a function that takes an
|const nsA[C]String&| can always be passed a raw character pointer by
wrapping it (for free) in a |nsDependent[C]String|. But a function that
takes a character pointer always has the potential to force allocation and
How to use it:
A |nsPromiseFlat[C]String| doesn't necessarily own the characters it
promises. You must never use it to promise characters out of a string
with a shorter lifespan. The typical use will be something like this:
SomeOSFunction( PromiseFlatCString(aCSubstring).get() ); // GOOD
Here's a BAD use:
const char* buffer = PromiseFlatCString(aCSubstring).get();
SomeOSFunction(buffer); // BAD!! |buffer| is a dangling pointer
The only way to make one is with the function |PromiseFlat[C]String|,
which produce a |const| instance. ``What if I need to keep a promise
around for a little while?'' you might ask. In that case, you can keep a
reference, like so:
const nsCString& flat = PromiseFlatString(aCSubstring);
// Temporaries usually die after the full expression containing the
// expression that created the temporary is evaluated. But when a
// temporary is assigned to a local reference, the temporary's lifetime
// is extended to the reference's lifetime (C++11 [class.temporary]p5).
// This reference holds the anonymous temporary alive. But remember: it
// must _still_ have a lifetime shorter than that of |aCSubstring|, and
// |aCSubstring| must not be changed while the PromiseFlatString lives.
How does it work?
A |nsPromiseFlat[C]String| is just a wrapper for another string. If you
apply it to a string that happens to be flat, your promise is just a
dependent reference to the string's data. If you apply it to a non-flat
string, then a temporary flat string is created for you, by allocating and
copying. In the event that you end up assigning the result into a sharing
string (e.g., |nsTString|), the right thing happens.
||This is the canonical null-terminated string class. All subclasses
promise null-terminated storage. Instances of this class allocate
strings on the heap.
nsString for wide characters
nsCString for narrow characters
This class is also known as nsAFlat[C]String, where "flat" is used
to denote a null-terminated string.
||This handle represents permission to perform low-level writes
the storage buffer of a string in a manner that's aware of the
actual capacity of the storage buffer allocation and that's
cache-friendly in the sense that the writing of zero terminator
for C compatibility can happen in linear memory access order
(i.e. the zero terminator write takes place after writing
new content to the string as opposed to the zero terminator
write happening first causing a non-linear memory write for
If you requested a prefix to be preserved when starting
or restarting the bulk write, the prefix is present at the
start of the buffer exposed by this handle as Span or
as a raw pointer, and it's your responsibility to start
writing after after the preserved prefix (which you
presumably wanted not to overwrite since you asked for
it to be preserved).
In a success case, you must call Finish() with the new
length of the string. In failure cases, it's OK to return
early from the function whose local variable this handle is.
The destructor of this class takes care of putting the
string in a valid and mostly harmless state in that case
by setting the value of a non-empty string to a single
REPLACEMENT CHARACTER or in the case of nsACString that's
too short for a REPLACEMENT CHARACTER to fit, an ASCII
You must not allow this handle to outlive the string you
obtained it from.
You must not access the string you obtained this handle
from in any way other than through this handle until
you call Finish() on the handle or the handle goes out
Once you've called Finish(), you must not call any
methods on this handle and must not use values previously
Once you call RestartBulkWrite(), you must not use
values previously obtained from this handle and must
reobtain the new corresponding values.
||computes the aggregate string length
Represents a tuple of string fragments. Built as a recursive binary tree.
It is used to implement the concatenation of two or more string objects.
NOTE: This class is a private implementation detail and should never be
referenced outside the string code.
||Extract the next Unicode scalar value from the buffer and return it. The
pointer passed in is advanced to the start of the next character in the
buffer. Upon error, the return value is 0xFFFD, *aBuffer is advanced
over the maximal valid prefix and *aErr is set to true (if aErr is not
Note: This method never sets *aErr to false to allow error accumulation
across multiple calls.
Precondition: *aBuffer < aEnd
||RustRegexCaptures represents storage for sub-capture locations of a match.
Computing the capture groups of a match can carry a significant performance
penalty, so their use in the API is optional.
A RustRegexCaptures value may outlive its corresponding RustRegex and can be
It is not safe to use from multiple threads simultaneously.