Mozilla external string guide

This page has been flagged by editors or users as needing technical review. Until it is fully reviewed, it may contain inaccurate or incorrect information.

This guide documents the string classes which are visible to code outside of the Mozilla codebase (Extensions, XULRunner applications, and embedders). Code for the Mozilla codebase (code which is linked into libxul) should use internal strings, documented here.

Introduction

External strings are part of the frozen API which maintains compatibility between the different versions of XPCOM. This is important because Extensions, XULRunner applications, and embedders are maintained outside any central location. If the external string API were to change, it could break them and each developer would have to correct their code independently.

If you are in a hurry, see Frozen API nsAString (External) or nsACString (External).

The library header file is /xpcom/glue/nsStringAPI.h and the implementation is /xpcom/glue/nsStringAPI.cpp.

Internal linkage is not available in XULRunner 1.9 (Firefox 3). For help migrating from internal to external linkage, see Migrating from Internal Linkage to Frozen Linkage.

The Abstract Classes

nsAString for wide characters and nsACString for narrow characters are the base for which other abstract classes as well as concrete classes are derived. They describe strings, much like an interface.

The Concrete Classes

The concrete classes are implementations of the abstract classes mentioned above. There are the classes you can use to make the string objects in your code, and they are: nsString (nsString_external) for 16-bit wide characters, nsCString (nsCString_external) for 8-bit narrow characters, and nsAutoString.

Using External Strings

Include

To use External strings one would include the nsStringAPI header file in their code.

#include "nsStringAPI.h"

Declaration

Type nsString will create a 16-bit "wide" string and nsCString will create an 8-bit "narrow" string.

Example:

nsString wideString;
nsCString narrowString;
nsString myString, secondString;

Helper Classes and Functions

Append

Setting a string with a literal string using the NS_LITERAL_STRING or NS_LITERAL_*STRING macro will let you pass a literal string into the string's Assign method. Also note that NS_LITERAL_*STRING("") may have to be used instead of Empty*String.

Examples:

myString.Assign(NS_LITERAL_STRING("Example of a string"));

However, the Assign method is meant to take in another string as its parameter.

mySecondString.Assign(myString);

The above line will assign mySecondString to the contents of myString.

Iteration

External strings don't have iterators; however, pointers may be used in a similar fashion.

Example:

const PRUnichar *begin, *end;
myString.BeginReading(&begin, &end);

Setting the length

To change the length of a string with external strings, one uses the .SetLength() method.

myString.SetLength(4);

Comparison

External strings use comparator functions (unlike internal strings which use virtual comparator classes.) For example the "Equals" method takes the string you are comparing the current string to as the first parameter, and takes a type "ComparatorFunc" as  the second parameter.

Other functions which use comparator functions are:

Example:

nsString myString = someString;

if (myString.Equals(otherString, CaseInsensitiveCompare))
    return NS_OK;

Finding Text Within Strings

• Find the first occurrence of aStr in this string.

• Find the first occurrence of aStr in this string, beginning at aOffset.

• Find an ASCII string within this string.

• Find the first occurrence of aStr in this string, beginning at aOffset.

Example:

PRInt32 value1, value2;
nsString myString = someString("ABC", 3);

value1 = someString.Find(NS_LITERAL_STRING("bc"), CaseInsensitiveCompare);
value2 = someString.Find("bc", 0);

Value1 and Value2 are the same.

• Search for the offset of the last occurrence of a character in a string.

Example:

PRInt32 value1, value2;
nsString myString = someString("ABBC", 3);

value1 = someString.FindChar("b");
value2 = someString.RFindChar("b");

Value1 will be "2" and Value2 will be "3".

All of the above "Find" methods have corresponding "RFind" methods which find the last occurrence of aStr in this string. The Find methods will also all return the offset of aStr, or -1 if it is not found within this string.

Substrings

Substrings (nsDependent*Substring) use NS_*StringContainerInit, when creating an empty nsDependent*Substring or NS_*StringContainerInit2 when created with parameters. The Substring methods return an nsDependent*Substring created with the data passed in.

Example:

const nsDependentSubstring subPart = Stringstring(myString, 4); //From myString, subPart is the fourth character to the end of the string
//or
const nsDependentSubstring subPart = Stringstring(myString, 5, 3); //From myString, subPart is the fifth character and the three characters past

Head and Tail

StringHead and StringTail make and return an nsDependent*Substring either from the first character to count, with StringHead, or from the string's length minus count then count on, as with StringTail.

Example:

nsString buffer = someString;
const nsDependentSubstring prefix = StringHead(buffer, 4);

Begins and Ends

Case (Upper and Lower)

To change the case of an external string

Whitespace

The CompressWhitespace method may be used to trim the white space from the first and last positions of the string, then change every block of continuous white space in the string to a single space.

Unicode Conversion ns*CString vs. ns*String

The conversion classes are classes which inherit from the class, or type, you are converting to but have constructors which accept the type you are converting from.

* to UTF-16 conversion

NS_ConvertUTF8toUTF16_external and NS_ConvertASCIItoUTF16_external have two constructors: one which accepts a nsACString, and a second which takes a character string (char*) and a string length of type PRUint32. With the second constructor mentioned the length (second parameter) has a default of PR_UNIT32_MAX if it is not specified.

Both constructors use the NS_CStringToUTF16 method to set itself to the string passed in. Depending upon which type you are converting to (UTF8 or ASCII) NS_CSTRING_ENCODING_UTF8 or NS_CSTRING_ENCODING_ASCII will be set when doing this, however the constructor which takes a nsACString passes the string directly to the NS_CStringToUTF16 method while the second passes a nsDependentCString created using the character string and length specified.

Example:

wideString = NS_ConvertUTF8toUTF16(narrowString);

* to UTF-8 or ASCII Conversion

NS_ConvertUTF16toUTF8_external and NS_ConvertUTF16toASCII_external have two constructors: one which accepts a nsAString, and a second which takes a PRUnichar* and a string length of type PRUint32. With the second constructor mentioned the length (second parameter) has a default of PR_UNIT32_MAX if it is not specified.

Both constructors use the NS_UTF16ToCString method to set itself to the string passed in. Depending upon which type you are converting to (UTF8 or ASCII) NS_CSTRING_ENCODING_UTF8 or NS_CSTRING_ENCODING_ASCII will be set when doing this, however the constructor which takes a nsAString passes the string directly to the NS_UTF16ToCString method while the second passes a nsDependentString created using the character string and length specified.

Example:

nsAString myString = "Test string";

//const nsAString&
NS_LossyConvertUTF16toASCII_external convertString(myString);

//And
//const PRUnichar*, PRUint32
NS_LossyConvertUTF16toASCII_external convertString("Test string", 11);

//...will have the same result when...

printf("%s", convertString);

//...is called