From 0ec97778ccfb142044bc41eb9079bc4de266fe01 Mon Sep 17 00:00:00 2001 From: "scc%mozilla.org" Date: Fri, 13 Apr 2001 18:03:33 +0000 Subject: [PATCH] [documentation], _never_ part of a build. Checking in as I add more FAQs --- string/doc/string-guide.html | 126 +++++++++++++++++------------ xpcom/string/doc/string-guide.html | 126 +++++++++++++++++------------ 2 files changed, 146 insertions(+), 106 deletions(-) diff --git a/string/doc/string-guide.html b/string/doc/string-guide.html index dcf02dc3c3a..6d0d25831b1 100644 --- a/string/doc/string-guide.html +++ b/string/doc/string-guide.html @@ -205,59 +205,48 @@ char - - - - + . [] [] - how to extract a character + extract a character PRUnichar PRUnichar('x') PRUnichar(c) - - - + convert encoding, extract a character char* - - - - - how to get a pointer + & + & + & + . + get a pointer PRUnichar* - - - - - + convert encoding, get a pointer nsACString - - - - - + NS_LITERAL_CSTRING("x") + make a string + NS_LITERAL_CSTRING("foo") + make a string + . nsAString - - - - - + NS_LITERAL_STRING("x") + convert encoding + NS_LITERAL_STRING("foo") + convert encoding to call printf - - - - - + . + call printf @@ -281,8 +270,8 @@ PRUnichar - - + [] + extract a character char* @@ -292,9 +281,9 @@ PRUnichar* - + & - + get a pointer nsACString @@ -306,13 +295,13 @@ nsAString - how to get a pointer + to call printf - + call printf @@ -409,6 +398,8 @@ void func( const nsAString& aString, const nsACString& aCString ) 
+  /* How do I get a particular character out of a string? */
+
 PRUnichar Get5thCharacterOf( const nsAString& aString )
   {
     if ( aString.Length() >= 5 )
@@ -424,9 +415,30 @@ PRUnichar Get5thCharacterOf( const nsAString& aString )
+
+ Using iterators isn't as bad as the example above makes it feel. + The typical use is for advancing through a string, examining many characters. +
+ +
+ How do I convert from one encoding to another? +
+
+
+ + + + +
+ How do I create a string? +
+
+
+ +
What is the best way to return a string? @@ -486,35 +498,43 @@ foo::GetShortName( nsAString& aResult ) const
- 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... + How do I printf a string, e.g., for debugging.
+ If your string is already narrow, you just have to worry about making it flat, and then getting a pointer. +
+
+ If your string happens to be wide, + you'll need to convert it before you can printf something reasonable. 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. + The result is conveniently flat already, so getting the pointer is simple. 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());
+  /* How do I |printf| a string? */
 
 
-  // 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
+void PrintSomeStrings( const nsAString& aString, const PRUnichar* aKey, const nsACString& aCString )
+  {
+      // |printf|ing a narrow string is easy
+    printf("%s\n", PromiseFlatCString(aCString).get());     // GOOD
+
+      // the simplest way to get a |printf|-able |const char*| out of a string
+    printf("%s\n", NS_ConvertUCS2toUTF8(aKey).get());       // GOOD
+
+      // works just as well with an formal wide string type...
+    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! |cstring| is dangling
+    printf("%s\n", cstring);
+  }
diff --git a/xpcom/string/doc/string-guide.html b/xpcom/string/doc/string-guide.html index dcf02dc3c3a..6d0d25831b1 100644 --- a/xpcom/string/doc/string-guide.html +++ b/xpcom/string/doc/string-guide.html @@ -205,59 +205,48 @@ char - - - - + . [] [] - how to extract a character + extract a character PRUnichar PRUnichar('x') PRUnichar(c) - - - + convert encoding, extract a character char* - - - - - how to get a pointer + & + & + & + . + get a pointer PRUnichar* - - - - - + convert encoding, get a pointer nsACString - - - - - + NS_LITERAL_CSTRING("x") + make a string + NS_LITERAL_CSTRING("foo") + make a string + . nsAString - - - - - + NS_LITERAL_STRING("x") + convert encoding + NS_LITERAL_STRING("foo") + convert encoding to call printf - - - - - + . + call printf @@ -281,8 +270,8 @@ PRUnichar - - + [] + extract a character char* @@ -292,9 +281,9 @@ PRUnichar* - + & - + get a pointer nsACString @@ -306,13 +295,13 @@ nsAString - how to get a pointer + to call printf - + call printf @@ -409,6 +398,8 @@ void func( const nsAString& aString, const nsACString& aCString ) 
+  /* How do I get a particular character out of a string? */
+
 PRUnichar Get5thCharacterOf( const nsAString& aString )
   {
     if ( aString.Length() >= 5 )
@@ -424,9 +415,30 @@ PRUnichar Get5thCharacterOf( const nsAString& aString )
+
+ Using iterators isn't as bad as the example above makes it feel. + The typical use is for advancing through a string, examining many characters. +
+ +
+ How do I convert from one encoding to another? +
+
+
+ + + + +
+ How do I create a string? +
+
+
+ +
What is the best way to return a string? @@ -486,35 +498,43 @@ foo::GetShortName( nsAString& aResult ) const
- 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... + How do I printf a string, e.g., for debugging.
+ If your string is already narrow, you just have to worry about making it flat, and then getting a pointer. +
+
+ If your string happens to be wide, + you'll need to convert it before you can printf something reasonable. 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. + The result is conveniently flat already, so getting the pointer is simple. 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());
+  /* How do I |printf| a string? */
 
 
-  // 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
+void PrintSomeStrings( const nsAString& aString, const PRUnichar* aKey, const nsACString& aCString )
+  {
+      // |printf|ing a narrow string is easy
+    printf("%s\n", PromiseFlatCString(aCString).get());     // GOOD
+
+      // the simplest way to get a |printf|-able |const char*| out of a string
+    printf("%s\n", NS_ConvertUCS2toUTF8(aKey).get());       // GOOD
+
+      // works just as well with an formal wide string type...
+    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! |cstring| is dangling
+    printf("%s\n", cstring);
+  }