Mozilla external string guide

  • Revision slug: Mozilla_external_string_guide
  • Revision title: Mozilla external string guide
  • Revision id: 119199
  • Created:
  • Creator: EndersTruth
  • Is current revision? No
  • Comment 145 words added

Revision Content

{{ NeedsTechnicalReview() }}

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 nsStringAPI.h and the implementation is nsStringAPI.cpp both of which are located in xpcom/glue/

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

To set a string with a literal string using the NS_LITERAL_STRING or NS_LITERAL_CSTRING macro will let you pass a literal string into the string's Assign member function.

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

However the Assign member function is meant to take in another string as it's 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.

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);

Parts of a string

Substrings

To extract parts of a string the Substring function may be used in he following fashion:

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
Return Type: Function: 1st Parameter: 2nd Parameter: 3rd Parameter:
nsAString
const nsDependentSubstring_external Substring const nsAString &str PRUint32 startPos PRUint32 length
    const PRUnichar *start const PRUnichar *end  
    const PRUnichar *start PRUint32 length  
Return Type: Function: 1st Parameter: 2nd Parameter: 3rd Parameter:
nsACString
const nsDependentCSubstring_external Substring const nsACString &str PRUint32 startPos PRUint32 length
    const char *start const char *end  
    const char *start PRUint32 length  

Head and Tail

Return Type: Function: 1st Parameter: 2nd Parameter:
const nsDependentCSubstring_external StringHead const nsACString &str PRUint32 count
  StringTail const nsACString &str PRUint32 count

Example:

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

Begins and Ends

nsAString
Return: Function: 1st Paramter: 2nd Parameter: 3rd Parameter:
PRBool StringBeginsWith const nsAString &aSource const nsAString &aSubstring nsAString::ComparatorFunc aComparator=nsAString::DefaultComparator
  StringEndsWith const nsAString &aSource const nsAString &aSubstring nsAString::ComparatorFunc aComparator=nsAString::DefaultComparator
Return: Function 1st Parameter: 2nd Parameter: 3rd Parameter:
nsACString
PRBool StringBeginsWith const nsACString &aSource const nsACString &aSubstring nsACString::ComparatorFunc aComparator=nsACString::DefaultComparator
  StringEndsWith const nsACString &aSource const nsACString &aSubstring nsACString::ComparatorFunc aComparator=nsACString::DefaultComparator

Case (Upper and Lower)

To change the case of an external string

Return Type: Function: 1st Parameter: 2nd Parameter:
PRUint32 ToLowerCase nsACString &aStr  
    const nsACString &aSrc nsACString &aDest
  ToUpperCase nsACString &aStr  
    const nsACString &aSrc nsACString &aDest

Whitespace

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

Return Type: Function: 1st Parameter:
void CompressWhitespace nsAString &aString

Unicode Conversion ns*CString vs. ns*String

UTF-8 / UTF-16 conversion

 

Classes
NS_ConvertUTF8toUTF16_external
NS_ConvertUTF16toUTF8_external

Example:

wideString = NS_ConvertUTF8toUTF16(narrowString);
Return Type: Function: 1st Parameter: 2st Parameter:
Functions
void CopyUTF16toUTF8 const nsAString &aSource nsACString &aDest
void CopyUTF8toUTF16 const nsACString &aSource nsAString &aDest
char * ToNewUTF8String const nsAString &aSource  

Lossy Conversion

UTF-16 to ASCII converters

Class
NS_LossyConvertUTF16toASCII_external

NS_LossyConvertUTF16toASCII_external has two constructors, one which takes a nsAString object as a parameter and one which accepts a character string and a PRUInt32 as the strings length. When passing in a nsAString object the NS_UTF16ToCString function is used to set the NS_LossyConvertUTF16toASCII_external's string, an ASCII string. It does this with the NS_CSTRING_ENCODING_ASCII macro. When passing a character string and length it works the same way except instead of passing the nsAString object as the first parameter to the NS_UTF16ToCString function nsDependentString(aData, aLength) is sent instead.

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
Function
 Return Type:  Function:  1st Parameter:  1st Parameter:
void LossyCopyUTF16toASCII const nsAString &aSource nsACString &aDest

ASCII to UTF-16 converters

