Back to index

lightning-sunbird  0.9+nobinonly
Functions
nsStringAPI.cpp File Reference
#include "nsString.h"
#include "nsCharTraits.h"
#include "nsStringAPI.h"
#include "nsNativeCharsetUtils.h"

Go to the source code of this file.

Functions

 NS_StringContainerInit (nsStringContainer &aContainer)
 NS_StringContainerInit.
 NS_StringContainerInit2 (nsStringContainer &aContainer, const PRUnichar *aData, PRUint32 aDataLength, PRUint32 aFlags)
 NS_StringContainerInit2.
 NS_StringContainerFinish (nsStringContainer &aContainer)
 NS_StringContainerFinish.
 NS_StringGetData (const nsAString &aStr, const PRUnichar **aData, PRBool *aTerminated)
 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)
 NS_StringSetData.
 NS_StringSetDataRange (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength, const PRUnichar *aData, PRUint32 aDataLength)
 NS_StringSetDataRange.
 NS_StringCopy (nsAString &aDest, const nsAString &aSrc)
 NS_StringCopy.
 NS_CStringContainerInit (nsCStringContainer &aContainer)
 NS_CStringContainerInit.
 NS_CStringContainerInit2 (nsCStringContainer &aContainer, const char *aData, PRUint32 aDataLength, PRUint32 aFlags)
 NS_CStringContainerInit2.
 NS_CStringContainerFinish (nsCStringContainer &aContainer)
 NS_CStringContainerFinish.
 NS_CStringGetData (const nsACString &aStr, const char **aData, PRBool *aTerminated)
 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)
 NS_CStringSetData.
 NS_CStringSetDataRange (nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength, const char *aData, PRUint32 aDataLength)
 NS_CStringSetDataRange.
 NS_CStringCopy (nsACString &aDest, const nsACString &aSrc)
 NS_CStringCopy.
 NS_CStringToUTF16 (const nsACString &aSrc, nsCStringEncoding aSrcEncoding, nsAString &aDest)
 NS_CStringToUTF16.
 NS_UTF16ToCString (const nsAString &aSrc, nsCStringEncoding aDestEncoding, nsACString &aDest)
 NS_UTF16ToCString.

Function Documentation

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 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 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 caller graph for 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 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 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 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 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 caller graph for this function: