nsString

In This Article

This is the canonical null-terminated string class.  All subclasses
promise null-terminated storage.  Instances of this class allocate
strings on the heap.
NAMES:
nsString for wide characters
nsCString for narrow characters
This class is also known as nsAFlat[C]String, where "flat" is used
to denote a null-terminated string.

Method Overview

Constructors

operator=

get

Find

RFind

ToFloat

Mid

Left

Right

Trim

Data

Length

IsEmpty

IsVoid

IsTerminated

CharAt

operator[]

First

Last

CountChar

FindChar

Equals

EqualsASCII

EqualsLiteral(const char

EqualsLiteral(char

LowerCaseEqualsASCII

LowerCaseEqualsLiteral(const char

LowerCaseEqualsLiteral(char

Assign

AssignASCII

AssignLiteral(const char

AssignLiteral(char

Adopt

Replace

ReplaceASCII

Append

AppendASCII

AppendLiteral(const char

AppendLiteral(char

operator+=

Insert

Cut

GetData

Base Classes

nsAString_internal

Data Members

No public members.

Methods

Constructors

void nsString() - source

constructors

void nsString(PRUnichar) - source

Parameters

PRUnichar c

void nsString(const PRUnichar*, PRUint32) - source

Parameters

PRUnichar* data
PRUint32 length

void nsString(const nsString&) - source

Parameters

nsString& str

void nsString(const nsSubstringTuple&) - source

Parameters

nsSubstringTuple& tuple

void nsString(const nsAString_internal&) - source

Parameters

nsAString_internal& readable

operator=

nsString& operator=(const nsString&) - source

Parameters

nsString& str

nsAString_internal& operator=(PRUnichar) - source

Parameters

PRUnichar c

nsAString_internal& operator=(const PRUnichar*) - source

Parameters

PRUnichar* data

nsAString_internal& operator=(const nsAString_internal&) - source

Parameters

nsAString_internal& str

nsAString_internal& operator=(const nsSubstringTuple&) - source

Parameters

nsSubstringTuple& tuple

get

PRUnichar* get() const - source

returns the null-terminated string

Find

PRInt32 Find(const nsCString&, PRBool, PRInt32, PRInt32) const - source

Search for the given substring within this string.
@param   aString is substring to be sought in this
@param   aIgnoreCase selects case sensitivity
@param   aOffset tells us where in this string to start searching
@param   aCount tells us how far from the offset we are to search. Use
-1 to search the whole string.
@return  offset in string, or kNotFound

Parameters

nsCString& aString
PRBool aIgnoreCase
PRInt32 aOffset
PRInt32 aCount

PRInt32 Find(const char*, PRBool, PRInt32, PRInt32) const - source

Parameters

char* aString
PRBool aIgnoreCase
PRInt32 aOffset
PRInt32 aCount

PRInt32 Find(const nsAFlatString&, PRInt32, PRInt32) const - source

Parameters

nsAFlatString& aString
PRInt32 aOffset
PRInt32 aCount

PRInt32 Find(const PRUnichar*, PRInt32, PRInt32) const - source

Parameters

PRUnichar* aString
PRInt32 aOffset
PRInt32 aCount

RFind

PRInt32 RFind(const nsCString&, PRBool, PRInt32, PRInt32) const - source

This methods scans the string backwards, looking for the given string
@param   aString is substring to be sought in this
@param   aIgnoreCase tells us whether or not to do caseless compare
@param   aOffset tells us where in this string to start searching.
Use -1 to search from the end of the string.
@param   aCount tells us how many iterations to make starting at the
given offset.
@return  offset in string, or kNotFound

Parameters

nsCString& aString
PRBool aIgnoreCase
PRInt32 aOffset
PRInt32 aCount

PRInt32 RFind(const char*, PRBool, PRInt32, PRInt32) const - source

Parameters

char* aCString
PRBool aIgnoreCase
PRInt32 aOffset
PRInt32 aCount

PRInt32 RFind(const nsAFlatString&, PRInt32, PRInt32) const - source

Parameters

nsAFlatString& aString
PRInt32 aOffset
PRInt32 aCount

PRInt32 RFind(const PRUnichar*, PRInt32, PRInt32) const - source

Parameters

PRUnichar* aString
PRInt32 aOffset
PRInt32 aCount

RFindChar

PRInt32 RFindChar(PRUnichar, PRInt32, PRInt32) const - source

Parameters

PRUnichar aChar
PRInt32 aOffset
PRInt32 aCount

FindCharInSet

PRInt32 FindCharInSet(const char*, PRInt32) const - source

This method searches this string for the first character found in
the given string.
@param aString contains set of chars to be found
@param aOffset tells us where in this string to start searching
(counting from left)
@return offset in string, or kNotFound

Parameters

char* aString
PRInt32 aOffset

PRInt32 FindCharInSet(const nsString&, PRInt32) const - source

Parameters

nsString& aString
PRInt32 aOffset

PRInt32 FindCharInSet(const PRUnichar*, PRInt32) const - source

Parameters

PRUnichar* aString
PRInt32 aOffset

RFindCharInSet

PRInt32 RFindCharInSet(const PRUnichar*, PRInt32) const - source

This method searches this string for the last character found in
the given string.
@param aString contains set of chars to be found
@param aOffset tells us where in this string to start searching
(counting from left)
@return offset in string, or kNotFound

Parameters

PRUnichar* aString
PRInt32 aOffset

PRInt32 RFindCharInSet(const nsString&, PRInt32) const - source

Parameters

nsString& aString
PRInt32 aOffset

EqualsIgnoreCase

PRBool EqualsIgnoreCase(const char*, PRInt32) const - source

Parameters

char* aString
PRInt32 aCount

ToFloat

float ToFloat(PRInt32*) const - source

Perform string to float conversion.
@param   aErrorCode will contain error if one occurs
@return  float rep of string value

Parameters

PRInt32* aErrorCode

ToInteger

PRInt32 ToInteger(PRInt32*, PRUint32) const - source

Parameters

PRInt32* aErrorCode
PRUint32 aRadix

Mid

PRUint32 Mid(nsString&, PRUint32, PRUint32) const - source

Parameters

nsString& aResult
PRUint32 aStartPos
PRUint32 aCount

Left

PRUint32 Left(nsString&, PRUint32) const - source

Parameters

nsString& aResult
PRUint32 aCount

Right

PRUint32 Right(nsString&, PRUint32) const - source

Parameters

nsString& aResult
PRUint32 aCount

SetCharAt

PRBool SetCharAt(PRUnichar, PRUint32) - source

Set a char inside this string at given index
@param aChar is the char you want to write into this string
@param anIndex is the ofs where you want to write the given char
@return TRUE if successful

Parameters

PRUnichar aChar
PRUint32 aIndex

StripChars

void StripChars(const char*) - source

These methods are used to remove all occurrences of the
characters found in aSet from this string.
@param  aSet -- characters to be cut from this

Parameters

char* aSet

StripWhitespace

void StripWhitespace() - source

This method strips whitespace throughout the string.

ReplaceChar

void ReplaceChar(PRUnichar, PRUnichar) - source

swaps occurence of 1 string for another

Parameters

PRUnichar aOldChar
PRUnichar aNewChar

void ReplaceChar(const char*, PRUnichar) - source

Parameters

char* aSet
PRUnichar aNewChar

ReplaceSubstring

void ReplaceSubstring(const nsString&, const nsString&) - source

Parameters

nsString& aTarget
nsString& aNewValue

void ReplaceSubstring(const PRUnichar*, const PRUnichar*) - source

Parameters

PRUnichar* aTarget
PRUnichar* aNewValue

Trim

void Trim(const char*, PRBool, PRBool, PRBool) - source

This method trims characters found in aTrimSet from
either end of the underlying string.
@param   aSet -- contains chars to be trimmed from both ends
@param   aEliminateLeading
@param   aEliminateTrailing
@param   aIgnoreQuotes -- if true, causes surrounding quotes to be ignored
@return  this

Parameters

char* aSet
PRBool aEliminateLeading
PRBool aEliminateTrailing
PRBool aIgnoreQuotes

CompressWhitespace

void CompressWhitespace(PRBool, PRBool) - source

This method strips whitespace from string.
You can control whether whitespace is yanked from start and end of
string as well.
@param   aEliminateLeading controls stripping of leading ws
@param   aEliminateTrailing controls stripping of trailing ws

Parameters

PRBool aEliminateLeading
PRBool aEliminateTrailing

AssignWithConversion

void AssignWithConversion(const nsACString_internal&) - source

assign/append/insert with _LOSSY_ conversion

Parameters

nsACString_internal& aString

void AssignWithConversion(const char*, PRInt32) - source

Parameters

char* aData
PRInt32 aLength

AppendWithConversion

void AppendWithConversion(const nsACString_internal&) - source

Parameters

nsACString_internal& aString

void AppendWithConversion(const char*, PRInt32) - source

Parameters

char* aData
PRInt32 aLength

AppendInt

void AppendInt(PRInt32, PRInt32) - source

Append the given integer to this string

Parameters

PRInt32 aInteger
PRInt32 aRadix

void AppendInt(PRUint32, PRInt32) - source

Append the given unsigned integer to this string

Parameters

PRUint32 aInteger
PRInt32 aRadix

void AppendInt(PRInt64, PRInt32) - source

Parameters

PRInt64 aInteger
PRInt32 aRadix

AppendFloat

void AppendFloat(float) - source

Append the given float to this string

Parameters

float aFloat

void AppendFloat(double) - source

Parameters

double aFloat

BeginReading

PRUnichar* BeginReading() const - source

reading iterators

nsReadingIterator<short unsigned int>& BeginReading(nsReadingIterator<short unsigned int>&) const - source

deprecated reading iterators

Parameters

nsReadingIterator<short unsigned int>& iter

PRUnichar*& BeginReading(const PRUnichar*&) const - source

Parameters

PRUnichar*& iter

EndReading

PRUnichar* EndReading() const - source

nsReadingIterator<short unsigned int>& EndReading(nsReadingIterator<short unsigned int>&) const - source

Parameters

nsReadingIterator<short unsigned int>& iter

PRUnichar*& EndReading(const PRUnichar*&) const - source

Parameters

PRUnichar*& iter

BeginWriting

PRUnichar* BeginWriting() - source

writing iterators

nsWritingIterator<short unsigned int>& BeginWriting(nsWritingIterator<short unsigned int>&) - source

deprecated writing iterators

Parameters

nsWritingIterator<short unsigned int>& iter

PRUnichar*& BeginWriting(PRUnichar*&) - source

Parameters

PRUnichar*& iter

EndWriting

PRUnichar* EndWriting() - source

nsWritingIterator<short unsigned int>& EndWriting(nsWritingIterator<short unsigned int>&) - source

Parameters

nsWritingIterator<short unsigned int>& iter

PRUnichar*& EndWriting(PRUnichar*&) - source

Parameters

PRUnichar*& iter

Data

PRUnichar* Data() const - source

accessors

Length

PRUint32 Length() const - source

IsEmpty

PRBool IsEmpty() const - source

IsVoid

PRBool IsVoid() const - source

IsTerminated

PRBool IsTerminated() const - source

CharAt

PRUnichar CharAt(PRUint32) const - source

Parameters

PRUint32 i

operator[]

PRUnichar operator[](PRUint32) const - source

Parameters

PRUint32 i

First

PRUnichar First() const - source

Last

PRUnichar Last() const - source

CountChar

PRUint32 CountChar(PRUnichar) const - source

Parameters

PRUnichar <anonymous>

FindChar

PRInt32 FindChar(PRUnichar, PRUint32) const - source

Parameters

PRUnichar <anonymous>
PRUint32 offset

Equals

PRBool Equals(const nsAString_internal&) const - source

equality

Parameters

nsAString_internal& <anonymous>

PRBool Equals(const nsAString_internal&, const nsStringComparator&) const - source

Parameters

nsAString_internal& <anonymous>
nsStringComparator& <anonymous>

PRBool Equals(const PRUnichar*) const - source

Parameters

PRUnichar* data

PRBool Equals(const PRUnichar*, const nsStringComparator&) const - source

Parameters

PRUnichar* data
nsStringComparator& comp

EqualsASCII

PRBool EqualsASCII(const char*, PRUint32) const - source

An efficient comparison with ASCII that can be used even
for wide strings. Call this version when you know the
length of 'data'.

Parameters

char* data
PRUint32 len

PRBool EqualsASCII(const char*) const - source

An efficient comparison with ASCII that can be used even
for wide strings. Call this version when 'data' is
null-terminated.

Parameters

char* data

EqualsLiteral(const char

PRBool EqualsLiteral(const char (&)[N]) const - source

EqualsLiteral(char

PRBool EqualsLiteral(char (&)[N]) const - source

LowerCaseEqualsASCII

PRBool LowerCaseEqualsASCII(const char*, PRUint32) const - source

Parameters

char* data
PRUint32 len

PRBool LowerCaseEqualsASCII(const char*) const - source

Parameters

char* data

LowerCaseEqualsLiteral(const char

PRBool LowerCaseEqualsLiteral(const char (&)[N]) const - source

LowerCaseEqualsLiteral(char

PRBool LowerCaseEqualsLiteral(char (&)[N]) const - source

Assign

void Assign(PRUnichar) - source

assignment

Parameters

PRUnichar c

void Assign(const PRUnichar*, PRUint32) - source

Parameters

PRUnichar* data
PRUint32 length

void Assign(const nsAString_internal&) - source

Parameters

nsAString_internal& <anonymous>

void Assign(const nsSubstringTuple&) - source

Parameters

nsSubstringTuple& <anonymous>

AssignASCII

void AssignASCII(const char*, PRUint32) - source

Parameters

char* data
PRUint32 length

void AssignASCII(const char*) - source

Parameters

char* data

AssignLiteral(const char

void AssignLiteral(const char (&)[N]) - source

AssignLiteral(char

void AssignLiteral(char (&)[N]) - source

Adopt

void Adopt(PRUnichar*, PRUint32) - source

Parameters

PRUnichar* data
PRUint32 length

Replace

void Replace(PRUint32, PRUint32, PRUnichar) - source

buffer manipulation

Parameters

PRUint32 cutStart
PRUint32 cutLength
PRUnichar c

void Replace(PRUint32, PRUint32, const PRUnichar*, PRUint32) - source

Parameters

PRUint32 cutStart
PRUint32 cutLength
PRUnichar* data
PRUint32 length

void Replace(PRUint32, PRUint32, const nsAString_internal&) - source

Parameters

PRUint32 cutStart
PRUint32 cutLength
nsAString_internal& str

void Replace(PRUint32, PRUint32, const nsSubstringTuple&) - source

Parameters

PRUint32 cutStart
PRUint32 cutLength
nsSubstringTuple& tuple

ReplaceASCII

void ReplaceASCII(PRUint32, PRUint32, const char*, PRUint32) - source

Parameters

PRUint32 cutStart
PRUint32 cutLength
char* data
PRUint32 length

Append

void Append(PRUnichar) - source

Parameters

PRUnichar c

void Append(const PRUnichar*, PRUint32) - source

Parameters

PRUnichar* data
PRUint32 length

void Append(const nsAString_internal&) - source

Parameters

nsAString_internal& str

void Append(const nsSubstringTuple&) - source

Parameters

nsSubstringTuple& tuple

AppendASCII

void AppendASCII(const char*, PRUint32) - source

Parameters

char* data
PRUint32 length

AppendLiteral(const char

void AppendLiteral(const char (&)[N]) - source

AppendLiteral(char

void AppendLiteral(char (&)[N]) - source

operator+=

nsAString_internal& operator+=(PRUnichar) - source

Parameters

PRUnichar c

nsAString_internal& operator+=(const PRUnichar*) - source

Parameters

PRUnichar* data

nsAString_internal& operator+=(const nsAString_internal&) - source

Parameters

nsAString_internal& str

nsAString_internal& operator+=(const nsSubstringTuple&) - source

Parameters

nsSubstringTuple& tuple

Insert

void Insert(PRUnichar, PRUint32) - source

Parameters

PRUnichar c
PRUint32 pos

void Insert(const PRUnichar*, PRUint32, PRUint32) - source

Parameters

PRUnichar* data
PRUint32 pos
PRUint32 length

void Insert(const nsAString_internal&, PRUint32) - source

Parameters

nsAString_internal& str
PRUint32 pos

void Insert(const nsSubstringTuple&, PRUint32) - source

Parameters

nsSubstringTuple& tuple
PRUint32 pos

Cut

void Cut(PRUint32, PRUint32) - source

Parameters

PRUint32 cutStart
PRUint32 cutLength

SetCapacity

void SetCapacity(PRUint32) - source

buffer sizing

Parameters

PRUint32 newCapacity

SetLength

void SetLength(PRUint32) - source

Parameters

PRUint32 newLength

Truncate

void Truncate(PRUint32) - source

Parameters

PRUint32 newLength

GetData

PRUint32 GetData(const PRUnichar**) const - source

Get a const pointer to the string's internal buffer.  The caller
MUST NOT modify the characters at the returned address.
@returns The length of the buffer in characters.

Parameters

PRUnichar** data

GetMutableData

PRUint32 GetMutableData(PRUnichar**, PRUint32) - source

Get a pointer to the string's internal buffer, optionally resizing
the buffer first.  If size_type(-1) is passed for newLen, then the
current length of the string is used.  The caller MAY modify the
characters at the returned address (up to but not exceeding the
length of the string).
@returns The length of the buffer in characters or 0 if unable to
satisfy the request due to low-memory conditions.

Parameters

PRUnichar** data
PRUint32 newLen

SetIsVoid

void SetIsVoid(PRBool) - source

string data is never null, but can be marked void.  if true, the
string will be truncated.  @see nsTSubstring::IsVoid

Parameters

PRBool <anonymous>

StripChar

void StripChar(PRUnichar, PRInt32) - source

This method is used to remove all occurrences of aChar from this
string.
@param  aChar -- char to be stripped
@param  aOffset -- where in this string to start stripping chars

Parameters

PRUnichar aChar
PRInt32 aOffset

Document Tags and Contributors

Contributors to this page: Sheppy, bsmedberg

Last updated by: Sheppy, Apr 22, 2014, 1:07:32 PM