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 *
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 * http://www.mozilla.org/MPL/
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 * License.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The Original Code is Mozilla.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Contributor(s):
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Darin Fisher <darin@meer.net>
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * ***** END LICENSE BLOCK ***** */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#ifndef nsStringAPI_h__
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define nsStringAPI_h__
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringAPI.h
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#include "nscore.h"
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#ifdef VBOX_WITH_XPCOM_NAMESPACE_CLEANUP
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringContainerInit VBoxNsxpNS_CStringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringContainerFinish VBoxNsxpNS_CStringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringCloneData VBoxNsxpNS_CStringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringCopy VBoxNsxpNS_CStringCopy
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringGetData VBoxNsxpNS_CStringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringSetData VBoxNsxpNS_CStringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringSetDataRange VBoxNsxpNS_CStringSetDataRange
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_UTF16ToCString VBoxNsxpNS_UTF16ToCString
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_CStringToUTF16 VBoxNsxpNS_CStringToUTF16
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringContainerInit VBoxNsxpNS_StringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringContainerFinish VBoxNsxpNS_StringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringCloneData VBoxNsxpNS_StringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringCopy VBoxNsxpNS_StringCopy
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringGetData VBoxNsxpNS_StringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringSetData VBoxNsxpNS_StringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_StringSetDataRange VBoxNsxpNS_StringSetDataRange
45e9809aff7304721fddb95654901b32195c9c7avboxsync#endif /* VBOX_WITH_XPCOM_NAMESPACE_CLEANUP */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define NS_STRINGAPI(x) extern "C" NS_COM x
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* The base string types */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncclass nsAString;
45e9809aff7304721fddb95654901b32195c9c7avboxsyncclass nsACString;
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringContainer
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The string data stored in a string container is always single fragment
45e9809aff7304721fddb95654901b32195c9c7avboxsync * and null-terminated.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_METHOD GetBlah(nsAString &aBlah);
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult MyCode()
45e9809aff7304721fddb95654901b32195c9c7avboxsync * {
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringContainer sc;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = NS_StringContainerInit(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * if (NS_FAILED(rv))
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = GetBlah(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * if (NS_SUCCEEDED(rv))
45e9809aff7304721fddb95654901b32195c9c7avboxsync * {
45e9809aff7304721fddb95654901b32195c9c7avboxsync * const PRUnichar *data;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringGetData(sc, &data);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * //
45e9809aff7304721fddb95654901b32195c9c7avboxsync * // |data| now points to the result of the GetBlah function
45e9809aff7304721fddb95654901b32195c9c7avboxsync * //
45e9809aff7304721fddb95654901b32195c9c7avboxsync * }
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerFinish(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * }
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_METHOD SetBlah(const nsAString &aBlah);
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult MyCode()
45e9809aff7304721fddb95654901b32195c9c7avboxsync * {
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsresult rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsStringContainer sc;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * rv = NS_StringContainerInit(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * if (NS_FAILED(rv))
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerFinish(sc);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * return rv;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * }
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncclass nsStringContainer;
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if string container successfully initialized
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function may allocate additional memory for aContainer. When
45e9809aff7304721fddb95654901b32195c9c7avboxsync * aContainer is no longer needed, NS_StringContainerFinish should be called.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringContainerInit(nsStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function frees any memory owned by aContainer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(void)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringContainerFinish(nsStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(PRUint32)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync (const nsAString &aStr, const PRUnichar **aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync PRBool *aTerminated = nsnull);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function returns a null-terminated copy of the string's
45e9809aff7304721fddb95654901b32195c9c7avboxsync * internal buffer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(PRUnichar *)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync (const nsAString &aStr);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function copies aData into aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync (nsAString &aStr, const PRUnichar *aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync PRUint32 aDataLength = PR_UINT32_MAX);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringSetDataRange
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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 *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringSetDataRange
45e9809aff7304721fddb95654901b32195c9c7avboxsync (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
45e9809aff7304721fddb95654901b32195c9c7avboxsync const PRUnichar *aData, PRUint32 aDataLength = PR_UINT32_MAX);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringCopy
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function makes aDestStr have the same value as aSrcStr. It is
45e9809aff7304721fddb95654901b32195c9c7avboxsync * provided as an optimization.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringCopy
45e9809aff7304721fddb95654901b32195c9c7avboxsync (nsAString &aDestStr, const nsAString &aSrcStr);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringAppendData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function appends data to the existing value of aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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.
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncinline NS_HIDDEN_(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringAppendData(nsAString &aStr, const PRUnichar *aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync PRUint32 aDataLength = PR_UINT32_MAX)
45e9809aff7304721fddb95654901b32195c9c7avboxsync{
45e9809aff7304721fddb95654901b32195c9c7avboxsync return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
45e9809aff7304721fddb95654901b32195c9c7avboxsync}
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringInsertData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function inserts data into the existing value of aStr at the specified
45e9809aff7304721fddb95654901b32195c9c7avboxsync * offset.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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.
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncinline NS_HIDDEN_(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync PRUint32 aDataLength = PR_UINT32_MAX)
45e9809aff7304721fddb95654901b32195c9c7avboxsync{
45e9809aff7304721fddb95654901b32195c9c7avboxsync return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
45e9809aff7304721fddb95654901b32195c9c7avboxsync}
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_StringCutData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function shortens the existing value of aStr, by removing characters
45e9809aff7304721fddb95654901b32195c9c7avboxsync * at the specified offset.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncinline NS_HIDDEN_(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
45e9809aff7304721fddb95654901b32195c9c7avboxsync{
45e9809aff7304721fddb95654901b32195c9c7avboxsync return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
45e9809aff7304721fddb95654901b32195c9c7avboxsync}
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * nsCStringContainer
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The string data stored in a string container is always single fragment
45e9809aff7304721fddb95654901b32195c9c7avboxsync * and null-terminated.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @see nsStringContainer for use cases and further documentation.
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncclass nsCStringContainer;
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringContainerInit
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @return NS_OK if string container successfully initialized
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function may allocate additional memory for aContainer. When
45e9809aff7304721fddb95654901b32195c9c7avboxsync * aContainer is no longer needed, NS_CStringContainerFinish should be called.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_CStringContainerInit(nsCStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringContainerFinish
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param aContainer string container reference
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function frees any memory owned by aContainer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(void)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_CStringContainerFinish(nsCStringContainer &aContainer);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/* ------------------------------------------------------------------------- */
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(PRUint32)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_CStringGetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync (const nsACString &aStr, const char **aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync PRBool *aTerminated = nsnull);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function returns a null-terminated copy of the string's
45e9809aff7304721fddb95654901b32195c9c7avboxsync * internal buffer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(char *)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_CStringCloneData
45e9809aff7304721fddb95654901b32195c9c7avboxsync (const nsACString &aStr);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
45e9809aff7304721fddb95654901b32195c9c7avboxsync/**
45e9809aff7304721fddb95654901b32195c9c7avboxsync * NS_CStringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This function copies aData into aStr.
45e9809aff7304721fddb95654901b32195c9c7avboxsync *
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 *
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 *
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @status FROZEN
45e9809aff7304721fddb95654901b32195c9c7avboxsync */
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_STRINGAPI(nsresult)
45e9809aff7304721fddb95654901b32195c9c7avboxsyncNS_CStringSetData
45e9809aff7304721fddb95654901b32195c9c7avboxsync (nsACString &aStr, const char *aData,
45e9809aff7304721fddb95654901b32195c9c7avboxsync PRUint32 aDataLength = PR_UINT32_MAX);
45e9809aff7304721fddb95654901b32195c9c7avboxsync
/**
* NS_CStringSetDataRange
*
* This function copies aData into a section of aStr. As a result it can be
* used to insert new characters into the string.
*
* @param aStr abstract string reference
* @param aCutOffset starting index where the string's existing data
* is to be overwritten (pass PR_UINT32_MAX to cause
* aData to be appended to the end of aStr, in which
* case the value of aCutLength is ignored).
* @param aCutLength number of characters to overwrite starting at
* aCutOffset (pass PR_UINT32_MAX to overwrite until the
* end of aStr).
* @param aData character buffer (pass null to cause this function
* to simply remove the "cut" range)
* @param aDataLength number of characters to copy from source string (pass
* PR_UINT32_MAX to copy until end of aData, designated by
* a null character)
* @return NS_OK if function succeeded
*
* This function does not necessarily null-terminate aStr after copying data
* from aData. The behavior depends on the implementation of the abstract
* string, aStr. If aStr is a reference to a nsStringContainer, then its data
* will be null-terminated by this function.
*
* @status FROZEN
*/
NS_STRINGAPI(nsresult)
NS_CStringSetDataRange
(nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
const char *aData, PRUint32 aDataLength = PR_UINT32_MAX);
/**
* NS_CStringCopy
*
* This function makes aDestStr have the same value as aSrcStr. It is
* provided as an optimization.
*
* @param aDestStr abstract string reference to be modified
* @param aSrcStr abstract string reference containing source string
* @return NS_OK if function succeeded
*
* This function does not necessarily null-terminate aDestStr after copying
* data from aSrcStr. The behavior depends on the implementation of the
* abstract string, aDestStr. If aDestStr is a reference to a
* nsStringContainer, then its data will be null-terminated by this function.
*
* @status FROZEN
*/
NS_STRINGAPI(nsresult)
NS_CStringCopy
(nsACString &aDestStr, const nsACString &aSrcStr);
/**
* NS_CStringAppendData
*
* This function appends data to the existing value of aStr.
*
* @param aStr abstract string reference to be modified
* @param aData character buffer
* @param aDataLength number of characters to append (pass PR_UINT32_MAX to
* append until a null-character is encountered)
* @return NS_OK if function succeeded
*
* This function does not necessarily null-terminate aStr upon completion.
* The behavior depends on the implementation of the abstract string, aStr.
* If aStr is a reference to a nsStringContainer, then its data will be null-
* terminated by this function.
*/
inline NS_HIDDEN_(nsresult)
NS_CStringAppendData(nsACString &aStr, const char *aData,
PRUint32 aDataLength = PR_UINT32_MAX)
{
return NS_CStringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
}
/**
* NS_CStringInsertData
*
* This function inserts data into the existing value of aStr at the specified
* offset.
*
* @param aStr abstract string reference to be modified
* @param aOffset specifies where in the string to insert aData
* @param aData character buffer
* @param aDataLength number of characters to append (pass PR_UINT32_MAX to
* append until a null-character is encountered)
* @return NS_OK if function succeeded
*
* This function does not necessarily null-terminate aStr upon completion.
* The behavior depends on the implementation of the abstract string, aStr.
* If aStr is a reference to a nsStringContainer, then its data will be null-
* terminated by this function.
*/
inline NS_HIDDEN_(nsresult)
NS_CStringInsertData(nsACString &aStr, PRUint32 aOffset, const char *aData,
PRUint32 aDataLength = PR_UINT32_MAX)
{
return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
}
/**
* NS_CStringCutData
*
* This function shortens the existing value of aStr, by removing characters
* at the specified offset.
*
* @param aStr abstract string reference to be modified
* @param aCutOffset specifies where in the string to insert aData
* @param aCutLength number of characters to remove
* @return NS_OK if function succeeded
*/
inline NS_HIDDEN_(nsresult)
NS_CStringCutData(nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
{
return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
}
/* ------------------------------------------------------------------------- */
/**
* Encodings that can be used with the following conversion routines.
*/
enum nsCStringEncoding {
/* Conversion between ASCII and UTF-16 assumes that all bytes in the source
* string are 7-bit ASCII and can be inflated to UTF-16 by inserting null
* bytes. Reverse conversion is done by truncating every other byte. The
* conversion may result in loss and/or corruption of information if the
* strings do not strictly contain ASCII data. */
NS_CSTRING_ENCODING_ASCII = 0,
/* Conversion between UTF-8 and UTF-16 is non-lossy. */
NS_CSTRING_ENCODING_UTF8 = 1,
/* Conversion from UTF-16 to the native filesystem charset may result in a
* loss of information. No attempt is made to protect against data loss in
* this case. The native filesystem charset applies to strings passed to
* the "Native" method variants on nsIFile and nsILocalFile. */
NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2
};
/**
* NS_CStringToUTF16
*
* This function converts the characters in a nsACString to an array of UTF-16
* characters, in the platform endianness. The result is stored in a nsAString
* object.
*
* @param aSource abstract string reference containing source string
* @param aSrcEncoding character encoding of the source string
* @param aDest abstract string reference to hold the result
*
* @status FROZEN
*/
NS_STRINGAPI(nsresult)
NS_CStringToUTF16(const nsACString &aSource, nsCStringEncoding aSrcEncoding,
nsAString &aDest);
/**
* NS_UTF16ToCString
*
* This function converts the UTF-16 characters in a nsAString to a single-byte
* encoding. The result is stored in a nsACString object. In some cases this
* conversion may be lossy. In such cases, the conversion may succeed with a
* return code indicating loss of information. The exact behavior is not
* specified at this time.
*
* @param aSource abstract string reference containing source string
* @param aDestEncoding character encoding of the resulting string
* @param aDest abstract string reference to hold the result
*
* @status FROZEN
*/
NS_STRINGAPI(nsresult)
NS_UTF16ToCString(const nsAString &aSource, nsCStringEncoding aDestEncoding,
nsACString &aDest);
/* ------------------------------------------------------------------------- */
/**
* Below we define nsAString and nsACString. The "_external" suffix is an
* implementation detail. nsAString_external is the name of the external
* representation of nsAString from the point of view of the Mozilla codebase.
* To a user of this API, nsAString_external is exactly nsAString.
*
* These classes should be treated as abstract classes with unspecified
* structure. The inline methods are provided as helper functions around the
* C-style API provided above.
*
* Do not try to mix these definitions of nsAString and nsACString with the
* internal definition of these classes from nsAString.h in the Mozilla tree.
*/
#ifndef NS_STRINGAPI_IMPL
#define nsAString_external nsAString
#define nsACString_external nsACString
#endif
class nsAString_external
{
#ifndef NS_STRINGAPI_IMPL
public:
typedef PRUnichar char_type;
typedef nsAString_external self_type;
typedef PRUint32 size_type;
typedef PRUint32 index_type;
NS_HIDDEN_(const char_type*) BeginReading() const
{
const char_type *data;
NS_StringGetData(*this, &data);
return data;
}
NS_HIDDEN_(const char_type*) EndReading() const
{
const char_type *data;
PRUint32 len = NS_StringGetData(*this, &data);
return data + len;
}
NS_HIDDEN_(size_type) Length() const
{
const char_type* data;
return NS_StringGetData(*this, &data);
}
NS_HIDDEN_(void) Assign(const self_type& aString)
{
NS_StringCopy(*this, aString);
}
NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
{
NS_StringSetData(*this, aData, aLength);
}
NS_HIDDEN_(void) Assign(char_type aChar)
{
NS_StringSetData(*this, &aChar, 1);
}
NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString); return *this; }
NS_HIDDEN_(self_type&) operator=(const char_type* aPtr) { Assign(aPtr); return *this; }
NS_HIDDEN_(self_type&) operator=(char_type aChar) { Assign(aChar); return *this; }
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
{
NS_StringSetDataRange(*this, cutStart, cutLength, data, length);
}
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
{
Replace(cutStart, cutLength, &c, 1);
}
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
{
const char_type* data;
PRUint32 dataLen = NS_StringGetData(readable, &data);
NS_StringSetDataRange(*this, cutStart, cutLength, data, dataLen);
}
NS_HIDDEN_(void) Append( char_type c ) { Replace(size_type(-1), 0, c); }
NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) ) { Replace(size_type(-1), 0, data, length); }
NS_HIDDEN_(void) Append( const self_type& readable ) { Replace(size_type(-1), 0, readable); }
NS_HIDDEN_(self_type&) operator+=( char_type c ) { Append(c); return *this; }
NS_HIDDEN_(self_type&) operator+=( const char_type* data ) { Append(data); return *this; }
NS_HIDDEN_(self_type&) operator+=( const self_type& readable ) { Append(readable); return *this; }
NS_HIDDEN_(void) Insert( char_type c, index_type pos ) { Replace(pos, 0, c); }
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) Insert( const self_type& readable, index_type pos ) { Replace(pos, 0, readable); }
NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength ) { Replace(cutStart, cutLength, nsnull, 0); }
#endif // NS_STRINGAPI_IMPL
private:
void *v;
};
class nsACString_external
{
#ifndef NS_STRINGAPI_IMPL
public:
typedef char char_type;
typedef nsACString_external self_type;
typedef PRUint32 size_type;
typedef PRUint32 index_type;
NS_HIDDEN_(const char_type*) BeginReading() const
{
const char_type *data;
NS_CStringGetData(*this, &data);
return data;
}
NS_HIDDEN_(const char_type*) EndReading() const
{
const char_type *data;
PRUint32 len = NS_CStringGetData(*this, &data);
return data + len;
}
NS_HIDDEN_(size_type) Length() const
{
const char_type* data;
return NS_CStringGetData(*this, &data);
}
NS_HIDDEN_(void) Assign(const self_type& aString)
{
NS_CStringCopy(*this, aString);
}
NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
{
NS_CStringSetData(*this, aData, aLength);
}
NS_HIDDEN_(void) Assign(char_type aChar)
{
NS_CStringSetData(*this, &aChar, 1);
}
NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString); return *this; }
NS_HIDDEN_(self_type&) operator=(const char_type* aPtr) { Assign(aPtr); return *this; }
NS_HIDDEN_(self_type&) operator=(char_type aChar) { Assign(aChar); return *this; }
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
{
NS_CStringSetDataRange(*this, cutStart, cutLength, data, length);
}
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
{
Replace(cutStart, cutLength, &c, 1);
}
NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
{
const char_type* data;
PRUint32 dataLen = NS_CStringGetData(readable, &data);
NS_CStringSetDataRange(*this, cutStart, cutLength, data, dataLen);
}
NS_HIDDEN_(void) Append( char_type c ) { Replace(size_type(-1), 0, c); }
NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) ) { Replace(size_type(-1), 0, data, length); }
NS_HIDDEN_(void) Append( const self_type& readable ) { Replace(size_type(-1), 0, readable); }
NS_HIDDEN_(self_type&) operator+=( char_type c ) { Append(c); return *this; }
NS_HIDDEN_(self_type&) operator+=( const char_type* data ) { Append(data); return *this; }
NS_HIDDEN_(self_type&) operator+=( const self_type& readable ) { Append(readable); return *this; }
NS_HIDDEN_(void) Insert( char_type c, index_type pos ) { Replace(pos, 0, c); }
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) Insert( const self_type& readable, index_type pos ) { Replace(pos, 0, readable); }
NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength ) { Replace(cutStart, cutLength, nsnull, 0); }
#endif // NS_STRINGAPI_IMPL
private:
void *v;
};
/* ------------------------------------------------------------------------- */
/**
* Below we define nsStringContainer and nsCStringContainer. These classes
* have unspecified structure. In most cases, your code should use
* nsEmbedString instead of these classes; however, if you prefer C-style
* programming, then look no further...
*/
class nsStringContainer : public nsAString_external
{
private:
void *d1;
PRUint32 d2;
void *d3;
public:
nsStringContainer() {} // MSVC6 needs this
};
class nsCStringContainer : public nsACString_external
{
private:
void *d1;
PRUint32 d2;
void *d3;
public:
nsCStringContainer() {} // MSVC6 needs this
};
#endif // nsStringAPI_h__