+ A string is an opaque container holding a, possibly zero length, linear sequence of characters.
+ Understanding the implications of this statement is the foundation for understanding all mozilla's string classes.
+
+ I have a wide string, i.e., an instance of a class derived from nsAString
+
+
I want a pointer to the characters
+
I want a narrow string
+
I want to printf it
+
+
+
+ I have a PRUnichar*
+
+
I want a wide string
+
I want a narrow string
+
I want to printf it
+
+
+
+ I have a narrow string, i.e., an instance of a class derived from nsACString
+
+
I want a pointer to the characters
+
I want a narrow string
+
I want to printf it
+
+
+
+ I have a char*
+
+
I want a wide string
+
I want a narrow string
+
+
+
+ I have a literal character sequence, e.g., "Hello, World!\n"
+
+
I want a wide string
+
I want a narrow string
+
+
+
What's the best way to return a string?
+
How can I get a pointer to the characters in a string?
+
How can I printf a string?
+
+
+
+ is there any string doc?
+
+
+ Yes, you're soaking in it!
+
+
+
+ I have a string, how to I get a pointer to the characters?
+
+
+ ...
+
+
+
+ What is the best way to return a string?
+
+
+
+ There are several reasonable ways to produce a string result from a function.
+ If you are already holding the answer as a sharable string,
+ you can simply return that string (pass-by-value).
+ Otherwise,
+ the most efficient and flexible way to return a string is
+ to assign your result into a non-const reference parameter.
+ Don't bother to create a sharable string from scratch with your generated result.
+
+
+ Why?
+ The two things you want to minimize in string manipulation are,
+ in order of importance,
+ heap allocation, and
+ moving characters around.
+
+
+
+
+
+ If I have a PRUnichar *aKey [or other representation of a wide] string,
+ what can I use (easily :)
+ to convert it
+ to a printf() printable string?
+ Just for debugging...
+
+
+ If it's just for debugging,
+ you probably wouldn't care if something odd was printed in the case of a UCS2 character that didn't have
+ an ASCII equivalent.
+ The simplest thing in this case is to make a temporary conversion using NS_ConvertUCS2toUTF8.
+ Remember not to hold onto the pointer you get out of this beyond the lifetime of temporary.
+
+
+
+
+const PRUnichar* aKey;
+
+printf("%s\n", NS_ConvertUCS2toUTF8(aKey).get()); // GOOD
+ // the simplest way to get a |printf|-able |const char*| out of a string
+
+ // works just as well with an formal wide string type...
+const nsAString& aString = ...; // perhaps it's a parameter
+printf("%s\n", NS_ConvertUCS2toUTF8(aString).get());
+
+
+ // But don't hold onto the pointer longer than the lifetime of the temporary!
+const char* cstring = NS_ConvertUCS2toUTF8(aKey).get(); // BAD!
+printf("%s\n", cstring); // |cstring| is dangling
+
+
+
+
+
+
+
+
diff --git a/mozilla/xpcom/string/doc/string-guide.html b/mozilla/xpcom/string/doc/string-guide.html
index 821a1791a03..e02812ce9a9 100644
--- a/mozilla/xpcom/string/doc/string-guide.html
+++ b/mozilla/xpcom/string/doc/string-guide.html
@@ -2,7 +2,8 @@
the complete guide to mozilla/string
-
+
+
@@ -66,21 +67,26 @@
+ A string is an opaque container holding a, possibly zero length, linear sequence of characters.
+ Understanding the implications of this statement is the foundation for understanding all mozilla's string classes.
+
+ I have a wide string, i.e., an instance of a class derived from nsAString
+
+
I want a pointer to the characters
+
I want a narrow string
+
I want to printf it
+
+
+
+ I have a PRUnichar*
+
+
I want a wide string
+
I want a narrow string
+
I want to printf it
+
+
+
+ I have a narrow string, i.e., an instance of a class derived from nsACString
+
+
I want a pointer to the characters
+
I want a narrow string
+
I want to printf it
+
+
+
+ I have a char*
+
+
I want a wide string
+
I want a narrow string
+
+
+
+ I have a literal character sequence, e.g., "Hello, World!\n"
+
+
I want a wide string
+
I want a narrow string
+
+
+
What's the best way to return a string?
+
How can I get a pointer to the characters in a string?
+
How can I printf a string?
+
+
+
+ is there any string doc?
+
+
+ Yes, you're soaking in it!
+
+
+
+ I have a string, how to I get a pointer to the characters?
+
+
+ ...
+
+
+
+ What is the best way to return a string?
+
+
+
+ There are several reasonable ways to produce a string result from a function.
+ If you are already holding the answer as a sharable string,
+ you can simply return that string (pass-by-value).
+ Otherwise,
+ the most efficient and flexible way to return a string is
+ to assign your result into a non-const reference parameter.
+ Don't bother to create a sharable string from scratch with your generated result.
+
+
+ Why?
+ The two things you want to minimize in string manipulation are,
+ in order of importance,
+ heap allocation, and
+ moving characters around.
+
+
+
+
+
+ If I have a PRUnichar *aKey [or other representation of a wide] string,
+ what can I use (easily :)
+ to convert it
+ to a printf() printable string?
+ Just for debugging...
+
+
+ If it's just for debugging,
+ you probably wouldn't care if something odd was printed in the case of a UCS2 character that didn't have
+ an ASCII equivalent.
+ The simplest thing in this case is to make a temporary conversion using NS_ConvertUCS2toUTF8.
+ Remember not to hold onto the pointer you get out of this beyond the lifetime of temporary.
+
+
+
+
+const PRUnichar* aKey;
+
+printf("%s\n", NS_ConvertUCS2toUTF8(aKey).get()); // GOOD
+ // the simplest way to get a |printf|-able |const char*| out of a string
+
+ // works just as well with an formal wide string type...
+const nsAString& aString = ...; // perhaps it's a parameter
+printf("%s\n", NS_ConvertUCS2toUTF8(aString).get());
+
+
+ // But don't hold onto the pointer longer than the lifetime of the temporary!
+const char* cstring = NS_ConvertUCS2toUTF8(aKey).get(); // BAD!
+printf("%s\n", cstring); // |cstring| is dangling
+