Mozilla external string guide

This article is in need of a technical review.

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.

Abstract Classes
Wide Narrow
nsAString nsACString

Note: An asterisk (*) is used in classes and types where the information being presented applies to both wide and narrow strings. (e.g., nsA*String refers to both nsAString and nsACString, nsDependent*Substring refers to both nsDependentSubstring and nsDependentCSubstring) However, methods will use either wide or narrow exclusively unless noted otherwise (i.e. If nsAString is used in one parameter or as the return type of a function, all instances of nsA*String in the prototype will represent nsAString).

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.

Concrete Classes
Wide Narrow
nsString nsCString

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.

Return Type Method Name 1st Parameter 2nd Parameter
PRBool Equals const PRUnichar* aStr ComparatorFunc c
PRBool Equals const nsAString& aStr ComparatorFunc c

Other functions which use comparator functions are:

Compare
Find
RFind
Comparator Functions:
CaseInsensitiveCompare

Example:

nsString myString = someString;

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

Finding Text Within Strings

Return Type Method Name 1st Parameter 2nd Parameter
PRInt32 Find const nsAString& aStr ComparatorFunc c
  • Find the first occurrence of aStr in this string.
Return Type Method Name 1st Parameter 2st Parameter 3nd Parameter
PRInt32 Find const nsAString& aStr PRUint32 aOffset ComparatorFunc c
  • Find the first occurrence of aStr in this string, beginning at aOffset.
Return Type Method Name 1st Parameter 2st Parameter
PRInt32 Find const char* aStr PRBool aIgnoreCaset
  • Find an ASCII string within this string.
Return Type Method Name 1st Parameter 2st Parameter 3st Parameter
PRInt32 Find const char* aStr PRUint32 aOffset PRBool aIgnoreCaset
  • 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.

Return Type Method Name 1st Parameter
PRInt32 FindChar PRUnichar
  • 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.

Substring Helper Classes
nsDependentSubstring
nsDependentCSubstring
nsAString
Return Type Method Name 1st Parameter 2nd Parameter 3rd Parameter
const nsDependentSubstring_external Substring const nsAString &str PRUint32 startPos PRUint32 length
    const PRUnichar *start const PRUnichar *end  
    const PRUnichar *start PRUint32 length  
nsACString
Return Type Method Name 1st Parameter 2nd Parameter 3rd Parameter
const nsDependentCSubstring_external Substring const nsACString &str PRUint32 startPos PRUint32 length
    const char *start const char *end  
    const char *start PRUint32 length  

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.

Return Type Method Name 1st Parameter 2nd Parameter
const nsDependent*Substring_external StringHead const nsA*String &str PRUint32 count
  StringTail const nsA*String &str PRUint32 count

Example:

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

Begins and Ends

Return Type Method Name 1st Parameter 2nd Parameter 3rd Parameter
PRBool StringBeginsWith const nsA*String &aSource const nsA*String &aSubstring nsA*String::ComparatorFunc aComparator=nsAString::DefaultComparator
  StringEndsWith const nsA*String &aSource const nsA*String &aSubstring nsA*String::ComparatorFunc aComparator=nsAString::DefaultComparator

Case (Upper and Lower)

To change the case of an external string

Return Type Method Name 1st Parameter 2nd Parameter
PRUint32 ToLowerCase nsA*String &aStr  
    const nsA*String &aSrc nsA*String &aDest
  ToUpperCase nsA*String &aStr  
    const nsA*String &aSrc nsA*String &aDest

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.

Return Type Method Name 1st Parameter
void CompressWhitespace nsA*String &aString

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.

Classes
Class Name Inherits From
NS_ConvertUTF8toUTF16 nsString
NS_ConvertUTF16toUTF8 nsCString
NS_ConvertASCIItoUTF16 nsString
NS_ConvertUTF16toASCII nsCString

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

Classes
NS_ConvertUTF8toUTF16_external
NS_LossyConvertASCIItoUTF16_external
Methods
Return Type method Name 1st Parameter 2nd Parameter
void CopyUTF8toUTF16 const nsACString &aSource nsAString &aDest

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.

Classes
NS_LossyConvertUTF16toASCII_external
NS_ConvertUTF16toUTF8_external
Methods
Return Type Method Name 1st Parameter 2nd Parameter
char * ToNewUTF8String const nsAString &aSource  
void CopyUTF16toUTF8 const nsAString &aSource nsACString &aDest
void LossyCopyUTF16toASCII const nsAString &aSource nsACString &aDest

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

Document Tags and Contributors

Contributors to this page: kscarfone, EndersTruth, charron12
Last updated by: kscarfone,