Functions

nsReadableUtils.h File Reference

#include "nsAString.h"
#include "nsTArray.h"
Include dependency graph for nsReadableUtils.h:
This graph shows which files directly or indirectly include this file:

Functions

size_t Distance (const nsReadingIterator< PRUnichar > &start, const nsReadingIterator< PRUnichar > &end)
 I guess all the routines in this file are all mis-named.
size_t Distance (const nsReadingIterator< char > &start, const nsReadingIterator< char > &end)
void LossyCopyUTF16toASCII (const nsAString &aSource, nsACString &aDest)
void CopyASCIItoUTF16 (const nsACString &aSource, nsAString &aDest)
void LossyCopyUTF16toASCII (const PRUnichar *aSource, nsACString &aDest)
void CopyASCIItoUTF16 (const char *aSource, nsAString &aDest)
void CopyUTF16toUTF8 (const nsAString &aSource, nsACString &aDest)
 conversion classes
void CopyUTF8toUTF16 (const nsACString &aSource, nsAString &aDest)
void CopyUTF16toUTF8 (const PRUnichar *aSource, nsACString &aDest)
void CopyUTF8toUTF16 (const char *aSource, nsAString &aDest)
void LossyAppendUTF16toASCII (const nsAString &aSource, nsACString &aDest)
void AppendASCIItoUTF16 (const nsACString &aSource, nsAString &aDest)
void LossyAppendUTF16toASCII (const PRUnichar *aSource, nsACString &aDest)
void AppendASCIItoUTF16 (const char *aSource, nsAString &aDest)
void AppendUTF16toUTF8 (const nsAString &aSource, nsACString &aDest)
void AppendUTF8toUTF16 (const nsACString &aSource, nsAString &aDest)
void AppendUTF16toUTF8 (const PRUnichar *aSource, nsACString &aDest)
void AppendUTF8toUTF16 (const char *aSource, nsAString &aDest)
char * ToNewCString (const nsAString &aSource)
 Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
char * ToNewCString (const nsACString &aSource)
 Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
char * ToNewUTF8String (const nsAString &aSource, PRUint32 *aUTF8Count=0)
 Returns a new |char| buffer containing a zero-terminated copy of |aSource|.
PRUnicharToNewUnicode (const nsAString &aSource)
 Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
PRUnicharToNewUnicode (const nsACString &aSource)
 Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
PRUnicharUTF8ToNewUnicode (const nsACString &aSource, PRUint32 *aUTF16Count=0)
 Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.
PRUnicharCopyUnicodeTo (const nsAString &aSource, PRUint32 aSrcOffset, PRUnichar *aDest, PRUint32 aLength)
 Copies |aLength| 16-bit code units from the start of |aSource| to the |PRUnichar| buffer |aDest|.
void CopyUnicodeTo (const nsAString::const_iterator &aSrcStart, const nsAString::const_iterator &aSrcEnd, nsAString &aDest)
 Copies 16-bit characters between iterators |aSrcStart| and |aSrcEnd| to the writable string |aDest|.
void AppendUnicodeTo (const nsAString::const_iterator &aSrcStart, const nsAString::const_iterator &aSrcEnd, nsAString &aDest)
 Appends 16-bit characters between iterators |aSrcStart| and |aSrcEnd| to the writable string |aDest|.
PRBool IsASCII (const nsAString &aString)
 Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F).
PRBool IsASCII (const nsACString &aString)
 Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F).
PRBool IsUTF8 (const nsACString &aString)
 Returns |PR_TRUE| if |aString| is a valid UTF-8 string.
PRBool ParseString (const nsACString &aAstring, char aDelimiter, nsTArray< nsCString > &aArray)
void ToUpperCase (nsACString &)
 Converts case in place in the argument string.
void ToLowerCase (nsACString &)
void ToUpperCase (const nsACString &aSource, nsACString &aDest)
 Converts case from string aSource to aDest.
