nsStringAPI.h revision 754899d3e29037e1a3cde20437768a6da3c50527
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* vim:set ts=2 sw=2 et cindent: */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ***** BEGIN LICENSE BLOCK *****
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Version: MPL 1.1/GPL 2.0/LGPL 2.1
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The contents of this file are subject to the Mozilla Public License Version
45e9809aff7304721fddb95654901b32195c9c7avboxsync * 1.1 (the "License"); you may not use this file except in compliance with
45e9809aff7304721fddb95654901b32195c9c7avboxsync * the License. You may obtain a copy of the License at
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Software distributed under the License is distributed on an "AS IS" basis,
45e9809aff7304721fddb95654901b32195c9c7avboxsync * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
45e9809aff7304721fddb95654901b32195c9c7avboxsync * for the specific language governing rights and limitations under the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The Original Code is Mozilla.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The Initial Developer of the Original Code is IBM Corporation.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Portions created by IBM Corporation are Copyright (C) 2003
45e9809aff7304721fddb95654901b32195c9c7avboxsync * IBM Corporation. All Rights Reserved.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Contributor(s):
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Darin Fisher <darin@meer.net>
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Alternatively, the contents of this file may be used under the terms of
45e9809aff7304721fddb95654901b32195c9c7avboxsync * either the GNU General Public License Version 2 or later (the "GPL"), or
45e9809aff7304721fddb95654901b32195c9c7avboxsync * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
45e9809aff7304721fddb95654901b32195c9c7avboxsync * in which case the provisions of the GPL or the LGPL are applicable instead
45e9809aff7304721fddb95654901b32195c9c7avboxsync * of those above. If you wish to allow use of your version of this file only
45e9809aff7304721fddb95654901b32195c9c7avboxsync * under the terms of either the GPL or the LGPL, and not to allow others to
45e9809aff7304721fddb95654901b32195c9c7avboxsync * use your version of this file under the terms of the MPL, indicate your
45e9809aff7304721fddb95654901b32195c9c7avboxsync * decision by deleting the provisions above and replace them with the notice
45e9809aff7304721fddb95654901b32195c9c7avboxsync * and other provisions required by the GPL or the LGPL. If you do not delete
45e9809aff7304721fddb95654901b32195c9c7avboxsync * the provisions above, a recipient may use your version of this file under
45e9809aff7304721fddb95654901b32195c9c7avboxsync * the terms of any one of the MPL, the GPL or the LGPL.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * ***** END LICENSE BLOCK ***** */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This file describes a minimal API for working with XPCOM's abstract
45e9809aff7304721fddb95654901b32195c9c7avboxsync * string classes. It divorces the consumer from having any run-time
45e9809aff7304721fddb95654901b32195c9c7avboxsync * dependency on the implementation details of the abstract string types.
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringContainerInit VBoxNsxpNS_CStringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringContainerFinish VBoxNsxpNS_CStringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringCloneData VBoxNsxpNS_CStringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringSetDataRange VBoxNsxpNS_CStringSetDataRange
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringContainerInit VBoxNsxpNS_StringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringContainerFinish VBoxNsxpNS_StringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringCloneData VBoxNsxpNS_StringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringSetDataRange VBoxNsxpNS_StringSetDataRange
45e9809aff7304721fddb95654901b32195c9c7avboxsync#endif /* VBOX_WITH_XPCOM_NAMESPACE_CLEANUP */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* The base string types */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringContainer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This is an opaque data type that is large enough to hold the canonical
45e9809aff7304721fddb95654901b32195c9c7avboxsync * implementation of nsAString. The binary structure of this class is an
45e9809aff7304721fddb95654901b32195c9c7avboxsync * implementation detail.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The string data stored in a string container is always single fragment
45e9809aff7304721fddb95654901b32195c9c7avboxsync * and null-terminated.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Typically, string containers are allocated on the stack for temporary
45e9809aff7304721fddb95654901b32195c9c7avboxsync * use. However, they can also be malloc'd if necessary. In either case,
45e9809aff7304721fddb95654901b32195c9c7avboxsync * a string container is not useful until it has been initialized with a
45e9809aff7304721fddb95654901b32195c9c7avboxsync * call to NS_StringContainerInit. The following example shows how to use
45e9809aff7304721fddb95654901b32195c9c7avboxsync * a string container to call a function that takes a |nsAString &| out-param.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_METHOD GetBlah(nsAString &aBlah);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult MyCode()
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringContainer sc;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = NS_StringContainerInit(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * if (NS_FAILED(rv))
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = GetBlah(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * if (NS_SUCCEEDED(rv))
45e9809aff7304721fddb95654901b32195c9c7avboxsync * const PRUnichar *data;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringGetData(sc, &data);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * // |data| now points to the result of the GetBlah function
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerFinish(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The following example show how to use a string container to pass a string
45e9809aff7304721fddb95654901b32195c9c7avboxsync * parameter to a function taking a |const nsAString &| in-param.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_METHOD SetBlah(const nsAString &aBlah);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult MyCode()
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringContainer sc;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = NS_StringContainerInit(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * if (NS_FAILED(rv))
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * const PRUnichar kData[] = {'x','y','z','\0'};
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = NS_StringSetData(sc, kData, sizeof(kData)/2 - 1);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * if (NS_SUCCEEDED(rv))
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = SetBlah(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerFinish(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if string container successfully initialized
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function may allocate additional memory for aContainer. When
45e9809aff7304721fddb95654901b32195c9c7avboxsync * aContainer is no longer needed, NS_StringContainerFinish should be called.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringContainerInit(nsStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function frees any memory owned by aContainer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringContainerFinish(nsStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function returns a const character pointer to the string's internal
45e9809aff7304721fddb95654901b32195c9c7avboxsync * buffer, the length of the string, and a boolean value indicating whether
45e9809aff7304721fddb95654901b32195c9c7avboxsync * or not the buffer is null-terminated.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aData out param that will hold the address of aStr's
45e9809aff7304721fddb95654901b32195c9c7avboxsync * internal buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aTerminated if non-null, this out param will be set to indicate
45e9809aff7304721fddb95654901b32195c9c7avboxsync * whether or not aStr's internal buffer is null-
45e9809aff7304721fddb95654901b32195c9c7avboxsync * terminated
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return length of aStr's internal buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function returns a null-terminated copy of the string's
45e9809aff7304721fddb95654901b32195c9c7avboxsync * internal buffer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return null-terminated copy of the string's internal buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * (it must be free'd using using nsMemory::Free)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function copies aData into aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aData character buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aDataLength number of characters to copy from source string (pass
45e9809aff7304721fddb95654901b32195c9c7avboxsync * PR_UINT32_MAX to copy until end of aData, designated by
45e9809aff7304721fddb95654901b32195c9c7avboxsync * a null character)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if function succeeded
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function does not necessarily null-terminate aStr after copying data
45e9809aff7304721fddb95654901b32195c9c7avboxsync * from aData. The behavior depends on the implementation of the abstract
45e9809aff7304721fddb95654901b32195c9c7avboxsync * string, aStr. If aStr is a reference to a nsStringContainer, then its data
45e9809aff7304721fddb95654901b32195c9c7avboxsync * will be null-terminated by this function.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringSetDataRange
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function copies aData into a section of aStr. As a result it can be
45e9809aff7304721fddb95654901b32195c9c7avboxsync * used to insert new characters into the string.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aCutOffset starting index where the string's existing data
45e9809aff7304721fddb95654901b32195c9c7avboxsync * is to be overwritten (pass PR_UINT32_MAX to cause
45e9809aff7304721fddb95654901b32195c9c7avboxsync * aData to be appended to the end of aStr, in which
45e9809aff7304721fddb95654901b32195c9c7avboxsync * case the value of aCutLength is ignored).
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aCutLength number of characters to overwrite starting at
45e9809aff7304721fddb95654901b32195c9c7avboxsync * aCutOffset (pass PR_UINT32_MAX to overwrite until the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * end of aStr).
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aData character buffer (pass null to cause this function
45e9809aff7304721fddb95654901b32195c9c7avboxsync * to simply remove the "cut" range)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aDataLength number of characters to copy from source string (pass
45e9809aff7304721fddb95654901b32195c9c7avboxsync * PR_UINT32_MAX to copy until end of aData, designated by
45e9809aff7304721fddb95654901b32195c9c7avboxsync * a null character)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if function succeeded
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function does not necessarily null-terminate aStr after copying data
45e9809aff7304721fddb95654901b32195c9c7avboxsync * from aData. The behavior depends on the implementation of the abstract
45e9809aff7304721fddb95654901b32195c9c7avboxsync * string, aStr. If aStr is a reference to a nsStringContainer, then its data
45e9809aff7304721fddb95654901b32195c9c7avboxsync * will be null-terminated by this function.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
45e9809aff7304721fddb95654901b32195c9c7avboxsync const PRUnichar *aData, PRUint32 aDataLength = PR_UINT32_MAX);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringCopy
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function makes aDestStr have the same value as aSrcStr. It is
45e9809aff7304721fddb95654901b32195c9c7avboxsync * provided as an optimization.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aDestStr abstract string reference to be modified
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aSrcStr abstract string reference containing source string
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if function succeeded
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function does not necessarily null-terminate aDestStr after copying
45e9809aff7304721fddb95654901b32195c9c7avboxsync * data from aSrcStr. The behavior depends on the implementation of the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * abstract string, aDestStr. If aDestStr is a reference to a
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringContainer, then its data will be null-terminated by this function.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringAppendData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function appends data to the existing value of aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference to be modified
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aData character buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aDataLength number of characters to append (pass PR_UINT32_MAX to
45e9809aff7304721fddb95654901b32195c9c7avboxsync * append until a null-character is encountered)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if function succeeded
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function does not necessarily null-terminate aStr upon completion.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The behavior depends on the implementation of the abstract string, aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * If aStr is a reference to a nsStringContainer, then its data will be null-
45e9809aff7304721fddb95654901b32195c9c7avboxsync * terminated by this function.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringAppendData(nsAString &aStr, const PRUnichar *aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringInsertData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function inserts data into the existing value of aStr at the specified
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference to be modified
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aOffset specifies where in the string to insert aData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aData character buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aDataLength number of characters to append (pass PR_UINT32_MAX to
45e9809aff7304721fddb95654901b32195c9c7avboxsync * append until a null-character is encountered)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if function succeeded
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function does not necessarily null-terminate aStr upon completion.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The behavior depends on the implementation of the abstract string, aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * If aStr is a reference to a nsStringContainer, then its data will be null-
45e9809aff7304721fddb95654901b32195c9c7avboxsync * terminated by this function.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringCutData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function shortens the existing value of aStr, by removing characters
45e9809aff7304721fddb95654901b32195c9c7avboxsync * at the specified offset.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference to be modified
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aCutOffset specifies where in the string to insert aData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aCutLength number of characters to remove
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if function succeeded
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
45e9809aff7304721fddb95654901b32195c9c7avboxsync return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsCStringContainer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This is an opaque data type that is large enough to hold the canonical
45e9809aff7304721fddb95654901b32195c9c7avboxsync * implementation of nsACString. The binary structure of this class is an
45e9809aff7304721fddb95654901b32195c9c7avboxsync * implementation detail.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The string data stored in a string container is always single fragment
45e9809aff7304721fddb95654901b32195c9c7avboxsync * and null-terminated.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @see nsStringContainer for use cases and further documentation.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if string container successfully initialized
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function may allocate additional memory for aContainer. When
45e9809aff7304721fddb95654901b32195c9c7avboxsync * aContainer is no longer needed, NS_CStringContainerFinish should be called.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_CStringContainerInit(nsCStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function frees any memory owned by aContainer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_CStringContainerFinish(nsCStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function returns a const character pointer to the string's internal
45e9809aff7304721fddb95654901b32195c9c7avboxsync * buffer, the length of the string, and a boolean value indicating whether
45e9809aff7304721fddb95654901b32195c9c7avboxsync * or not the buffer is null-terminated.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aData out param that will hold the address of aStr's
45e9809aff7304721fddb95654901b32195c9c7avboxsync * internal buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aTerminated if non-null, this out param will be set to indicate
45e9809aff7304721fddb95654901b32195c9c7avboxsync * whether or not aStr's internal buffer is null-
45e9809aff7304721fddb95654901b32195c9c7avboxsync * terminated
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return length of aStr's internal buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function returns a null-terminated copy of the string's
45e9809aff7304721fddb95654901b32195c9c7avboxsync * internal buffer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return null-terminated copy of the string's internal buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * (it must be free'd using using nsMemory::Free)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function copies aData into aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aStr abstract string reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aData character buffer
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aDataLength number of characters to copy from source string (pass
45e9809aff7304721fddb95654901b32195c9c7avboxsync * PR_UINT32_MAX to copy until end of aData, designated by
45e9809aff7304721fddb95654901b32195c9c7avboxsync * a null character)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if function succeeded
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function does not necessarily null-terminate aStr after copying data
45e9809aff7304721fddb95654901b32195c9c7avboxsync * from aData. The behavior depends on the implementation of the abstract
45e9809aff7304721fddb95654901b32195c9c7avboxsync * string, aStr. If aStr is a reference to a nsStringContainer, then its data
45e9809aff7304721fddb95654901b32195c9c7avboxsync * will be null-terminated by this function.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
enum nsCStringEncoding {
* internal definition of these classes from nsAString.h in the Mozilla tree.
#ifndef NS_STRINGAPI_IMPL
#ifndef NS_STRINGAPI_IMPL
return data;
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) ) { Replace(size_type(-1), 0, data, length); }
NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) ) { Replace(pos, 0, data, length); }
NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength ) { Replace(cutStart, cutLength, nsnull, 0); }
#ifndef NS_STRINGAPI_IMPL
typedef char char_type;
return data;
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) ) { Replace(size_type(-1), 0, data, length); }
NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) ) { Replace(pos, 0, data, length); }
NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength ) { Replace(cutStart, cutLength, nsnull, 0); }
void *d1;
void *d3;
void *d1;
void *d3;