Back to index

lightning-sunbird  0.9+nobinonly
Classes | Defines | Typedefs | Enumerations | Functions | Variables
nsStringAPI.h File Reference
#include <string.h>
#include "nscore.h"
#include "nsDebug.h"
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  nsAString_external
class  nsACString_external
class  nsStringContainer
 Below we define nsStringContainer and nsCStringContainer. More...
class  nsCStringContainer
class  nsString
 basic strings More...
class  nsCString
class  nsDependentString
 dependent strings More...
class  nsDependentCString
class  NS_ConvertASCIItoUTF16
 conversion classes More...
class  NS_ConvertUTF8toUTF16
class  NS_ConvertUTF16toUTF8
 A helper class that converts a UTF-16 string to UTF-8. More...
class  NS_LossyConvertUTF16toASCII
 A helper class that converts a UTF-16 string to ASCII in a lossy manner. More...
class  nsGetterCopies
 getter_Copies support More...
class  nsCGetterCopies
class  nsDependentSubstring
 substrings More...
class  nsDependentCSubstring

Defines

#define NS_STRINGAPI(type)   extern "C" NS_IMPORT type
 nsStringAPI.h
#define nsAString_external   nsAString
 Below we define nsAString and nsACString.
#define nsACString_external   nsACString
#define nsString   nsString_external
 Below we define a number of inlined helper classes that make the frozen string API easier to use.
#define nsCString   nsCString_external
#define nsDependentString   nsDependentString_external
#define nsDependentCString   nsDependentCString_external
#define NS_ConvertASCIItoUTF16   NS_ConvertASCIItoUTF16_external
#define NS_ConvertUTF8toUTF16   NS_ConvertUTF8toUTF16_external
#define NS_ConvertUTF16toUTF8   NS_ConvertUTF16toUTF8_external
#define NS_LossyConvertUTF16toASCII   NS_LossyConvertUTF16toASCII_external
#define nsGetterCopies   nsGetterCopies_external
#define nsCGetterCopies   nsCGetterCopies_external
#define nsDependentSubstring   nsDependentSubstring_external
#define nsDependentCSubstring   nsDependentCSubstring_external
#define NS_LL(s)   s
 literal strings
#define NS_MULTILINE_LITERAL_STRING(s)   NS_ConvertASCIItoUTF16(s, PRUint32(sizeof(s)-1))
#define NS_MULTILINE_LITERAL_STRING_INIT(n, s)   n(s, PRUint32(sizeof(s)-1))
#define NS_NAMED_MULTILINE_LITERAL_STRING(n, s)   const NS_ConvertASCIItoUTF16 n(s, PRUint32(sizeof(s)-1))
#define NS_L(s)   NS_LL(s)
#define NS_LITERAL_STRING(s)   NS_STATIC_CAST(const nsString&, NS_MULTILINE_LITERAL_STRING(NS_LL(s)))
#define NS_LITERAL_STRING_INIT(n, s)   NS_MULTILINE_LITERAL_STRING_INIT(n, NS_LL(s))
#define NS_NAMED_LITERAL_STRING(n, s)   NS_NAMED_MULTILINE_LITERAL_STRING(n, NS_LL(s))
#define NS_LITERAL_CSTRING(s)   NS_STATIC_CAST(const nsDependentCString&, nsDependentCString(s, PRUint32(sizeof(s)-1)))
#define NS_LITERAL_CSTRING_INIT(n, s)   n(s, PRUint32(sizeof(s)-1))
#define NS_NAMED_LITERAL_CSTRING(n, s)   const nsDependentCString n(s, PRUint32(sizeof(s)-1))
#define EmptyCString()   nsCString()
#define EmptyString()   nsString()

Typedefs

typedef NS_ConvertASCIItoUTF16 nsLiteralString
typedef nsDependentCString nsLiteralCString

Enumerations

enum  { NS_STRING_CONTAINER_INIT_DEPEND = (1 << 1), NS_STRING_CONTAINER_INIT_ADOPT = (1 << 2), NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3) }
 Flags that may be OR'd together to pass to NS_StringContainerInit2: More...
enum  { NS_CSTRING_CONTAINER_INIT_DEPEND = (1 << 1), NS_CSTRING_CONTAINER_INIT_ADOPT = (1 << 2), NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3) }
 Flags that may be OR'd together to pass to NS_StringContainerInit2: More...