void ToLowerCase (const nsACString &aSource, nsACString &aDest)
PRBool FindInReadable (const nsAString &aPattern, nsAString::const_iterator &, nsAString::const_iterator &, const nsStringComparator &=nsDefaultStringComparator())
 Finds the leftmost occurrence of |aPattern|, if any in the range |aSearchStart|..|aSearchEnd|.
PRBool FindInReadable (const nsACString &aPattern, nsACString::const_iterator &, nsACString::const_iterator &, const nsCStringComparator &=nsDefaultCStringComparator())
PRBool FindInReadable (const nsAString &aPattern, const nsAString &aSource, const nsStringComparator &compare=nsDefaultStringComparator())
PRBool FindInReadable (const nsACString &aPattern, const nsACString &aSource, const nsCStringComparator &compare=nsDefaultCStringComparator())
PRBool CaseInsensitiveFindInReadable (const nsACString &aPattern, nsACString::const_iterator &, nsACString::const_iterator &)
PRBool RFindInReadable (const nsAString &aPattern, nsAString::const_iterator &, nsAString::const_iterator &, const nsStringComparator &=nsDefaultStringComparator())
 Finds the rightmost occurrence of |aPattern| Returns |PR_TRUE| if a match was found, and adjusts |aSearchStart| and |aSearchEnd| to point to the match.
PRBool RFindInReadable (const nsACString &aPattern, nsACString::const_iterator &, nsACString::const_iterator &, const nsCStringComparator &=nsDefaultCStringComparator())
PRBool FindCharInReadable (PRUnichar aChar, nsAString::const_iterator &aSearchStart, const nsAString::const_iterator &aSearchEnd)
 Finds the leftmost occurrence of |aChar|, if any in the range |aSearchStart|..|aSearchEnd|.
PRBool FindCharInReadable (char aChar, nsACString::const_iterator &aSearchStart, const nsACString::const_iterator &aSearchEnd)
PRUint32 CountCharInReadable (const nsAString &aStr, PRUnichar aChar)
 Finds the number of occurences of |aChar| in the string |aStr|.
PRUint32 CountCharInReadable (const nsACString &aStr, char aChar)
PRBool StringBeginsWith (const nsAString &aSource, const nsAString &aSubstring, const nsStringComparator &aComparator=nsDefaultStringComparator())
PRBool StringBeginsWith (const nsACString &aSource, const nsACString &aSubstring, const nsCStringComparator &aComparator=nsDefaultCStringComparator())
PRBool StringEndsWith (const nsAString &aSource, const nsAString &aSubstring, const nsStringComparator &aComparator=nsDefaultStringComparator())
PRBool StringEndsWith (const nsACString &aSource, const nsACString &aSubstring, const nsCStringComparator &aComparator=nsDefaultCStringComparator())
const nsAFlatStringEmptyString ()
const nsAFlatCStringEmptyCString ()
PRInt32 CompareUTF8toUTF16 (const nsASingleFragmentCString &aUTF8String, const nsASingleFragmentString &aUTF16String)
 Compare a UTF-8 string to an UTF-16 string.
void AppendUCS4ToUTF16 (const PRUint32 aSource, nsAString &aDest)
template<class T >
PRBool EnsureStringLength (T &aStr, PRUint32 aLen)

Function Documentation

void AppendASCIItoUTF16 ( const nsACString aSource,
nsAString aDest 
)
void AppendASCIItoUTF16 ( const char *  aSource,
nsAString aDest 
)
void AppendUCS4ToUTF16 ( const PRUint32  aSource,
nsAString aDest 
)
void AppendUnicodeTo ( const nsAString::const_iterator &  aSrcStart,
const nsAString::const_iterator &  aSrcEnd,
nsAString aDest 
)

Appends 16-bit characters between iterators |aSrcStart| and |aSrcEnd| to the writable string |aDest|.

After this operation |aDest| is not null terminated.