Class
NS_ConvertASCIItoUTF16_external
 Return Type:  Function:  1st Parameter:  1st Parameter:
Function
void CopyASCIItoUTF16 const nsACString &aSource nsAString &aDest

 

Revision Source

<p>{{ NeedsTechnicalReview() }}</p>
<p>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 <a href="/En/Mozilla_internal_string_guide" title="En/Mozilla internal string guide">here</a>.</p>
<h2>Introduction</h2>
<p>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.</p>
<p>If you are in a hurry see Frozen API <a href="/en/nsAString_(External)" title="en/nsAString (External)">nsAString (External)</a> or <a href="/en/nsACString_(External)" title="en/nsACString (External)">nsACString (External)</a></p>
<p>The library header file is <a class=" external" href="http://mxr.mozilla.org/mozilla-central/source/xpcom/glue/nsStringAPI.h" title="http://mxr.mozilla.org/mozilla-central/source/xpcom/glue/nsStringAPI.h">nsStringAPI.h</a> and the implementation is <a class=" external" href="http://mxr.mozilla.org/mozilla-central/source/xpcom/glue/nsStringAPI.cpp" title="http://mxr.mozilla.org/mozilla-central/source/xpcom/glue/nsStringAPI.cpp">nsStringAPI.cpp</a> both of which are located in <a class=" external" href="http://mxr.mozilla.org/mozilla-central/source/xpcom/glue/" title="http://mxr.mozilla.org/mozilla-central/source/xpcom/glue/">xpcom/glue/</a></p>
<p>Internal linkage is not available in XULRunner 1.9 (Firefox 3). For help migrating from internal to external linkage see <a href="/en/Migrating_from_Internal_Linkage_to_Frozen_Linkage" title="en/Migrating from Internal Linkage to Frozen Linkage">Migrating from Internal Linkage to Frozen Linkage</a>.</p>
<h2>The Abstract Classes</h2>
<p>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.</p>
<h2>The Concrete Classes</h2>
<p>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.</p>
<h2>Using External Strings</h2>
<h3>Include</h3>
<p>To use External strings one would include the nsStringAPI header file in their code.</p>
<pre class="eval">#include "nsStringAPI.h"
</pre>
<h3>Declaration</h3>
<p>Type nsString will create a 16-bit "wide"  string and nsCString will create an 8-bit "narrow"  string.</p>
<p><strong>Example:</strong></p>
<pre class="eval">nsString wideString;
nsCString narrowString;
nsString myString, secondString;
</pre>
<h2>Helper Classes and Functions</h2>
<h3>Append</h3>
<p>To set a string with a literal string using the NS_LITERAL_STRING or NS_LITERAL_CSTRING macro will let you pass a literal string into the string's Assign member function.</p>
<pre class="eval">myString.Assign(NS_LITERAL_STRING("Example of a string"));</pre>
<p>However the Assign member function is meant to take in another string as it's parameter.</p>
<pre class="eval">mySecondString.Assign(myString);</pre>
<p>The above line will assign mySecondString to the contents of myString.</p>
<h3>Iteration</h3>
<p>External strings don't have iterators, however pointers may be used in a similar fashion.</p>
<pre class="eval">const PRUnichar *begin, *end;
myString.BeginReading(&amp;begin, &amp;end);
</pre>
<h3>Setting the length</h3>
<p>To change the length of a string with external strings one uses the .SetLength() method</p>
<pre class="eval">myString.SetLength(4);</pre>
<h3>Parts of a string</h3>
<h4>Substrings</h4>
<p>To extract parts of a string the Substring function may be used in he following fashion:</p>
<pre class="eval">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
</pre>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col">Return Type:</th> <th scope="col">Function:</th> <th scope="col">1st Parameter:</th> <th scope="col">2nd Parameter:</th> <th scope="col">3rd Parameter:</th> </tr> </thead> <caption>nsAString</caption> <tbody> <tr> <td>const nsDependentSubstring_external</td> <td>Substring</td> <td style="background-color: rgb(0, 255, 0);">const nsAString &amp;str</td> <td style="background-color: rgb(0, 255, 0);">PRUint32 startPos</td> <td>PRUint32 length</td> </tr> <tr> <td> </td> <td> </td> <td>const PRUnichar *start</td> <td>const PRUnichar *end</td> <td> </td> </tr> <tr> <td> </td> <td> </td> <td>const PRUnichar *start</td> <td>PRUint32 length</td> <td> </td> </tr> </tbody>
</table>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col">Return Type:</th> <th scope="col">Function:</th> <th scope="col">1st Parameter:</th> <th scope="col">2nd Parameter:</th> <th scope="col">3rd Parameter:</th> </tr> </thead> <caption>nsACString</caption> <tbody> <tr> <td>const nsDependentCSubstring_external</td> <td>Substring</td> <td style="background-color: rgb(0, 255, 0);">const nsACString &amp;str</td> <td style="background-color: rgb(0, 255, 0);">PRUint32 startPos</td> <td>PRUint32 length</td> </tr> <tr> <td> </td> <td> </td> <td>const char *start</td> <td>const char *end</td> <td> </td> </tr> <tr> <td> </td> <td> </td> <td>const char *start</td> <td>PRUint32 length</td> <td> </td> </tr> </tbody>
</table>
<h4>Head and Tail</h4>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col">Return Type:</th> <th scope="col">Function:</th> <th scope="col">1st Parameter:</th> <th scope="col">2nd Parameter:</th> </tr> </thead> <tbody> <tr> <td>const nsDependentCSubstring_external</td> <td>StringHead</td> <td>const nsACString &amp;str</td> <td>PRUint32 count</td> </tr> <tr> <td> </td> <td>StringTail</td> <td>const nsACString &amp;str</td> <td>PRUint32 count</td> </tr> </tbody>
</table>
<p><strong>Example:</strong></p>
<pre class="eval">nsString buffer = someString;
const nsDependentSubstring prefix = StringHead(buffer, 4);
</pre>
<h4>Begins and Ends</h4>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <caption>nsAString</caption> <thead> <tr> <th scope="col">Return:</th> <th scope="col">Function:</th> <th scope="col">1st Paramter:</th> <th scope="col">2nd Parameter:</th> <th scope="col">3rd Parameter:</th> </tr> </thead> <tbody> <tr> <td>PRBool</td> <td>StringBeginsWith</td> <td>const nsAString &amp;aSource</td> <td>const nsAString &amp;aSubstring</td> <td>nsAString::ComparatorFunc aComparator=nsAString::DefaultComparator</td> </tr> <tr> <td> </td> <td>StringEndsWith</td> <td>const nsAString &amp;aSource</td> <td>const nsAString &amp;aSubstring</td> <td>nsAString::ComparatorFunc aComparator=nsAString::DefaultComparator</td> </tr> </tbody>
</table>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col">Return:</th> <th scope="col">Function</th> <th scope="col">1st Parameter:</th> <th scope="col">2nd Parameter:</th> <th scope="col">3rd Parameter:</th> </tr> </thead> <caption>nsACString</caption> <tbody> <tr> <td>PRBool</td> <td>StringBeginsWith</td> <td>const nsACString &amp;aSource</td> <td>const nsACString &amp;aSubstring</td> <td>nsACString::ComparatorFunc aComparator=nsACString::DefaultComparator</td> </tr> <tr> <td> </td> <td>StringEndsWith</td> <td>const nsACString &amp;aSource</td> <td>const nsACString &amp;aSubstring</td> <td>nsACString::ComparatorFunc aComparator=nsACString::DefaultComparator</td> </tr> </tbody>
</table>
<h3>Case (Upper and Lower)</h3>
<p>To change the case of an external string</p>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col">Return Type:</th> <th scope="col">Function:</th> <th scope="col">1st Parameter:</th> <th scope="col">2nd Parameter:</th> </tr> </thead> <tbody> <tr> <td>PRUint32</td> <td>ToLowerCase</td> <td>nsACString &amp;aStr</td> <td> </td> </tr> <tr> <td> </td> <td> </td> <td>const nsACString &amp;aSrc</td> <td>nsACString &amp;aDest</td> </tr> <tr> <td> </td> <td>ToUpperCase</td> <td>nsACString &amp;aStr</td> <td> </td> </tr> <tr> <td> </td> <td> </td> <td>const nsACString &amp;aSrc</td> <td>nsACString &amp;aDest</td> </tr> </tbody>
</table>
<h3>Whitespace</h3>
<p>The CompressWhitespace function may be used to trim the white space from the first and last positions of the string then change every block of continuous whitespcae in the string to a single space.</p>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col">Return Type:</th> <th scope="col">Function:</th> <th scope="col">1st Parameter:</th> </tr> </thead> <tbody> <tr> <td>void</td> <td>CompressWhitespace</td> <td>nsAString &amp;aString</td> </tr> </tbody>
</table>
<h2>Unicode Conversion ns*CString vs. ns*String</h2>
<h3>UTF-8 / UTF-16 conversion</h3>
<p> </p>
<table border="1" cellpadding="1" cellspacing="1" style="width: 0%;"> <caption>Classes</caption> <tbody> <tr> <td>NS_ConvertUTF8toUTF16_external</td> </tr> <tr> <td>NS_ConvertUTF16toUTF8_external</td> </tr> </tbody>
</table>
<p><strong>Example:</strong></p>
<pre class="eval">wideString = NS_ConvertUTF8toUTF16(narrowString);</pre>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col">Return Type:</th> <th scope="col">Function:</th> <th scope="col">1st Parameter:</th> <th scope="col">2st Parameter:</th> </tr> </thead> <caption>Functions</caption> <tbody> <tr> <td>void</td> <td>CopyUTF16toUTF8</td> <td>const nsAString &amp;aSource</td> <td>nsACString &amp;aDest</td> </tr> <tr> <td>void</td> <td>CopyUTF8toUTF16</td> <td>const nsACString &amp;aSource</td> <td>nsAString &amp;aDest</td> </tr> <tr> <td>char *</td> <td>ToNewUTF8String</td> <td>const nsAString &amp;aSource</td> <td> </td> </tr> </tbody>
</table>
<h3>Lossy Conversion</h3>
<h4>UTF-16 to ASCII converters</h4>
<table border="1" cellpadding="1" cellspacing="0" style="width: 0%;"> <caption>Class</caption> <tbody> <tr> <td>NS_LossyConvertUTF16toASCII_external</td> </tr> </tbody>
</table>
<p>NS_LossyConvertUTF16toASCII_external has two constructors, one which takes a nsAString object as a parameter and one which accepts a character string and a PRUInt32 as the strings length. When passing in a nsAString object the NS_UTF16ToCString function is used to set the NS_LossyConvertUTF16toASCII_external's string, an ASCII string. It does this with the NS_CSTRING_ENCODING_ASCII macro. When passing a character string and length it works the same way except instead of passing the nsAString object as the first parameter to the NS_UTF16ToCString function nsDependentString(aData, aLength) is sent instead.</p>
<pre class="eval">nsAString myString = "Test string";

