Skip to main content

Visit Mozilla.org

User:Waldo/XPCOM String API Reference

From MDC


The interface given below is the one shared by all strings which inherit from the abstract classes nsAString or nsACString; all methods described below may be used on strings of either type.

This document only describes the methods of these abstract string classes; it does not describe the concrete classes which implement this interface. For details on the concrete classes which implement this interface, see the XPCOM string guide.

Contents


The string class APIs are defined in xpcom/glue/nsStringAPI.h. They have been frozen since Mozilla 1.0.

[edit] typedefs

This interface is shared by both nsAString and nsACString, but the types of the characters in these strings differ. For purposes of combining the interfaces' documentation, assume one of the following type definitions, depending upon the type of your string: 

// if using nsACString
typedef char char_type;

// if using nsAString
typedef PRUnichar char_type;

[edit] Method overview

PRUint32 BeginReading(const char_type **begin, const char_type **end = nsnull) const;
const char_type* BeginReading() const;
const char_type* EndReading() const;
char_type CharAt(PRUint32 aPos) const;

[edit] Methods

[edit] PRUint32 BeginReading(const char_type **begin, const char_type **end = nsnull) const

Returns a pointer to the start of the string in begin, a pointer to the end of the string in end (if provided), and returns the length of the string. 

PRUint32 BeginReading(const char_type **begin, const char_type **end = nsnull) const;
[edit] Parameters
begin
This pointer will point to a pointer to the beginning of this string when the method returns.
end
This pointer, if given, will point to a pointer to the beginning of this string when the method returns.
[edit] Return value

The length of this string.

[edit] const char_type* BeginReading() const

Returns a pointer to the start of this string. 

const char_type* BeginReading() const;
[edit] Return value

A pointer to the beginning of this string.

[edit] const char_type* EndReading() const

Returns a pointer to the character after the last character in this string. Note that this pointer is not guaranteed to point to '\0', in particular with some of the substring classes; it should only be used in comparisons and should not be dereferenced. 

const char_type* EndReading() const;
[edit] Return value

A pointer to the character after the last character in this string.

[edit] char_type CharAt(PRUint32 aPos) const

Returns the character at the given index in the string. The first character is at index 0, the second at index 1, etc. This method uses the NS_ASSERTION macro to check that the given index is less than the length of this string, in debug builds. 

char_type CharAt(PRUint32 aPos) const;
[edit] Parameters
aPos
The zero-indexed position in the string whose character should be returned.
[edit] Return value

The character at the given index in this string.

[edit] Remarks

XXX none needed, given that this is a reference and not tutorial information???

[edit] See also

XPCOM String Guide

Retrieved from "http://developer.mozilla.org/en/docs/User:Waldo/XPCOM_String_API_Reference"