Parameters:
aSrcStart start source iterator
aSrcEnd end source iterator
aDest destination for the copy
void AppendUTF16toUTF8 ( const PRUnichar aSource,
nsACString aDest 
)
void AppendUTF16toUTF8 ( const nsAString aSource,
nsACString aDest 
)
void AppendUTF8toUTF16 ( const nsACString aSource,
nsAString aDest 
)
void AppendUTF8toUTF16 ( const char *  aSource,
nsAString aDest 
)
PRBool CaseInsensitiveFindInReadable ( const nsACString aPattern,
nsACString::const_iterator &  ,
nsACString::const_iterator &   
)
PRInt32 CompareUTF8toUTF16 ( const nsASingleFragmentCString aUTF8String,
const nsASingleFragmentString aUTF16String 
)

Compare a UTF-8 string to an UTF-16 string.

Returns 0 if the strings are equal, -1 if aUTF8String is less than aUTF16Count, and 1 in the reverse case. In case of fatal error (eg the strings are not valid UTF8 and UTF16 respectively), this method will return PR_INT32_MIN.

void CopyASCIItoUTF16 ( const char *  aSource,
nsAString aDest 
)
void CopyASCIItoUTF16 ( const nsACString aSource,
nsAString aDest 
) [inline]
PRUnichar* CopyUnicodeTo ( const nsAString aSource,
PRUint32  aSrcOffset,
PRUnichar aDest,
PRUint32  aLength 
)

Copies |aLength| 16-bit code units from the start of |aSource| to the |PRUnichar| buffer |aDest|.

After this operation |aDest| is not null terminated.

Parameters:
aSource a UTF-16 string
aSrcOffset start offset in the source string
aDest a |PRUnichar| buffer
aLength the number of 16-bit code units to copy
Returns:
pointer to destination buffer - identical to |aDest|
void CopyUnicodeTo ( const nsAString::const_iterator &  aSrcStart,
const nsAString::const_iterator &  aSrcEnd,
nsAString aDest 
)

Copies 16-bit characters between iterators |aSrcStart| and |aSrcEnd| to the writable string |aDest|.

Similar to the |nsStringMid| method.

After this operation |aDest| is not null terminated.

Parameters:
aSrcStart start source iterator
aSrcEnd end source iterator
aDest destination for the copy
void CopyUTF16toUTF8 ( const PRUnichar aSource,
nsACString aDest 
)
void CopyUTF16toUTF8 ( const nsAString aSource,
nsACString aDest 
) [inline]

conversion classes

void CopyUTF8toUTF16 ( const nsACString aSource,
nsAString aDest 
) [inline]
void CopyUTF8toUTF16 ( const char *  aSource,
nsAString aDest 
)
PRUint32 CountCharInReadable ( const nsAString aStr,
PRUnichar  aChar 
)

Finds the number of occurences of |aChar| in the string |aStr|.

PRUint32 CountCharInReadable ( const nsACString aStr,
char  aChar 
)
size_t Distance ( const nsReadingIterator< char > &  start,
const nsReadingIterator< char > &  end 
) [inline]
size_t Distance ( const nsReadingIterator< PRUnichar > &  start,
const nsReadingIterator< PRUnichar > &  end 
) [inline]

I guess all the routines in this file are all mis-named.

According to our conventions, they should be |NS_xxx|.

const nsAFlatCString& EmptyCString (  ) 
const nsAFlatString& EmptyString (  ) 
template<class T >
PRBool EnsureStringLength ( T &  aStr,
PRUint32  aLen 
) [inline]
PRBool FindCharInReadable ( PRUnichar  aChar,
nsAString::const_iterator &  aSearchStart,
const nsAString::const_iterator &  aSearchEnd 
)

Finds the leftmost occurrence of |aChar|, if any in the range |aSearchStart|..|aSearchEnd|.

Returns |PR_TRUE| if a match was found, and adjusts |aSearchStart| to point to the match. If no match was found, returns |PR_FALSE| and makes |aSearchStart == aSearchEnd|.

