Mozilla String Handling
Mozilla used to have a wide range of string classes, which didn't provide a stable ABI. In mozilla 1.7 them implemented a couple of classes called nsEmbedString and nsEmbedCString. These are thin wrappers around a C like interface to provide a stable API/ABI. These interfaces are frozen.
In mozilla 1.8 there are more thin wrappers around the stable API to provide compatibility with the internal string classes (things like nsAutoString, nsDependentSubstring and NS_ConvertUTF16toUTF8). Unfortunately we can't use these as Galeon only supports mozilla 1.7.
Although the nsEmbedString API provides us with a useable interface, there is no easy way to convert from UTF16 <-> UTF8. To make it easy to perform the conversion, and provide a consistent and simple API, Galeon has a few string classes of its own that are compatible with the mozilla classes:
- GulString - A container for UTF16 strings (wrapper around nsEmbedString)
- GulCString - A container for UTF8 strings (wrapper around nsEmbedCString)
- GulDependantString - Wrap a string object around a const PRUnichar*
- GulDependantCString - Wrap a string object around a const char*
GulString and GulCString perform automatic conversion from UTF8 and UTF16 repsectively. They also provide some convenience functions that aren't available in the nsEmbedString API (such as IsEmpty() and Equals()).
The GulDependantString classes just wrap their argument in a string object, so that they can be passed to functions that expect an nsAString (or nsACString) input.
NS_LITERAL_STRING() wraps a literal (i.e. double quoted string) in a mozilla string class, it might be implemented as GulString or a proper mozilla class depending on the version of mozilla being compiled against, either way, you should NOT use variables inside the macro.
Summmary
| If you used to use this | Use this instead  | Description |
|---|
| nsXPIDLString | PRUnichar* / nsMemory::Free | You need to do this manually now |
| NS_LITERAL_STRING | NS_LITERAL_STRING | Wrapper around a literal string |
| nsAutoString | GulString | Container for a UTF16 string |
| NS_ConvertUTF8toUCS2 | GulString | Convert from UTF8 to UTF16, this is now done automatically |
| nsDependentString | GulDependentString | Wrapper around a const PRUnichar* |
| nsDependentCString | GulDependentCString | Wrapper around a const char * |
| nsCAutoString | GulCString | Container for a UTF8 string |
| NS_ConvertUCS2toUTF8 | GulCString | Convert from UTF16 to UTF8, this is now done automatically |
