diff --git a/mozilla/string/doc/string-guide.html b/mozilla/string/doc/string-guide.html index 99e3395205a..dcf02dc3c3a 100644 --- a/mozilla/string/doc/string-guide.html +++ b/mozilla/string/doc/string-guide.html @@ -5,7 +5,6 @@ - @@ -144,6 +143,7 @@
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
you have some chars
you want'x'char c"foo"char* cpnsACString& cs
char - - [] [] how to extract a character
PRUnichar PRUnichar('x') PRUnichar(c)
char* how to get a pointer
PRUnichar*
nsACString
nsAString
to call printf
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
you have some PRUnichars
you wantPRUnichar wPRUnichar* wpnsAString& s
char
PRUnichar
char*
PRUnichar*
nsACString
nsAString how to get a pointer
to call printf
+
@@ -197,13 +325,109 @@ Yes, you're soaking in it! + + +
- I have a string, how to I get a pointer to the characters? + I have a string, how do I get a pointer to the characters?
- ... + You want to avoid this situation. + In your own interfaces, prefer string types over raw pointers. + Any interface that wants to process a string using a single pointer is making two expensive assumptions. + First, that the string is stored in one contiguous hunk; and + second, that the string is zero-terminated. + If this isn't the case, + then to get a pointer, storage must be allocated and the entire string must be copied to it and zero-terminated. + You may not be able to avoid needing a pointer when interacting with system calls. +
+
+ Some string classes guarantee that they are `flat'. + That is, that their data is stored in one contiguous zero-terminated hunk. + This does not imply that there are no embedded nulls. Caveat emptor. + All strings that explicitly promise flatness + inherit from the class nsAFlatString + or nsAFlatCString + and can produce a constant pointer to their data with the get() member function. + Even strings that don't explicitly promise to be flat + may happen to be flat. + The helper function PromiseFlatString will produce + a const dependent string that is guaranteed to be flat. + If you use this on a string that already happens to be flat, + the result is simply a reference through to that string. + Otherwise, + PromiseFlatString does the work to allocate, copy, terminate, and manage + a temporary flat string. + Since the result of PromiseFlatString is a temporary, + you must be careful not to get and hold a pointer to it's data for longer than the temporary itself lives. +
+
+
+
+  /* I have a string, how do I get a pointer to the characters? */
+
+extern void EvilNarrowOSFunction( const char* );    // evil OS routines that want a pointers
+extern void EvilWideOSFunction( const PRUnichar* );
+
+void func( const nsAString& aString, const nsACString& aCString )
+  {
+    EvilWideOSFunction( NS_LITERAL_STRING("Hello, World!").get() );
+      // literal strings are flat already (as are |nsString|s, et al), just use |.get()|
+
+    EvilWideOSFunction( PromiseFlatString(aString).get() );
+      // for strings that don't explicitly guarantee flatness, use |PromiseFlatString|
+
+
+      // beware holding the pointer for longer than the life of the promise
+    const PRUnichar* wp = PromiseFlatString(aString).get(); // BAD! |wp| dangles
+    EvilWideOSFunction(wp);
+
+      // if you really need to use the pointer from |PromiseFlatString| in more than one expression...
+    const nsAFlatString& flat = PromiseFlatString(aString);
+    EvilWideOSFunction(flat.get());
+    SomeOtherFunction(flat.get());
+
+      // similarly for |char| strings
+    EvilNarrowOSFunction( PromiseFlatCString(aCString).get() );
+  }
+
+
+ + + +
+ How do I get a particular character out of a string? +
+
+ Flat strings provide operator[] and CharAt(). + All strings provide First(), Last(), and access with iterators. + Don't promise a string flat just to do character indexing. + Prefer, instead, to get an iterator and advance it to the position you care about. +
+
+
+
+PRUnichar Get5thCharacterOf( const nsAString& aString )
+  {
+    if ( aString.Length() >= 5 )
+      {
+        nsAString::const_iterator iter;
+        aString.BeginReading(iter); // make |iter| point to the beginning of |aString|
+        iter.advance(5);
+        return *iter;
+      }
+
+    return PRUnichar(0);
+  }
+
+
+
+ + + +
What is the best way to return a string?
@@ -225,26 +449,27 @@ moving characters around.

- +
If I have a PRUnichar *aKey [or other representation of a wide] string, diff --git a/mozilla/xpcom/string/doc/string-guide.html b/mozilla/xpcom/string/doc/string-guide.html index 99e3395205a..dcf02dc3c3a 100644 --- a/mozilla/xpcom/string/doc/string-guide.html +++ b/mozilla/xpcom/string/doc/string-guide.html @@ -5,7 +5,6 @@ - @@ -144,6 +143,7 @@
    +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
you have some chars
you want'x'char c"foo"char* cpnsACString& cs
char - - [] [] how to extract a character
PRUnichar PRUnichar('x') PRUnichar(c)
char* how to get a pointer
PRUnichar*
nsACString
nsAString
to call printf
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
you have some PRUnichars
you wantPRUnichar wPRUnichar* wpnsAString& s
char
PRUnichar
char*
PRUnichar*
nsACString
nsAString how to get a pointer
to call printf
+
@@ -197,13 +325,109 @@ Yes, you're soaking in it! + + +
- I have a string, how to I get a pointer to the characters? + I have a string, how do I get a pointer to the characters?
- ... + You want to avoid this situation. + In your own interfaces, prefer string types over raw pointers. + Any interface that wants to process a string using a single pointer is making two expensive assumptions. + First, that the string is stored in one contiguous hunk; and + second, that the string is zero-terminated. + If this isn't the case, + then to get a pointer, storage must be allocated and the entire string must be copied to it and zero-terminated. + You may not be able to avoid needing a pointer when interacting with system calls. +
+
+ Some string classes guarantee that they are `flat'. + That is, that their data is stored in one contiguous zero-terminated hunk. + This does not imply that there are no embedded nulls. Caveat emptor. + All strings that explicitly promise flatness + inherit from the class nsAFlatString + or nsAFlatCString + and can produce a constant pointer to their data with the get() member function. + Even strings that don't explicitly promise to be flat + may happen to be flat. + The helper function PromiseFlatString will produce + a const dependent string that is guaranteed to be flat. + If you use this on a string that already happens to be flat, + the result is simply a reference through to that string. + Otherwise, + PromiseFlatString does the work to allocate, copy, terminate, and manage + a temporary flat string. + Since the result of PromiseFlatString is a temporary, + you must be careful not to get and hold a pointer to it's data for longer than the temporary itself lives. +
+
+
+
+  /* I have a string, how do I get a pointer to the characters? */
+
+extern void EvilNarrowOSFunction( const char* );    // evil OS routines that want a pointers
+extern void EvilWideOSFunction( const PRUnichar* );
+
+void func( const nsAString& aString, const nsACString& aCString )
+  {
+    EvilWideOSFunction( NS_LITERAL_STRING("Hello, World!").get() );
+      // literal strings are flat already (as are |nsString|s, et al), just use |.get()|
+
+    EvilWideOSFunction( PromiseFlatString(aString).get() );
+      // for strings that don't explicitly guarantee flatness, use |PromiseFlatString|
+
+
+      // beware holding the pointer for longer than the life of the promise
+    const PRUnichar* wp = PromiseFlatString(aString).get(); // BAD! |wp| dangles
+    EvilWideOSFunction(wp);
+
+      // if you really need to use the pointer from |PromiseFlatString| in more than one expression...
+    const nsAFlatString& flat = PromiseFlatString(aString);
+    EvilWideOSFunction(flat.get());
+    SomeOtherFunction(flat.get());
+
+      // similarly for |char| strings
+    EvilNarrowOSFunction( PromiseFlatCString(aCString).get() );
+  }
+
+
+ + + +
+ How do I get a particular character out of a string? +
+
+ Flat strings provide operator[] and CharAt(). + All strings provide First(), Last(), and access with iterators. + Don't promise a string flat just to do character indexing. + Prefer, instead, to get an iterator and advance it to the position you care about. +
+
+
+
+PRUnichar Get5thCharacterOf( const nsAString& aString )
+  {
+    if ( aString.Length() >= 5 )
+      {
+        nsAString::const_iterator iter;
+        aString.BeginReading(iter); // make |iter| point to the beginning of |aString|
+        iter.advance(5);
+        return *iter;
+      }
+
+    return PRUnichar(0);
+  }
+
+
+
+ + + +
What is the best way to return a string?
@@ -225,26 +449,27 @@ moving characters around.

- +
If I have a PRUnichar *aKey [or other representation of a wide] string,