Functions

 NS_StringContainerInit (nsStringContainer &aContainer)
 NS_StringContainerInit.
 NS_StringContainerInit2 (nsStringContainer &aContainer, const PRUnichar *aData=nsnull, PRUint32 aDataLength=PR_UINT32_MAX, PRUint32 aFlags=0)
 NS_StringContainerInit2.
 NS_StringContainerFinish (nsStringContainer &aContainer)
 NS_StringContainerFinish.
 NS_StringGetData (const nsAString &aStr, const PRUnichar **aData, PRBool *aTerminated=nsnull)
 NS_StringGetData.
 NS_StringGetMutableData (nsAString &aStr, PRUint32 aDataLength, PRUnichar **aData)
 NS_StringGetMutableData.
 NS_StringCloneData (const nsAString &aStr)
 NS_StringCloneData.
 NS_StringSetData (nsAString &aStr, const PRUnichar *aData, PRUint32 aDataLength=PR_UINT32_MAX)
 NS_StringSetData.
 NS_StringSetDataRange (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength, const PRUnichar *aData, PRUint32 aDataLength=PR_UINT32_MAX)
 NS_StringSetDataRange.
 NS_StringCopy (nsAString &aDestStr, const nsAString &aSrcStr)
 NS_StringCopy.
 NS_HIDDEN_ (nsresult) NS_StringAppendData(nsAString &aStr
 NS_StringAppendData.
 NS_CStringContainerInit (nsCStringContainer &aContainer)
 NS_CStringContainerInit.
 NS_CStringContainerInit2 (nsCStringContainer &aContainer, const char *aData=nsnull, PRUint32 aDataLength=PR_UINT32_MAX, PRUint32 aFlags=0)
 NS_CStringContainerInit2.
 NS_CStringContainerFinish (nsCStringContainer &aContainer)
 NS_CStringContainerFinish.
 NS_CStringGetData (const nsACString &aStr, const char **aData, PRBool *aTerminated=nsnull)
 NS_CStringGetData.
 NS_CStringGetMutableData (nsACString &aStr, PRUint32 aDataLength, char **aData)
 NS_CStringGetMutableData.
 NS_CStringCloneData (const nsACString &aStr)
 NS_CStringCloneData.
 NS_CStringSetData (nsACString &aStr, const char *aData, PRUint32 aDataLength=PR_UINT32_MAX)
 NS_CStringSetData.
 NS_CStringSetDataRange (nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength, const char *aData, PRUint32 aDataLength=PR_UINT32_MAX)
 NS_CStringSetDataRange.
 NS_CStringCopy (nsACString &aDestStr, const nsACString &aSrcStr)
 NS_CStringCopy.
 NS_CStringToUTF16 (const nsACString &aSource, nsCStringEncoding aSrcEncoding, nsAString &aDest)
 NS_CStringToUTF16.
 NS_UTF16ToCString (const nsAString &aSource, nsCStringEncoding aDestEncoding, nsACString &aDest)
 NS_UTF16ToCString.
nsGetterCopies getter_Copies (nsString &aString)
nsCGetterCopies getter_Copies (nsCString &aString)
const nsDependentSubstring Substring (const nsAString &str, PRUint32 startPos)
 Various nsDependentC?Substring constructor functions.
const nsDependentSubstring Substring (const nsAString &str, PRUint32 startPos, PRUint32 length)
const nsDependentSubstring Substring (const PRUnichar *start, const PRUnichar *end)
const nsDependentSubstring Substring (const PRUnichar *start, PRUint32 length)
const nsDependentSubstring StringHead (const nsAString &str, PRUint32 count)
const nsDependentSubstring StringTail (const nsAString &str, PRUint32 count)
const nsDependentCSubstring Substring (const nsACString &str, PRUint32 startPos)
const nsDependentCSubstring Substring (const nsACString &str, PRUint32 startPos, PRUint32 length)
const nsDependentCSubstring Substring (const char *start, const char *end)
const nsDependentCSubstring Substring (const char *start, PRUint32 length)
const nsDependentCSubstring StringHead (const nsACString &str, PRUint32 count)
const nsDependentCSubstring StringTail (const nsACString &str, PRUint32 count)

Variables

const PRUnicharaData
const PRUnichar PRUint32 aDataLength

Define Documentation

Definition at line 1732 of file nsStringAPI.h.

#define EmptyString ( )    nsString()

Definition at line 1733 of file nsStringAPI.h.

#define NS_ConvertASCIItoUTF16   NS_ConvertASCIItoUTF16_external

Definition at line 1113 of file nsStringAPI.h.

#define NS_ConvertUTF16toUTF8   NS_ConvertUTF16toUTF8_external

Definition at line 1115 of file nsStringAPI.h.

#define NS_ConvertUTF8toUTF16   NS_ConvertUTF8toUTF16_external

Definition at line 1114 of file nsStringAPI.h.

#define NS_L (   s)    NS_LL(s)

Definition at line 1427 of file nsStringAPI.h.

Definition at line 1433 of file nsStringAPI.h.

#define NS_LITERAL_CSTRING_INIT (   n,
  s 
)    n(s, PRUint32(sizeof(s)-1))

Definition at line 1434 of file nsStringAPI.h.

Definition at line 1429 of file nsStringAPI.h.

Definition at line 1430 of file nsStringAPI.h.

#define NS_LL (   s)    s

literal strings

