mozilla
Your Search Results

    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: charron12, EndersTruth, kscarfone
    Last updated by: kscarfone,