NS_StringContainerInit

Summary

The NS_StringContainerInit function initializes a nsStringContainer instance for use as a nsAString. This is a low-level API.

  #include "nsStringAPI.h"

  nsresult NS_StringContainerInit(
    nsStringContainer& aString
  );

Parameters

aString: [in] A nsStringContainer instance to be initialized.

Return Values

The NS_StringContainerInit function returns NS_OK if successful. Otherwise, it returns an error code.

Remarks

The nsStringContainer structure has unspecified size and layout. Its members may not be accessed directly.

After a nsStringContainer object has been initialized, it may be used as an ordinary nsAString object.

The internal buffer allocated by a nsStringContainer is always null-terminated.

With NS_StringContainerInit, the coder is required to call NS_StringContainerFinish when done with the nsStringContainer object. Therefore, it is generally better to use nsEmbedString, to instantiate a nsAString object, since it automatically releases allocated memory when the object goes out of scope.

Example Code

  nsStringContainer str;
  if (NS_SUCCEEDED(NS_StringContainerInit(str)))
  {
    // Now, |str| can be used with any function taking a nsAString parameter.

    // Be sure to call this function to release any memory owned by |str| when done.
    NS_StringContainerFinish(str);
  }

History

This function was frozen for Mozilla 1.7. See bug 239123 for details.