NOTE: HAVE_CPP_2BYTE_WCHAR_T may be automatically defined for some platforms in nscore.h. On other platforms, it may be defined in xpcom-config.h. Under GCC, this define should only be set if compiling with -fshort-wchar.

Definition at line 1411 of file nsStringAPI.h.

#define NS_LossyConvertUTF16toASCII   NS_LossyConvertUTF16toASCII_external

Definition at line 1116 of file nsStringAPI.h.

Definition at line 1412 of file nsStringAPI.h.

#define NS_MULTILINE_LITERAL_STRING_INIT (   n,
  s 
)    n(s, PRUint32(sizeof(s)-1))

Definition at line 1413 of file nsStringAPI.h.

#define NS_NAMED_LITERAL_CSTRING (   n,
  s 
)    const nsDependentCString n(s, PRUint32(sizeof(s)-1))

Definition at line 1435 of file nsStringAPI.h.

Definition at line 1431 of file nsStringAPI.h.

Definition at line 1414 of file nsStringAPI.h.

#define NS_STRINGAPI (   type)    extern "C" NS_IMPORT type

nsStringAPI.h

This file describes a minimal API for working with XPCOM's abstract string classes. It divorces the consumer from having any run-time dependency on the implementation details of the abstract string types.

Definition at line 82 of file nsStringAPI.h.

#define nsACString_external   nsACString

Definition at line 828 of file nsStringAPI.h.

#define nsAString_external   nsAString

Below we define nsAString and nsACString.

The "_external" suffix is an implementation detail. nsAString_external is the name of the external representation of nsAString from the point of view of the Mozilla codebase. To a user of this API, nsAString_external is exactly nsAString.

These classes should be treated as abstract classes with unspecified structure. The inline methods are provided as helper functions around the C-style API provided above.

Do not try to mix these definitions of nsAString and nsACString with the internal definition of these classes from nsAString.h in the Mozilla tree.

Definition at line 827 of file nsStringAPI.h.

#define nsCGetterCopies   nsCGetterCopies_external

Definition at line 1118 of file nsStringAPI.h.

#define nsCString   nsCString_external

Definition at line 1110 of file nsStringAPI.h.

#define nsDependentCString   nsDependentCString_external

Definition at line 1112 of file nsStringAPI.h.

#define nsDependentCSubstring   nsDependentCSubstring_external

Definition at line 1120 of file nsStringAPI.h.

#define nsDependentString   nsDependentString_external

Definition at line 1111 of file nsStringAPI.h.

#define nsDependentSubstring   nsDependentSubstring_external

Definition at line 1119 of file nsStringAPI.h.

#define nsGetterCopies   nsGetterCopies_external

Definition at line 1117 of file nsStringAPI.h.

#define nsString   nsString_external

Below we define a number of inlined helper classes that make the frozen string API easier to use.

Rename symbols to avoid conflicting with internal versions.

Definition at line 1109 of file nsStringAPI.h.


Typedef Documentation

Definition at line 1437 of file nsStringAPI.h.

Definition at line 1415 of file nsStringAPI.h.


Enumeration Type Documentation

anonymous enum

Flags that may be OR'd together to pass to NS_StringContainerInit2:

Enumerator:
NS_STRING_CONTAINER_INIT_DEPEND 
NS_STRING_CONTAINER_INIT_ADOPT 
NS_STRING_CONTAINER_INIT_SUBSTRING 

Definition at line 160 of file nsStringAPI.h.

     {
  /* Data passed into NS_StringContainerInit2 is not copied; instead, the
   * string references the passed in data pointer directly.  The caller must
   * ensure that the data is valid for the lifetime of the string container.
   * This flag should not be combined with NS_STRING_CONTAINER_INIT_ADOPT. */
  NS_STRING_CONTAINER_INIT_DEPEND    = (1 << 1),

  /* Data passed into NS_StringContainerInit2 is not copied; instead, the
   * string takes ownership over the data pointer.  The caller must have
   * allocated the data array using the XPCOM memory allocator (nsMemory).
   * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */
  NS_STRING_CONTAINER_INIT_ADOPT     = (1 << 2),

  /* Data passed into NS_StringContainerInit2 is a substring that is not
   * null-terminated. */
  NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
};
anonymous enum

Flags that may be OR'd together to pass to NS_StringContainerInit2:

Enumerator:
NS_CSTRING_CONTAINER_INIT_DEPEND 
NS_CSTRING_CONTAINER_INIT_ADOPT 
NS_CSTRING_CONTAINER_INIT_SUBSTRING 

Definition at line 465 of file nsStringAPI.h.

     {
  /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
   * string references the passed in data pointer directly.  The caller must
   * ensure that the data is valid for the lifetime of the string container.
   * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */
  NS_CSTRING_CONTAINER_INIT_DEPEND    = (1 << 1),

  /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
   * string takes ownership over the data pointer.  The caller must have
   * allocated the data array using the XPCOM memory allocator (nsMemory).
   * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
  NS_CSTRING_CONTAINER_INIT_ADOPT     = (1 << 2),

  /* Data passed into NS_CStringContainerInit2 is a substring that is not
   * null-terminated. */
  NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
};