//<code>const nsAString&amp;</code>
NS_LossyConvertUTF16toASCII_external convertString(myString);

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

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

printf("%s", convertString);

//...is called
</pre>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <caption>Function</caption> <tbody> <tr> <td> Return Type:</td> <td> Function:</td> <td> 1st Parameter:</td> <td> 1st Parameter:</td> </tr> <tr> <td>void</td> <td>LossyCopyUTF16toASCII</td> <td>const nsAString &amp;aSource</td> <td>nsACString &amp;aDest</td> </tr> </tbody>
</table>
<h4>ASCII to UTF-16 converters</h4>
<table border="1" cellpadding="1" cellspacing="0" style="width: 0%;"> <caption>Class</caption> <tbody> <tr> <td>NS_ConvertASCIItoUTF16_external</td> </tr> </tbody>
</table>
<table border="1" cellpadding="1" cellspacing="0" style="width: 100%;"> <thead> <tr> <th scope="col"> Return Type:</th> <th scope="col"> Function:</th> <th scope="col"> 1st Parameter:</th> <th scope="col"> 1st Parameter:</th> </tr> </thead> <caption>Function</caption> <tbody> <tr> <td>void</td> <td>CopyASCIItoUTF16</td> <td>const nsACString &amp;aSource</td> <td>nsAString &amp;aDest</td> </tr> </tbody>
</table>
<p> </p>
Revert to this revision