mozilla
Your Search Results

    NS_CStringGetMutableData

    « XPCOM API Reference

    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.

    See Also

    NS_CStringGetData

    Document Tags and Contributors

    Contributors to this page: Sheppy, Nickolay, Pmash, DarinFisher, newacct
    Last updated by: Sheppy,