Function Documentation

nsGetterCopies getter_Copies ( nsString aString) [inline]

Definition at line 1478 of file nsStringAPI.h.

{
  return nsGetterCopies(aString);
}
nsCGetterCopies getter_Copies ( nsCString aString) [inline]

Definition at line 1508 of file nsStringAPI.h.

{
  return nsCGetterCopies(aString);
}
NS_CStringCloneData ( const nsACString &  aStr)

NS_CStringCloneData.

This function returns a null-terminated copy of the string's internal buffer.

Parameters:
aStrabstract string reference
Returns:
null-terminated copy of the string's internal buffer (it must be free'd using using nsMemory::Free)

FROZEN

Definition at line 291 of file nsStringAPI.cpp.

{
  return ToNewCString(aStr);
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_CStringContainerFinish.

Parameters:
aContainerstring container reference

This function frees any memory owned by aContainer.

FROZEN

Definition at line 252 of file nsStringAPI.cpp.

{
  // call the nsCString dtor
  NS_REINTERPRET_CAST(nsCString *, &aContainer)->~nsCString();
}

Here is the caller graph for this function:

NS_CStringContainerInit.

Parameters:
aContainerstring container reference
Returns:
NS_OK if string container successfully initialized

This function may allocate additional memory for aContainer. When aContainer is no longer needed, NS_CStringContainerFinish should be called.

FROZEN

Definition at line 195 of file nsStringAPI.cpp.

{
  NS_ASSERTION(sizeof(nsCStringContainer) >= sizeof(nsCString),
      "nsCStringContainer is not large enough");

  // use placement new to avoid heap allocating nsCString object
  new (&aContainer) nsCString();

  return NS_OK;
}

Here is the caller graph for this function:

NS_CStringContainerInit2 ( nsCStringContainer aContainer,
const char *  aData = nsnull,
PRUint32  aDataLength = PR_UINT32_MAX,
PRUint32  aFlags = 0 
)

NS_CStringContainerInit2.

Parameters:
aContainerstring container reference
aDatacharacter buffer (may be null)
aDataLengthnumber of characters stored at aData (may pass PR_UINT32_MAX if aData is null-terminated)
aFlagsflags affecting how the string container is initialized. this parameter is ignored when aData is null. otherwise, if this parameter is 0, then aData is copied into the string.

This function resembles NS_CStringContainerInit but provides further options that permit more efficient memory usage. When aContainer is no longer needed, NS_CStringContainerFinish should be called.

NOTE: NS_CStringContainerInit2(container, nsnull, 0, 0) is equivalent to NS_CStringContainerInit(container).

FROZEN

Definition at line 207 of file nsStringAPI.cpp.

{
  NS_ASSERTION(sizeof(nsCStringContainer) >= sizeof(nsCString),
      "nsStringContainer is not large enough");

  if (!aData)
  {
    new (&aContainer) nsCString();
  }
  else
  {
    if (aDataLength == PR_UINT32_MAX)
    {
      NS_ENSURE_ARG(!(aFlags & NS_CSTRING_CONTAINER_INIT_SUBSTRING));
      aDataLength = nsCharTraits<char>::length(aData);
    }

    if (aFlags & (NS_CSTRING_CONTAINER_INIT_DEPEND |
                  NS_CSTRING_CONTAINER_INIT_ADOPT))
    {
      PRUint32 flags;
      if (aFlags & NS_CSTRING_CONTAINER_INIT_SUBSTRING)
        flags = nsCSubstring::F_NONE;
      else
        flags = nsCSubstring::F_TERMINATED;

      if (aFlags & NS_CSTRING_CONTAINER_INIT_ADOPT)
        flags |= nsCSubstring::F_OWNED;

      new (&aContainer) nsCSubstring(NS_CONST_CAST(char *, aData),
                                     aDataLength, flags);
    }
    else
    {
      new (&aContainer) nsCString(aData, aDataLength);
    }
  }

  return NS_OK;
}

Here is the caller graph for this function:

NS_CStringCopy ( nsACString &  aDestStr,
const nsACString &  aSrcStr 
)

NS_CStringCopy.

This function makes aDestStr have the same value as aSrcStr. It is provided as an optimization.

Parameters:
aDestStrabstract string reference to be modified
aSrcStrabstract string reference containing source string
Returns:
NS_OK if function succeeded

This function does not necessarily null-terminate aDestStr after copying data from aSrcStr. The behavior depends on the implementation of the abstract string, aDestStr. If aDestStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 333 of file nsStringAPI.cpp.

{
  aDest.Assign(aSrc);
  return NS_OK; // XXX report errors
}

Here is the caller graph for this function:

NS_CStringGetData ( const nsACString &  aStr,
const char **  aData,
PRBool aTerminated = nsnull 
)

NS_CStringGetData.

This function returns a const character pointer to the string's internal buffer, the length of the string, and a boolean value indicating whether or not the buffer is null-terminated.

Parameters:
aStrabstract string reference
aDataout param that will hold the address of aStr's internal buffer
aTerminatedif non-null, this out param will be set to indicate whether or not aStr's internal buffer is null- terminated
Returns:
length of aStr's internal buffer

FROZEN

Definition at line 261 of file nsStringAPI.cpp.

{
  if (aTerminated)
    *aTerminated = aStr.IsTerminated();

  nsACString::const_iterator begin;
  aStr.BeginReading(begin);
  *aData = begin.get();
  return begin.size_forward();
}

Here is the caller graph for this function:

NS_CStringGetMutableData ( nsACString &  aStr,
PRUint32  aDataLength,
char **  aData 
)

NS_CStringGetMutableData.

This function provides mutable access to a string's internal buffer. It returns a pointer to an array of characters that may be modified. The returned pointer remains valid until the string object is passed to some other string function.

Optionally, this function may be used to resize the string's internal buffer. The aDataLength parameter specifies the requested length of the string's internal buffer. By passing some value other than PR_UINT32_MAX, the caller can request that the buffer be resized to the specified number of characters before returning. The caller is not responsible for writing a null-terminator.

Parameters:
aStrabstract string reference
aDataLengthnumber of characters to resize the string's internal buffer to or PR_UINT32_MAX if no resizing is needed
aDataout param that upon return holds the address of aStr's internal buffer or null if the function failed
Returns:
number of characters or zero if the function failed

This function does not necessarily null-terminate aStr after resizing its internal buffer. The behavior depends on the implementation of the abstract string, aStr. If aStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 274 of file nsStringAPI.cpp.

{
  if (aDataLength != PR_UINT32_MAX) {
    aStr.SetLength(aDataLength);
    if (aStr.Length() != aDataLength) {
      *aData = nsnull;
      return 0;
    }
  }

  nsACString::iterator begin;
  aStr.BeginWriting(begin);
  *aData = begin.get();
  return begin.size_forward();
}

Here is the caller graph for this function:

NS_CStringSetData ( nsACString &  aStr,
const char *  aData,
PRUint32  aDataLength = PR_UINT32_MAX 
)

NS_CStringSetData.

This function copies aData into aStr.

Parameters:
aStrabstract string reference
aDatacharacter buffer
aDataLengthnumber of characters to copy from source string (pass PR_UINT32_MAX to copy until end of aData, designated by a null character)
Returns:
NS_OK if function succeeded

This function does not necessarily null-terminate aStr after copying data from aData. The behavior depends on the implementation of the abstract string, aStr. If aStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 297 of file nsStringAPI.cpp.

{
  aStr.Assign(aData, aDataLength);
  return NS_OK; // XXX report errors
}

Here is the caller graph for this function:

NS_CStringSetDataRange ( nsACString &  aStr,
PRUint32  aCutOffset,
PRUint32  aCutLength,
const char *  aData,
PRUint32  aDataLength = PR_UINT32_MAX 
)

NS_CStringSetDataRange.

This function copies aData into a section of aStr. As a result it can be used to insert new characters into the string.

Parameters:
aStrabstract string reference
aCutOffsetstarting index where the string's existing data is to be overwritten (pass PR_UINT32_MAX to cause aData to be appended to the end of aStr, in which case the value of aCutLength is ignored).
aCutLengthnumber of characters to overwrite starting at aCutOffset (pass PR_UINT32_MAX to overwrite until the end of aStr).
aDatacharacter buffer (pass null to cause this function to simply remove the "cut" range)
aDataLengthnumber of characters to copy from source string (pass PR_UINT32_MAX to copy until end of aData, designated by a null character)
Returns:
NS_OK if function succeeded

This function does not necessarily null-terminate aStr after copying data from aData. The behavior depends on the implementation of the abstract string, aStr. If aStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 304 of file nsStringAPI.cpp.

{
  if (aCutOffset == PR_UINT32_MAX)
  {
    // append case
    if (aData)
      aStr.Append(aData, aDataLength);
    return NS_OK; // XXX report errors
  }

  if (aCutLength == PR_UINT32_MAX)
    aCutLength = aStr.Length() - aCutOffset;

  if (aData)
  {
    if (aDataLength == PR_UINT32_MAX)
      aStr.Replace(aCutOffset, aCutLength, nsDependentCString(aData));
    else
      aStr.Replace(aCutOffset, aCutLength, Substring(aData, aData + aDataLength));
  }
  else
    aStr.Cut(aCutOffset, aCutLength);

  return NS_OK; // XXX report errors
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_CStringToUTF16 ( const nsACString &  aSource,
nsCStringEncoding  aSrcEncoding,
nsAString &  aDest 
)

NS_CStringToUTF16.

This function converts the characters in a nsACString to an array of UTF-16 characters, in the platform endianness. The result is stored in a nsAString object.

Parameters:
aSourceabstract string reference containing source string
aSrcEncodingcharacter encoding of the source string
aDestabstract string reference to hold the result

FROZEN

Definition at line 342 of file nsStringAPI.cpp.

{
  switch (aSrcEncoding)
  {
    case NS_CSTRING_ENCODING_ASCII:
      CopyASCIItoUTF16(aSrc, aDest);
      break;
    case NS_CSTRING_ENCODING_UTF8:
      CopyUTF8toUTF16(aSrc, aDest);
      break;
    case NS_CSTRING_ENCODING_NATIVE_FILESYSTEM:
      NS_CopyNativeToUnicode(aSrc, aDest);
      break;
    default:
      return NS_ERROR_NOT_IMPLEMENTED;
  }

  return NS_OK; // XXX report errors
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_HIDDEN_ ( nsresult  ) [inline]

NS_StringAppendData.

This routine attempts to delete a directory that may contain some files that are still in use.

Resolves a relative path string containing "." and ".." with respect to a base path (assumed to already be resolved).

NS_CStringAppendData.

This function appends data to the existing value of aStr.

Parameters:
aStrabstract string reference to be modified
aDatacharacter buffer
aDataLengthnumber of characters to append (pass PR_UINT32_MAX to append until a null-character is encountered)
Returns:
NS_OK if function succeeded

This function does not necessarily null-terminate aStr upon completion. The behavior depends on the implementation of the abstract string, aStr. If aStr is a reference to a nsStringContainer, then its data will be null- terminated by this function.

NS_StringCloneData ( const nsAString &  aStr)

NS_StringCloneData.

This function returns a null-terminated copy of the string's internal buffer.

Parameters:
aStrabstract string reference
Returns:
null-terminated copy of the string's internal buffer (it must be free'd using using nsMemory::Free)

FROZEN

Definition at line 144 of file nsStringAPI.cpp.

{
  return ToNewUnicode(aStr);
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_StringContainerFinish.

Parameters:
aContainerstring container reference

This function frees any memory owned by aContainer.

FROZEN

Definition at line 104 of file nsStringAPI.cpp.

{
  // call the nsString dtor
  NS_REINTERPRET_CAST(nsString *, &aContainer)->~nsString();
}

Here is the caller graph for this function:

NS_StringContainerInit.

Parameters:
aContainerstring container reference
Returns:
NS_OK if string container successfully initialized

This function may allocate additional memory for aContainer. When aContainer is no longer needed, NS_StringContainerFinish should be called.

FROZEN

Definition at line 47 of file nsStringAPI.cpp.

{
  NS_ASSERTION(sizeof(nsStringContainer) >= sizeof(nsString),
      "nsStringContainer is not large enough");

  // use placement new to avoid heap allocating nsString object
  new (&aContainer) nsString();

  return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_StringContainerInit2 ( nsStringContainer aContainer,
const PRUnichar aData = nsnull,
PRUint32  aDataLength = PR_UINT32_MAX,
PRUint32  aFlags = 0 
)

NS_StringContainerInit2.

Parameters:
aContainerstring container reference
aDatacharacter buffer (may be null)
aDataLengthnumber of characters stored at aData (may pass PR_UINT32_MAX if aData is null-terminated)
aFlagsflags affecting how the string container is initialized. this parameter is ignored when aData is null. otherwise, if this parameter is 0, then aData is copied into the string.

This function resembles NS_StringContainerInit but provides further options that permit more efficient memory usage. When aContainer is no longer needed, NS_StringContainerFinish should be called.

NOTE: NS_StringContainerInit2(container, nsnull, 0, 0) is equivalent to NS_StringContainerInit(container).

FROZEN

Definition at line 59 of file nsStringAPI.cpp.

{
  NS_ASSERTION(sizeof(nsStringContainer) >= sizeof(nsString),
      "nsStringContainer is not large enough");

  if (!aData)
  {
    new (&aContainer) nsString();
  }
  else
  {
    if (aDataLength == PR_UINT32_MAX)
    {
      NS_ENSURE_ARG(!(aFlags & NS_STRING_CONTAINER_INIT_SUBSTRING));
      aDataLength = nsCharTraits<PRUnichar>::length(aData);
    }

    if (aFlags & (NS_STRING_CONTAINER_INIT_DEPEND |
                  NS_STRING_CONTAINER_INIT_ADOPT))
    {
      PRUint32 flags;
      if (aFlags & NS_STRING_CONTAINER_INIT_SUBSTRING)
        flags = nsSubstring::F_NONE;
      else
        flags = nsSubstring::F_TERMINATED;

      if (aFlags & NS_STRING_CONTAINER_INIT_ADOPT)
        flags |= nsSubstring::F_OWNED;

      new (&aContainer) nsSubstring(NS_CONST_CAST(PRUnichar *, aData),
                                    aDataLength, flags);
    }
    else
    {
      new (&aContainer) nsString(aData, aDataLength);
    }
  }

  return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_StringCopy ( nsAString &  aDestStr,
const nsAString &  aSrcStr 
)

NS_StringCopy.

This function makes aDestStr have the same value as aSrcStr. It is provided as an optimization.

Parameters:
aDestStrabstract string reference to be modified
aSrcStrabstract string reference containing source string
Returns:
NS_OK if function succeeded

This function does not necessarily null-terminate aDestStr after copying data from aSrcStr. The behavior depends on the implementation of the abstract string, aDestStr. If aDestStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 186 of file nsStringAPI.cpp.

{
  aDest.Assign(aSrc);
  return NS_OK; // XXX report errors
}

Here is the caller graph for this function:

NS_StringGetData ( const nsAString &  aStr,
const PRUnichar **  aData,
PRBool aTerminated = nsnull 
)

NS_StringGetData.

This function returns a const character pointer to the string's internal buffer, the length of the string, and a boolean value indicating whether or not the buffer is null-terminated.

Parameters:
aStrabstract string reference
aDataout param that will hold the address of aStr's internal buffer
aTerminatedif non-null, this out param will be set to indicate whether or not aStr's internal buffer is null- terminated
Returns:
length of aStr's internal buffer

FROZEN

Definition at line 113 of file nsStringAPI.cpp.

{
  if (aTerminated)
    *aTerminated = aStr.IsTerminated();

  nsAString::const_iterator begin;
  aStr.BeginReading(begin);
  *aData = begin.get();
  return begin.size_forward();
}

Here is the caller graph for this function:

NS_StringGetMutableData ( nsAString &  aStr,
PRUint32  aDataLength,
PRUnichar **  aData 
)

NS_StringGetMutableData.

This function provides mutable access to a string's internal buffer. It returns a pointer to an array of characters that may be modified. The returned pointer remains valid until the string object is passed to some other string function.

Optionally, this function may be used to resize the string's internal buffer. The aDataLength parameter specifies the requested length of the string's internal buffer. By passing some value other than PR_UINT32_MAX, the caller can request that the buffer be resized to the specified number of characters before returning. The caller is not responsible for writing a null-terminator.

Parameters:
aStrabstract string reference
aDataLengthnumber of characters to resize the string's internal buffer to or PR_UINT32_MAX if no resizing is needed
aDataout param that upon return holds the address of aStr's internal buffer or null if the function failed
Returns:
number of characters or zero if the function failed

This function does not necessarily null-terminate aStr after resizing its internal buffer. The behavior depends on the implementation of the abstract string, aStr. If aStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 126 of file nsStringAPI.cpp.

{
  if (aDataLength != PR_UINT32_MAX) {
    aStr.SetLength(aDataLength);
    if (aStr.Length() != aDataLength) {
      *aData = nsnull;
      return 0;
    }
  }

  nsAString::iterator begin;
  aStr.BeginWriting(begin);
  *aData = begin.get();
  return begin.size_forward();
}

Here is the caller graph for this function:

NS_StringSetData ( nsAString &  aStr,
const PRUnichar aData,
PRUint32  aDataLength = PR_UINT32_MAX 
)

NS_StringSetData.

This function copies aData into aStr.

Parameters:
aStrabstract string reference
aDatacharacter buffer
aDataLengthnumber of characters to copy from source string (pass PR_UINT32_MAX to copy until end of aData, designated by a null character)
Returns:
NS_OK if function succeeded

This function does not necessarily null-terminate aStr after copying data from aData. The behavior depends on the implementation of the abstract string, aStr. If aStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 150 of file nsStringAPI.cpp.

{
  aStr.Assign(aData, aDataLength);
  return NS_OK; // XXX report errors
}

Here is the caller graph for this function:

NS_StringSetDataRange ( nsAString &  aStr,
PRUint32  aCutOffset,
PRUint32  aCutLength,
const PRUnichar aData,
PRUint32  aDataLength = PR_UINT32_MAX 
)

NS_StringSetDataRange.

This function copies aData into a section of aStr. As a result it can be used to insert new characters into the string.

Parameters:
aStrabstract string reference
aCutOffsetstarting index where the string's existing data is to be overwritten (pass PR_UINT32_MAX to cause aData to be appended to the end of aStr, in which case the value of aCutLength is ignored).
aCutLengthnumber of characters to overwrite starting at aCutOffset (pass PR_UINT32_MAX to overwrite until the end of aStr).
aDatacharacter buffer (pass null to cause this function to simply remove the "cut" range)
aDataLengthnumber of characters to copy from source string (pass PR_UINT32_MAX to copy until end of aData, designated by a null character)
Returns:
NS_OK if function succeeded

This function does not necessarily null-terminate aStr after copying data from aData. The behavior depends on the implementation of the abstract string, aStr. If aStr is a reference to a nsStringContainer, then its data will be null-terminated by this function.

FROZEN

Definition at line 157 of file nsStringAPI.cpp.

{
  if (aCutOffset == PR_UINT32_MAX)
  {
    // append case
    if (aData)
      aStr.Append(aData, aDataLength);
    return NS_OK; // XXX report errors
  }

  if (aCutLength == PR_UINT32_MAX)
    aCutLength = aStr.Length() - aCutOffset;

  if (aData)
  {
    if (aDataLength == PR_UINT32_MAX)
      aStr.Replace(aCutOffset, aCutLength, nsDependentString(aData));
    else
      aStr.Replace(aCutOffset, aCutLength, Substring(aData, aData + aDataLength));
  }
  else
    aStr.Cut(aCutOffset, aCutLength);

  return NS_OK; // XXX report errors
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_UTF16ToCString ( const nsAString &  aSource,
nsCStringEncoding  aDestEncoding,
nsACString &  aDest 
)

NS_UTF16ToCString.

This function converts the UTF-16 characters in a nsAString to a single-byte encoding. The result is stored in a nsACString object. In some cases this conversion may be lossy. In such cases, the conversion may succeed with a return code indicating loss of information. The exact behavior is not specified at this time.

Parameters:
aSourceabstract string reference containing source string
aDestEncodingcharacter encoding of the resulting string
aDestabstract string reference to hold the result

FROZEN

Definition at line 365 of file nsStringAPI.cpp.

{
  switch (aDestEncoding)
  {
    case NS_CSTRING_ENCODING_ASCII:
      LossyCopyUTF16toASCII(aSrc, aDest);
      break;
    case NS_CSTRING_ENCODING_UTF8:
      CopyUTF16toUTF8(aSrc, aDest);
      break;
    case NS_CSTRING_ENCODING_NATIVE_FILESYSTEM:
      NS_CopyUnicodeToNative(aSrc, aDest);
      break;
    default:
      return NS_ERROR_NOT_IMPLEMENTED;
  }

  return NS_OK; // XXX report errors
}

Here is the call graph for this function:

Here is the caller graph for this function:

const nsDependentSubstring StringHead ( const nsAString &  str,
PRUint32  count 
) [inline]

Definition at line 1672 of file nsStringAPI.h.

{
  return nsDependentSubstring(str, 0, count);
}

Here is the caller graph for this function:

const nsDependentCSubstring StringHead ( const nsACString &  str,
PRUint32  count 
) [inline]

Definition at line 1715 of file nsStringAPI.h.

{
  return nsDependentCSubstring(str, 0, count);
}
const nsDependentSubstring StringTail ( const nsAString &  str,
PRUint32  count 
) [inline]

Definition at line 1679 of file nsStringAPI.h.

{
  return nsDependentSubstring(str, str.Length() - count, count);
}

Here is the caller graph for this function:

const nsDependentCSubstring StringTail ( const nsACString &  str,
PRUint32  count 
) [inline]

Definition at line 1722 of file nsStringAPI.h.

{
  return nsDependentCSubstring(str, str.Length() - count, count);
}
const nsDependentSubstring Substring ( const nsAString &  str,
PRUint32  startPos 
) [inline]

Various nsDependentC?Substring constructor functions.

Definition at line 1644 of file nsStringAPI.h.

const nsDependentSubstring Substring ( const nsAString &  str,
PRUint32  startPos,
PRUint32  length 
) [inline]

Definition at line 1651 of file nsStringAPI.h.

const nsDependentSubstring Substring ( const PRUnichar start,
const PRUnichar end 
) [inline]

Definition at line 1658 of file nsStringAPI.h.

const nsDependentSubstring Substring ( const PRUnichar start,
PRUint32  length 
) [inline]

Definition at line 1665 of file nsStringAPI.h.

const nsDependentCSubstring Substring ( const nsACString &  str,
PRUint32  startPos 
) [inline]

Definition at line 1687 of file nsStringAPI.h.

const nsDependentCSubstring Substring ( const nsACString &  str,
PRUint32  startPos,
PRUint32  length 
) [inline]

Definition at line 1694 of file nsStringAPI.h.

const nsDependentCSubstring Substring ( const char *  start,
const char *  end 
) [inline]

Definition at line 1701 of file nsStringAPI.h.

const nsDependentCSubstring Substring ( const char *  start,
PRUint32  length 
) [inline]

Definition at line 1708 of file nsStringAPI.h.


Variable Documentation

const char* aData

Definition at line 398 of file nsStringAPI.h.

Initial value:
 PR_UINT32_MAX)
{
  return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
}


inline NS_HIDDEN_(nsresult)
NS_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
                    PRUint32 aDataLength = PR_UINT32_MAX)
{
  return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
}


inline NS_HIDDEN_(nsresult)
NS_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
{
  return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
}




class nsCStringContainer

Definition at line 399 of file nsStringAPI.h.