PRBool FindCharInReadable ( char  aChar,
nsACString::const_iterator &  aSearchStart,
const nsACString::const_iterator &  aSearchEnd 
)
PRBool FindInReadable ( const nsACString aPattern,
nsACString::const_iterator &  ,
nsACString::const_iterator &  ,
const nsCStringComparator &  = nsDefaultCStringComparator() 
)
PRBool FindInReadable ( const nsAString aPattern,
nsAString::const_iterator &  ,
nsAString::const_iterator &  ,
const nsStringComparator &  = nsDefaultStringComparator() 
)

Finds the leftmost occurrence of |aPattern|, if any in the range |aSearchStart|..|aSearchEnd|.

Returns |PR_TRUE| if a match was found, and adjusts |aSearchStart| and |aSearchEnd| to point to the match. If no match was found, returns |PR_FALSE| and makes |aSearchStart == aSearchEnd|.

Currently, this is equivalent to the O(m*n) implementation previously on |ns[C]String|. If we need something faster, then we can implement that later.

PRBool FindInReadable ( const nsAString aPattern,
const nsAString aSource,
const nsStringComparator &  compare = nsDefaultStringComparator() 
) [inline]
PRBool FindInReadable ( const nsACString aPattern,
const nsACString aSource,
const nsCStringComparator &  compare = nsDefaultCStringComparator() 
) [inline]
PRBool IsASCII ( const nsAString aString  ) 

Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F).

Parameters:
aString a 16-bit wide string to scan
PRBool IsASCII ( const nsACString aString  ) 

Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F).

Parameters:
aString a 8-bit wide string to scan
PRBool IsUTF8 ( const nsACString aString  ) 

Returns |PR_TRUE| if |aString| is a valid UTF-8 string.

XXX This is not bullet-proof and nor an all-purpose UTF-8 validator. It is mainly written to replace and roughly equivalent to

str.Equals(NS_ConvertUTF16toUTF8(NS_ConvertUTF8toUTF16(str)))

(see bug 191541) As such, it does not check for non-UTF-8 7bit encodings such as ISO-2022-JP and HZ. However, it filters out UTF-8 representation of surrogate codepoints and non-characters ( 0xFFFE and 0xFFFF in planes 0 through 16.) as well as overlong UTF-8 sequences. Also note that it regards UTF-8 sequences corresponding to codepoints above 0x10FFFF as invalid in accordance with http://www.ietf.org/internet-drafts/draft-yergeau-rfc2279bis-04.txt

Parameters:
aString an 8-bit wide string to scan
void LossyAppendUTF16toASCII ( const PRUnichar aSource,
nsACString aDest 
)
void LossyAppendUTF16toASCII ( const nsAString aSource,
nsACString aDest 
)
void LossyCopyUTF16toASCII ( const PRUnichar aSource,
nsACString aDest 
)
void LossyCopyUTF16toASCII ( const nsAString aSource,
nsACString aDest 
) [inline]
PRBool ParseString ( const nsACString aAstring,
char  aDelimiter,
nsTArray< nsCString > &  aArray 
)
PRBool RFindInReadable ( const nsACString aPattern,
nsACString::const_iterator &  ,
nsACString::const_iterator &  ,
const nsCStringComparator &  = nsDefaultCStringComparator() 
)
PRBool RFindInReadable ( const nsAString aPattern,
nsAString::const_iterator &  ,
nsAString::const_iterator &  ,
const nsStringComparator &  = nsDefaultStringComparator() 
)

Finds the rightmost occurrence of |aPattern| Returns |PR_TRUE| if a match was found, and adjusts |aSearchStart| and |aSearchEnd| to point to the match.

If no match was found, returns |PR_FALSE| and makes |aSearchStart == aSearchEnd|.

