NS_CStringContainerInit2

Summary

The NS_CStringContainerInit2 function initializes a nsCStringContainer instance for use as a nsACString.

#include "nsStringAPI.h"
 
nsresult NS_CStringContainerInit2(
  nsCStringContainer& aContainer,
  const char* aData = nsnull,
  PRUint32 aDataLength = PR_UINT32_MAX,
  PRUint32 aFlags = 0
);

Parameters

aContainer: [in] The nsCStringContainer instance to initialize.

aData: [in] An array of characters used to initialize the string object. This parameter may be null.

aDataLength: [in] An optional parameter that specifies the length of the array pointed to by aData. Pass PR_UINT32_MAX to indicate that aData's length may be determined by scanning the string for a terminating null. If aData is null, then this parameter is ignored.

aFlags: [in] A bit-field that modifies how the string object is initialized. If this value is zero, then the array referenced by aData (if any) will be copied. Flag values are defined below.

Flag Values

The aFlags parameter is a bit-wise combination of the following values:

NS_CSTRING_CONTAINER_INIT_DEPEND: Data passed into NS_CStringContainerInit2 is not copied. Instead, the string references the passed in data pointer directly. The caller must ensure that the data is valid for the lifetime of the string container. This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT.
NS_CSTRING_CONTAINER_INIT_ADOPT: Data passed into NS_CStringContainerInit2 is not copied. Instead, the string takes ownership over the data pointer. The caller must have allocated the data array using the XPCOM memory allocator. This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND.
NS_CSTRING_CONTAINER_INIT_SUBSTRING: Data passed into NS_CStringContainerInit2 is a substring that is not null-terminated.

Return Values

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

Remarks

After a nsCStringContainer object has been initialized via NS_CStringContainerInit2, it may be used as an ordinary nsACString object. When the string object is no longer needed, it should be passed to NS_CStringContainerFinish to free any extra memory that the string object may have allocated.

It is generally better to use one of the helper classes, such as nsCString, instead of coding directly to NS_CStringContainerInit2 because those classes take care of cleaning up the string object when it goes out of scope.

When NS_CStringContainerInit2 is told to copy aData, the copy it creates is null-terminated. This is significant as it allows the programmer to be certain that NS_CStringGetData will return a null-terminated character array.

The NS_CStringContainerInit function is equivalent to calling NS_CStringContainerInit with aData=nsnull and aFlags=0.

History

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