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 withNS_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.