PRBool StringBeginsWith ( const nsACString aSource,
const nsACString aSubstring,
const nsCStringComparator &  aComparator = nsDefaultCStringComparator() 
)
PRBool StringBeginsWith ( const nsAString aSource,
const nsAString aSubstring,
const nsStringComparator &  aComparator = nsDefaultStringComparator() 
)
PRBool StringEndsWith ( const nsACString aSource,
const nsACString aSubstring,
const nsCStringComparator &  aComparator = nsDefaultCStringComparator() 
)
PRBool StringEndsWith ( const nsAString aSource,
const nsAString aSubstring,
const nsStringComparator &  aComparator = nsDefaultStringComparator() 
)
void ToLowerCase ( nsACString  ) 
void ToLowerCase ( const nsACString aSource,
nsACString aDest 
)
char* ToNewCString ( const nsAString aSource  ) 

Returns a new |char| buffer containing a zero-terminated copy of |aSource|.

Allocates and returns a new |char| buffer which you must free with |nsMemoryFree|. Performs a lossy encoding conversion by chopping 16-bit wide characters down to 8-bits wide while copying |aSource| to your new buffer. This conversion is not well defined; but it reproduces legacy string behavior. The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.

Parameters:
aSource a 16-bit wide string
Returns:
a new |char| buffer you must free with |nsMemoryFree|.
char* ToNewCString ( const nsACString aStr  )  [inline]

Returns a new |char| buffer containing a zero-terminated copy of |aSource|.

Allocates and returns a new |char| buffer which you must free with |nsMemoryFree|. The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.

Parameters:
aSource an 8-bit wide string
Returns:
a new |char| buffer you must free with |nsMemoryFree|.

Returns a new |char| buffer containing a zero-terminated copy of |aSource|.

They may disappear in the future.

PRUnichar* ToNewUnicode ( const nsAString aSource  )  [inline]

Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.

Allocates and returns a new |PRUnichar| buffer which you must free with |nsMemoryFree|. The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.

Parameters:
aSource a UTF-16 string
Returns:
a new |PRUnichar| buffer you must free with |nsMemoryFree|.
PRUnichar* ToNewUnicode ( const nsACString aSource  ) 

Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.

Allocates and returns a new |PRUnichar| buffer which you must free with |nsMemoryFree|. Performs an encoding conversion by 0-padding 8-bit wide characters up to 16-bits wide while copying |aSource| to your new buffer. This conversion is not well defined; but it reproduces legacy string behavior. The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.

Parameters:
aSource an 8-bit wide string (a C-string, NOT UTF-8)
Returns:
a new |PRUnichar| buffer you must free with |nsMemoryFree|.
char* ToNewUTF8String ( const nsAString aSource,
PRUint32 *  aUTF8Count = 0 
)

Returns a new |char| buffer containing a zero-terminated copy of |aSource|.

Allocates and returns a new |char| buffer which you must free with |nsMemoryFree|. Performs an encoding conversion from a UTF-16 string to a UTF-8 string copying |aSource| to your new buffer. The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.

Parameters:
aSource a UTF-16 string (made of PRUnichar's)
aUTF8Count the number of 8-bit units that was returned
Returns:
a new |char| buffer you must free with |nsMemoryFree|.
void ToUpperCase ( const nsACString aSource,
nsACString aDest 
)

Converts case from string aSource to aDest.

void ToUpperCase ( nsACString  ) 

Converts case in place in the argument string.

PRUnichar* UTF8ToNewUnicode ( const nsACString aSource,
PRUint32 *  aUTF16Count = 0 
)

Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|.

Allocates and returns a new |char| buffer which you must free with |nsMemoryFree|. Performs an encoding conversion from UTF-8 to UTF-16 while copying |aSource| to your new buffer. This conversion is well defined for a valid UTF-8 string. The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls.

Parameters:
aSource an 8-bit wide string, UTF-8 encoded
aUTF16Count the number of 16-bit units that was returned
Returns:
a new |PRUnichar| buffer you must free with |nsMemoryFree|. (UTF-16 encoded)