From cc8d69912ea7c7aac161476e75ee5eb3ebf84c43 Mon Sep 17 00:00:00 2001 From: "scc%mozilla.org" Date: Thu, 12 Apr 2001 00:33:13 +0000 Subject: [PATCH] this file is documentation only; it will never be part of the build. more initial content git-svn-id: svn://10.0.0.236/trunk@92038 18797224-902f-48f8-a5cc-f745e15eee43 --- mozilla/string/doc/string-guide.html | 166 ++++++++++++++++++++- mozilla/xpcom/string/doc/string-guide.html | 166 ++++++++++++++++++++- 2 files changed, 322 insertions(+), 10 deletions(-) diff --git a/mozilla/string/doc/string-guide.html b/mozilla/string/doc/string-guide.html index 821a1791a03..e02812ce9a9 100644 --- a/mozilla/string/doc/string-guide.html +++ b/mozilla/string/doc/string-guide.html @@ -2,7 +2,8 @@ the complete guide to mozilla/string - + + @@ -66,21 +67,26 @@

introduction

-

what is a string?

+

what and what isn't a string?

+

+ 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. +

+

readable and writable

promises

flat strings

encoding

sharing

-

using the string classes right; using the right string class

+

using the string classes correctly; using the correct string class

basic string operations

comparison

concatenation

@@ -136,10 +142,160 @@
+
+
+
+ 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 @@

introduction

-

what is a string?

+

what and what isn't a string?

+

+ 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. +

+

readable and writable

promises

flat strings

encoding

sharing

-

using the string classes right; using the right string class

+

using the string classes correctly; using the correct string class

basic string operations

comparison

concatenation

@@ -136,10 +142,160 @@
+
+
+
+ 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
+
+
+
+ +
+
+ +