NS_CStringGetMutableData

Summary

The NS_CStringGetMutableData function gives the caller write access to the string's internal buffer.

#include "nsStringAPI.h"
 
PRUint32 NS_CStringGetMutableData(
  nsACString& aString,
  PRUint32 aDataLength,
  char** aData
);

Parameters

aString: [in] A nsACString instance to modify.
aDataLength: [in] The number of characters to resize the string's internal buffer to or PR_UINT32_MAX to return the buffer as-is.
aData: [out] Upon return, if the function was successful, then *aData references the string's internal buffer.

Return Values

This function returns the number of characters contained in the string's internal buffer (excluding any null-terminator). This value will be zero if the function failed to resize its internal buffer to the size requested.

Remarks

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

This function does not necessarily null-terminate aString's internal buffer after resizing it. That behavior depends on the implementation of aString. If aString is a reference to a nsCStringContainer, then its data will be null-terminated by this function. The caller is not responsible for writing a null-terminator.

Example

// Convert any uppercase ASCII letters to lowercase
void ToLowerCase(nsCString &str)
{
  char *iter;
  PRUint32 len = NS_CStringGetMutableData(str, PR_UINT32_MAX, &iter);
  char *end = iter + len;
  while (iter != end) {
    char c = *iter;
    if (c >= 'A' && c <= 'Z')
      *iter = c + ('a' - 'A');
    ++iter;
  }
}

History

This function was finalized for Mozilla 1.8. See bug 288786 for details.