NS_CStringGetMutableData

  • Revision slug: NS_CStringGetMutableData
  • Revision title: NS_CStringGetMutableData
  • Revision id: 287404
  • Created:
  • Creator: newacct
  • Is current revision? Yes
  • Comment 4 words added

Revision Content

{{ Xpcomapi() }}

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
{{ mediawiki.external('in') }} A nsACString instance to modify.
aDataLength
{{ mediawiki.external('in') }} The number of characters to resize the string's internal buffer to or PR_UINT32_MAX to return the buffer as-is.
aData
{{ mediawiki.external('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

Revision Source

<p>{{ Xpcomapi() }}</p>
<h3 id="Summary" name="Summary">Summary</h3>
<p>The <code>NS_CStringGetMutableData</code> function gives the caller write access to the string's internal buffer.</p>
<pre class="eval">#include "nsStringAPI.h"
 
PRUint32 NS_CStringGetMutableData(
  nsACString&amp; <var>aString</var>,
  PRUint32 <var>aDataLength</var>,
  char** <var>aData</var>
);
</pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl> <dt>aString</dt> <dd>{{ mediawiki.external('in') }} A <code><a href="/en/nsACString" title="en/nsACString">nsACString</a></code> instance to modify.</dd> <dt>aDataLength</dt> <dd>{{ mediawiki.external('in') }} The number of characters to resize the string's internal buffer to or <code>PR_UINT32_MAX</code> to return the buffer as-is.</dd> <dt>aData</dt> <dd>{{ mediawiki.external('out') }} Upon return, if the function was successful, then <var>*aData</var> references the string's internal buffer.</dd>
</dl>
<h3 id="Return_Values" name="Return_Values">Return Values</h3>
<p>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.</p>
<h3 id="Remarks" name="Remarks">Remarks</h3>
<p>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.</p>
<p>This function does not necessarily null-terminate <var>aString</var>'s internal buffer after resizing it. That behavior depends on the implementation of <var>aString</var>. If <var>aString</var> is a reference to a <code><a href="/en/NsCStringContainer" title="en/NsCStringContainer">nsCStringContainer</a></code>, then its data will be null-terminated by this function. The caller is not responsible for writing a null-terminator.</p>
<h3 id="Example" name="Example">Example</h3>
<pre>// Convert any uppercase ASCII letters to lowercase
void ToLowerCase(nsCString &amp;str)
{
  char *iter;
  PRUint32 len = NS_CStringGetMutableData(str, PR_UINT32_MAX, &amp;iter);

  char *end = iter + len;
  while (iter != end) {
    char c = *iter;
    if (c &gt;= 'A' &amp;&amp; c &lt;= 'Z')
      *iter = c + ('a' - 'A');
    ++iter;
  }
}
</pre>
<h3 id="History" name="History">History</h3>
<p>This function was finalized for Mozilla 1.8. See {{ Bug(288786) }} for details.</p>
<h3 id="See_Also" name="See_Also">See Also</h3>
<p><code><a href="/en/NS_CStringGetData" title="en/NS_CStringGetData">NS_CStringGetData</a></code></p>
Revert to this revision