nsStringAPI.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:56k
- /* vim:set ts=2 sw=2 et cindent: */
- /* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is Mozilla.
- *
- * The Initial Developer of the Original Code is IBM Corporation.
- * Portions created by IBM Corporation are Copyright (C) 2003
- * IBM Corporation. All Rights Reserved.
- *
- * Contributor(s):
- * Darin Fisher <darin@meer.net>
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
- #ifndef nsStringAPI_h__
- #define nsStringAPI_h__
- #include <string.h>
- /**
- * nsStringAPI.h
- *
- * This file describes a minimal API for working with XPCOM's abstract
- * string classes. It divorces the consumer from having any run-time
- * dependency on the implementation details of the abstract string types.
- */
- // Map frozen functions to private symbol names if not using strict API.
- #ifdef MOZILLA_INTERNAL_API
- # define NS_StringContainerInit NS_StringContainerInit_P
- # define NS_StringContainerInit2 NS_StringContainerInit2_P
- # define NS_StringContainerFinish NS_StringContainerFinish_P
- # define NS_StringGetData NS_StringGetData_P
- # define NS_StringGetMutableData NS_StringGetMutableData_P
- # define NS_StringCloneData NS_StringCloneData_P
- # define NS_StringSetData NS_StringSetData_P
- # define NS_StringSetDataRange NS_StringSetDataRange_P
- # define NS_StringCopy NS_StringCopy_P
- # define NS_CStringContainerInit NS_CStringContainerInit_P
- # define NS_CStringContainerInit2 NS_CStringContainerInit2_P
- # define NS_CStringContainerFinish NS_CStringContainerFinish_P
- # define NS_CStringGetData NS_CStringGetData_P
- # define NS_CStringGetMutableData NS_CStringGetMutableData_P
- # define NS_CStringCloneData NS_CStringCloneData_P
- # define NS_CStringSetData NS_CStringSetData_P
- # define NS_CStringSetDataRange NS_CStringSetDataRange_P
- # define NS_CStringCopy NS_CStringCopy_P
- # define NS_CStringToUTF16 NS_CStringToUTF16_P
- # define NS_UTF16ToCString NS_UTF16ToCString_P
- #endif
- #include "nscore.h"
- #if defined( XPCOM_GLUE )
- #define NS_STRINGAPI(type) extern "C" NS_HIDDEN_(type)
- #elif defined( _IMPL_NS_STRINGAPI )
- #define NS_STRINGAPI(type) extern "C" NS_EXPORT type
- #else
- #define NS_STRINGAPI(type) extern "C" NS_IMPORT type
- #endif
- /* The base string types */
- class nsAString;
- class nsACString;
- /* ------------------------------------------------------------------------- */
- /**
- * nsStringContainer
- *
- * This is an opaque data type that is large enough to hold the canonical
- * implementation of nsAString. The binary structure of this class is an
- * implementation detail.
- *
- * The string data stored in a string container is always single fragment
- * and may be null-terminated depending on how it is initialized.
- *
- * Typically, string containers are allocated on the stack for temporary
- * use. However, they can also be malloc'd if necessary. In either case,
- * a string container is not useful until it has been initialized with a
- * call to NS_StringContainerInit. The following example shows how to use
- * a string container to call a function that takes a |nsAString &| out-param.
- *
- * NS_METHOD GetBlah(nsAString &aBlah);
- *
- * nsresult MyCode()
- * {
- * nsresult rv;
- *
- * nsStringContainer sc;
- * rv = NS_StringContainerInit(sc);
- * if (NS_FAILED(rv))
- * return rv;
- *
- * rv = GetBlah(sc);
- * if (NS_SUCCEEDED(rv))
- * {
- * const PRUnichar *data;
- * NS_StringGetData(sc, &data);
- * //
- * // |data| now points to the result of the GetBlah function
- * //
- * }
- *
- * NS_StringContainerFinish(sc);
- * return rv;
- * }
- *
- * The following example show how to use a string container to pass a string
- * parameter to a function taking a |const nsAString &| in-param.
- *
- * NS_METHOD SetBlah(const nsAString &aBlah);
- *
- * nsresult MyCode()
- * {
- * nsresult rv;
- *
- * nsStringContainer sc;
- * rv = NS_StringContainerInit(sc);
- * if (NS_FAILED(rv))
- * return rv;
- *
- * const PRUnichar kData[] = {'x','y','z',' '};
- * rv = NS_StringSetData(sc, kData, sizeof(kData)/2 - 1);
- * if (NS_SUCCEEDED(rv))
- * rv = SetBlah(sc);
- *
- * NS_StringContainerFinish(sc);
- * return rv;
- * }
- */
- class nsStringContainer;
- /**
- * Flags that may be OR'd together to pass to NS_StringContainerInit2:
- */
- enum {
- /* Data passed into NS_StringContainerInit2 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_STRING_CONTAINER_INIT_ADOPT. */
- NS_STRING_CONTAINER_INIT_DEPEND = (1 << 1),
- /* Data passed into NS_StringContainerInit2 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 (nsMemory).
- * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */
- NS_STRING_CONTAINER_INIT_ADOPT = (1 << 2),
- /* Data passed into NS_StringContainerInit2 is a substring that is not
- * null-terminated. */
- NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
- };
- /**
- * NS_StringContainerInit
- *
- * @param aContainer string container reference
- * @return NS_OK if string container successfully initialized
- *
- * This function may allocate additional memory for aContainer. When
- * aContainer is no longer needed, NS_StringContainerFinish should be called.
- *
- * @status FROZEN
- */
- NS_STRINGAPI(nsresult)
- NS_StringContainerInit(nsStringContainer &aContainer);
- /**
- * NS_StringContainerInit2
- *
- * @param aContainer string container reference
- * @param aData character buffer (may be null)
- * @param aDataLength number of characters stored at aData (may pass
- * PR_UINT32_MAX if aData is null-terminated)
- * @param aFlags flags affecting how the string container is
- * initialized. this parameter is ignored when aData
- * is null. otherwise, if this parameter is 0, then
- * aData is copied into the string.
- *
- * This function resembles NS_StringContainerInit but provides further
- * options that permit more efficient memory usage. When aContainer is
- * no longer needed, NS_StringContainerFinish should be called.
- *
- * NOTE: NS_StringContainerInit2(container, nsnull, 0, 0) is equivalent to
- * NS_StringContainerInit(container).
- *
- * @status FROZEN
- */
- NS_STRINGAPI(nsresult)
- NS_StringContainerInit2
- (nsStringContainer &aContainer, const PRUnichar *aData = nsnull,
- PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
- /**
- * NS_StringContainerFinish
- *
- * @param aContainer string container reference
- *
- * This function frees any memory owned by aContainer.
- *
- * @status FROZEN
- */
- NS_STRINGAPI(void)
- NS_StringContainerFinish(nsStringContainer &aContainer);
- /* ------------------------------------------------------------------------- */
- /**
- * NS_StringGetData
- *
- * This function returns a const character pointer to the string's internal
- * buffer, the length of the string, and a boolean value indicating whether
- * or not the buffer is null-terminated.
- *
- * @param aStr abstract string reference
- * @param aData out param that will hold the address of aStr's
- * internal buffer
- * @param aTerminated if non-null, this out param will be set to indicate
- * whether or not aStr's internal buffer is null-
- * terminated
- * @return length of aStr's internal buffer
- *
- * @status FROZEN
- */
- NS_STRINGAPI(PRUint32)
- NS_StringGetData
- (const nsAString &aStr, const PRUnichar **aData,
- PRBool *aTerminated = nsnull);
- /**
- * NS_StringGetMutableData
- *
- * This function provides mutable access to a string's internal buffer. It
- * returns a pointer to an array of characters that may be modified. The
- * returned pointer remains valid until the string object is passed to some
- * other string function.
- *
- * Optionally, this function may be used to resize the string's internal
- * buffer. The aDataLength parameter specifies the requested length of the
- * string's internal buffer. By passing some value other than PR_UINT32_MAX,
- * the caller can request that the buffer be resized to the specified number of
- * characters before returning. The caller is not responsible for writing a
- * null-terminator.
- *
- * @param aStr abstract string reference
- * @param aDataLength number of characters to resize the string's internal
- * buffer to or PR_UINT32_MAX if no resizing is needed
- * @param aData out param that upon return holds the address of aStr's
- * internal buffer or null if the function failed
- * @return number of characters or zero if the function failed
- *
- * This function does not necessarily null-terminate aStr after resizing its
- * internal buffer. 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(PRUint32)
- NS_StringGetMutableData
- (nsAString &aStr, PRUint32 aDataLength, PRUnichar **aData);
- /**
- * NS_StringCloneData
- *
- * This function returns a null-terminated copy of the string's
- * internal buffer.
- *
- * @param aStr abstract string reference
- * @return null-terminated copy of the string's internal buffer
- * (it must be free'd using using nsMemory::Free)
- *
- * @status FROZEN
- */
- NS_STRINGAPI(PRUnichar *)
- NS_StringCloneData
- (const nsAString &aStr);
- /**
- * NS_StringSetData
- *
- * This function copies aData into aStr.
- *
- * @param aStr abstract string reference
- * @param aData character buffer
- * @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_StringSetData
- (nsAString &aStr, const PRUnichar *aData,
- PRUint32 aDataLength = PR_UINT32_MAX);
- /**
- * NS_StringSetDataRange
- *
- * 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_StringSetDataRange
- (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
- const PRUnichar *aData, PRUint32 aDataLength = PR_UINT32_MAX);
- /**
- * NS_StringCopy
- *
- * 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_StringCopy
- (nsAString &aDestStr, const nsAString &aSrcStr);
- /**
- * NS_StringAppendData
- *
- * 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_StringAppendData(nsAString &aStr, const PRUnichar *aData,
- PRUint32 aDataLength = PR_UINT32_MAX)
- {
- return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
- }
- /**
- * NS_StringInsertData
- *
- * 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_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
- PRUint32 aDataLength = PR_UINT32_MAX)
- {
- return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
- }
- /**
- * NS_StringCutData
- *
- * 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_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
- {
- return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
- }
- /* ------------------------------------------------------------------------- */
- /**
- * nsCStringContainer
- *
- * This is an opaque data type that is large enough to hold the canonical
- * implementation of nsACString. The binary structure of this class is an
- * implementation detail.
- *
- * The string data stored in a string container is always single fragment
- * and may be null-terminated depending on how it is initialized.
- *
- * @see nsStringContainer for use cases and further documentation.
- */
- class nsCStringContainer;
- /**
- * Flags that may be OR'd together to pass to NS_StringContainerInit2:
- */
- enum {
- /* 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_DEPEND = (1 << 1),
- /* 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 (nsMemory).
- * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
- NS_CSTRING_CONTAINER_INIT_ADOPT = (1 << 2),
- /* Data passed into NS_CStringContainerInit2 is a substring that is not
- * null-terminated. */
- NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
- };
- /**
- * NS_CStringContainerInit
- *
- * @param aContainer string container reference
- * @return NS_OK if string container successfully initialized
- *
- * This function may allocate additional memory for aContainer. When
- * aContainer is no longer needed, NS_CStringContainerFinish should be called.
- *
- * @status FROZEN
- */
- NS_STRINGAPI(nsresult)
- NS_CStringContainerInit(nsCStringContainer &aContainer);
- /**
- * NS_CStringContainerInit2
- *
- * @param aContainer string container reference
- * @param aData character buffer (may be null)
- * @param aDataLength number of characters stored at aData (may pass
- * PR_UINT32_MAX if aData is null-terminated)
- * @param aFlags flags affecting how the string container is
- * initialized. this parameter is ignored when aData
- * is null. otherwise, if this parameter is 0, then
- * aData is copied into the string.
- *
- * This function resembles NS_CStringContainerInit but provides further
- * options that permit more efficient memory usage. When aContainer is
- * no longer needed, NS_CStringContainerFinish should be called.
- *
- * NOTE: NS_CStringContainerInit2(container, nsnull, 0, 0) is equivalent to
- * NS_CStringContainerInit(container).
- *
- * @status FROZEN
- */
- NS_STRINGAPI(nsresult)
- NS_CStringContainerInit2
- (nsCStringContainer &aContainer, const char *aData = nsnull,
- PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
- /**
- * NS_CStringContainerFinish
- *
- * @param aContainer string container reference
- *
- * This function frees any memory owned by aContainer.
- *
- * @status FROZEN
- */
- NS_STRINGAPI(void)
- NS_CStringContainerFinish(nsCStringContainer &aContainer);
- /* ------------------------------------------------------------------------- */
- /**
- * NS_CStringGetData
- *
- * This function returns a const character pointer to the string's internal
- * buffer, the length of the string, and a boolean value indicating whether
- * or not the buffer is null-terminated.
- *
- * @param aStr abstract string reference
- * @param aData out param that will hold the address of aStr's
- * internal buffer
- * @param aTerminated if non-null, this out param will be set to indicate
- * whether or not aStr's internal buffer is null-
- * terminated
- * @return length of aStr's internal buffer
- *
- * @status FROZEN
- */
- NS_STRINGAPI(PRUint32)
- NS_CStringGetData
- (const nsACString &aStr, const char **aData,
- PRBool *aTerminated = nsnull);
- /**
- * NS_CStringGetMutableData
- *
- * This function provides mutable access to a string's internal buffer. It
- * returns a pointer to an array of characters that may be modified. The
- * returned pointer remains valid until the string object is passed to some
- * other string function.
- *
- * Optionally, this function may be used to resize the string's internal
- * buffer. The aDataLength parameter specifies the requested length of the
- * string's internal buffer. By passing some value other than PR_UINT32_MAX,
- * the caller can request that the buffer be resized to the specified number of
- * characters before returning. The caller is not responsible for writing a
- * null-terminator.
- *
- * @param aStr abstract string reference
- * @param aDataLength number of characters to resize the string's internal
- * buffer to or PR_UINT32_MAX if no resizing is needed
- * @param aData out param that upon return holds the address of aStr's
- * internal buffer or null if the function failed
- * @return number of characters or zero if the function failed
- *
- * This function does not necessarily null-terminate aStr after resizing its
- * internal buffer. 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(PRUint32)
- NS_CStringGetMutableData
- (nsACString &aStr, PRUint32 aDataLength, char **aData);
- /**
- * NS_CStringCloneData
- *
- * This function returns a null-terminated copy of the string's
- * internal buffer.
- *
- * @param aStr abstract string reference
- * @return null-terminated copy of the string's internal buffer
- * (it must be free'd using using nsMemory::Free)
- *
- * @status FROZEN
- */
- NS_STRINGAPI(char *)
- NS_CStringCloneData
- (const nsACString &aStr);
- /**
- * NS_CStringSetData
- *
- * This function copies aData into aStr.
- *
- * @param aStr abstract string reference
- * @param aData character buffer
- * @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_CStringSetData
- (nsACString &aStr, const char *aData,
- PRUint32 aDataLength = PR_UINT32_MAX);
- /**
- * 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 MOZILLA_INTERNAL_API
- #define nsAString_external nsAString
- #define nsACString_external nsACString
- #endif
- class nsAString_external
- {
- #ifndef MOZILLA_INTERNAL_API
- 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_(char_type*) BeginWriting()
- {
- char_type *data;
- NS_StringGetMutableData(*this, PR_UINT32_MAX, &data);
- return data;
- }
- NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
- {
- char_type *data;
- NS_StringGetMutableData(*this, aLen, &data);
- return data != nsnull;
- }
- NS_HIDDEN_(size_type) Length() const
- {
- const char_type* data;
- return NS_StringGetData(*this, &data);
- }
- NS_HIDDEN_(PRBool) IsEmpty() const
- {
- return Length() == 0;
- }
- 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); }
- NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
- const char_type *cself;
- const char_type *cother;
- PRUint32 selflen = NS_StringGetData(*this, &cself);
- PRUint32 otherlen = NS_StringGetData(other, &cother);
- if (selflen != otherlen)
- return PR_FALSE;
- return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
- }
- #endif // MOZILLA_INTERNAL_API
- protected:
- // Prevent people from allocating a nsAString directly.
- ~nsAString_external() {}
- private:
- void *v;
- };
- class nsACString_external
- {
- #ifndef MOZILLA_INTERNAL_API
- 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_(char_type*) BeginWriting()
- {
- char_type *data;
- NS_CStringGetMutableData(*this, PR_UINT32_MAX, &data);
- return data;
- }
- NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
- {
- char_type *data;
- NS_CStringGetMutableData(*this, aLen, &data);
- return data != nsnull;
- }
- NS_HIDDEN_(size_type) Length() const
- {
- const char_type* data;
- return NS_CStringGetData(*this, &data);
- }
- NS_HIDDEN_(PRBool) IsEmpty() const
- {
- return Length() == 0;
- }
- 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); }
- NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
- const char_type *cself;
- const char_type *cother;
- PRUint32 selflen = NS_CStringGetData(*this, &cself);
- PRUint32 otherlen = NS_CStringGetData(other, &cother);
- if (selflen != otherlen)
- return PR_FALSE;
-
- return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
- }
- #endif // MOZILLA_INTERNAL_API
- protected:
- // Prevent people from allocating a nsACString directly.
- ~nsACString_external() {}
- 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
- };
- /* ------------------------------------------------------------------------- */
- /**
- * Below we define a number of inlined helper classes that make the frozen
- * string API easier to use.
- */
- #ifndef MOZILLA_INTERNAL_API
- #include "nsDebug.h"
- /**
- * Rename symbols to avoid conflicting with internal versions.
- */
- #define nsString nsString_external
- #define nsCString nsCString_external
- #define nsDependentString nsDependentString_external
- #define nsDependentCString nsDependentCString_external
- #define NS_ConvertASCIItoUTF16 NS_ConvertASCIItoUTF16_external
- #define NS_ConvertUTF8toUTF16 NS_ConvertUTF8toUTF16_external
- #define NS_ConvertUTF16toUTF8 NS_ConvertUTF16toUTF8_external
- #define NS_LossyConvertUTF16toASCII NS_LossyConvertUTF16toASCII_external
- #define nsGetterCopies nsGetterCopies_external
- #define nsCGetterCopies nsCGetterCopies_external
- #define nsDependentSubstring nsDependentSubstring_external
- #define nsDependentCSubstring nsDependentCSubstring_external
- /**
- * basic strings
- */
- class nsString : public nsStringContainer
- {
- public:
- typedef nsString self_type;
- typedef nsAString abstract_string_type;
- nsString()
- {
- NS_StringContainerInit(*this);
- }
- nsString(const self_type& aString)
- {
- NS_StringContainerInit(*this);
- NS_StringCopy(*this, aString);
- }
- explicit
- nsString(const abstract_string_type& aReadable)
- {
- NS_StringContainerInit(*this);
- NS_StringCopy(*this, aReadable);
- }
- explicit
- nsString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
- {
- NS_StringContainerInit2(*this, aData, aLength, 0);
- }
-
- ~nsString()
- {
- NS_StringContainerFinish(*this);
- }
- const char_type* get() const
- {
- const char_type* data;
- NS_StringGetData(*this, &data);
- return data;
- }
-
- self_type& operator=(const self_type& aString) { Assign(aString); return *this; }
- self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
- self_type& operator=(const char_type* aPtr) { Assign(aPtr); return *this; }
- self_type& operator=(char_type aChar) { Assign(aChar); return *this; }
- void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
- {
- NS_StringContainerFinish(*this);
- NS_StringContainerInit2(*this, aData, aLength,
- NS_STRING_CONTAINER_INIT_ADOPT);
- }
- protected:
-
- nsString(const char_type* aData, size_type aLength, PRUint32 aFlags)
- {
- NS_StringContainerInit2(*this, aData, aLength, aFlags);
- }
- };
- class nsCString : public nsCStringContainer
- {
- public:
- typedef nsCString self_type;
- typedef nsACString abstract_string_type;
- nsCString()
- {
- NS_CStringContainerInit(*this);
- }
- nsCString(const self_type& aString)
- {
- NS_CStringContainerInit(*this);
- NS_CStringCopy(*this, aString);
- }
- explicit
- nsCString(const abstract_string_type& aReadable)
- {
- NS_CStringContainerInit(*this);
- NS_CStringCopy(*this, aReadable);
- }
- explicit
- nsCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
- {
- NS_CStringContainerInit(*this);
- NS_CStringSetData(*this, aData, aLength);
- }
-
- ~nsCString()
- {
- NS_CStringContainerFinish(*this);
- }
- const char_type* get() const
- {
- const char_type* data;
- NS_CStringGetData(*this, &data);
- return data;
- }
-
- self_type& operator=(const self_type& aString) { Assign(aString); return *this; }
- self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
- self_type& operator=(const char_type* aPtr) { Assign(aPtr); return *this; }
- self_type& operator=(char_type aChar) { Assign(aChar); return *this; }
- void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
- {
- NS_CStringContainerFinish(*this);
- NS_CStringContainerInit2(*this, aData, aLength,
- NS_CSTRING_CONTAINER_INIT_ADOPT);
- }
- protected:
-
- nsCString(const char_type* aData, size_type aLength, PRUint32 aFlags)
- {
- NS_CStringContainerInit2(*this, aData, aLength, aFlags);
- }
- };
- /**
- * dependent strings
- */
- class nsDependentString : public nsString
- {
- public:
- typedef nsDependentString self_type;
- nsDependentString() {}
- explicit
- nsDependentString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
- : nsString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
- {}
- void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
- {
- NS_StringContainerFinish(*this);
- NS_StringContainerInit2(*this, aData, aLength,
- NS_STRING_CONTAINER_INIT_DEPEND);
- }
-
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- class nsDependentCString : public nsCString
- {
- public:
- typedef nsDependentCString self_type;
- nsDependentCString() {}
- explicit
- nsDependentCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
- : nsCString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
- {}
- void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
- {
- NS_CStringContainerFinish(*this);
- NS_CStringContainerInit2(*this, aData, aLength,
- NS_CSTRING_CONTAINER_INIT_DEPEND);
- }
-
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- /**
- * conversion classes
- */
- class NS_ConvertASCIItoUTF16 : public nsString
- {
- public:
- typedef NS_ConvertASCIItoUTF16 self_type;
- explicit
- NS_ConvertASCIItoUTF16(const nsACString& aStr)
- {
- NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_ASCII, *this);
- }
- explicit
- NS_ConvertASCIItoUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
- {
- NS_CStringToUTF16(nsDependentCString(aData, aLength),
- NS_CSTRING_ENCODING_ASCII, *this);
- }
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- class NS_ConvertUTF8toUTF16 : public nsString
- {
- public:
- typedef NS_ConvertUTF8toUTF16 self_type;
- explicit
- NS_ConvertUTF8toUTF16(const nsACString& aStr)
- {
- NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_UTF8, *this);
- }
- explicit
- NS_ConvertUTF8toUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
- {
- NS_CStringToUTF16(nsDependentCString(aData, aLength),
- NS_CSTRING_ENCODING_UTF8, *this);
- }
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- class NS_ConvertUTF16toUTF8 : public nsCString
- {
- public:
- typedef NS_ConvertUTF16toUTF8 self_type;
- explicit
- NS_ConvertUTF16toUTF8(const nsAString& aStr)
- {
- NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_UTF8, *this);
- }
- explicit
- NS_ConvertUTF16toUTF8(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
- {
- NS_UTF16ToCString(nsDependentString(aData, aLength),
- NS_CSTRING_ENCODING_UTF8, *this);
- }
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- class NS_LossyConvertUTF16toASCII : public nsCString
- {
- public:
- typedef NS_LossyConvertUTF16toASCII self_type;
- explicit
- NS_LossyConvertUTF16toASCII(const nsAString& aStr)
- {
- NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_ASCII, *this);
- }
- explicit
- NS_LossyConvertUTF16toASCII(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
- {
- NS_UTF16ToCString(nsDependentString(aData, aLength),
- NS_CSTRING_ENCODING_ASCII, *this);
- }
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- /**
- * literal strings
- *
- * NOTE: HAVE_CPP_2BYTE_WCHAR_T may be automatically defined for some platforms
- * in nscore.h. On other platforms, it may be defined in xpcom-config.h.
- * Under GCC, this define should only be set if compiling with -fshort-wchar.
- */
- #ifdef HAVE_CPP_2BYTE_WCHAR_T
- #define NS_LL(s) L##s
- #define NS_MULTILINE_LITERAL_STRING(s) nsDependentString(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
- #define NS_MULTILINE_LITERAL_STRING_INIT(n,s) n(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
- #define NS_NAMED_MULTILINE_LITERAL_STRING(n,s) const nsDependentString n(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
- typedef nsDependentString nsLiteralString;
- #else
- #define NS_LL(s) s
- #define NS_MULTILINE_LITERAL_STRING(s) NS_ConvertASCIItoUTF16(s, PRUint32(sizeof(s)-1))
- #define NS_MULTILINE_LITERAL_STRING_INIT(n,s) n(s, PRUint32(sizeof(s)-1))
- #define NS_NAMED_MULTILINE_LITERAL_STRING(n,s) const NS_ConvertASCIItoUTF16 n(s, PRUint32(sizeof(s)-1))
- typedef NS_ConvertASCIItoUTF16 nsLiteralString;
- #endif
- /*
- * Macro arguments used in concatenation or stringification won't be expanded.
- * Therefore, in order for |NS_L(FOO)| to work as expected (which is to expand
- * |FOO| before doing whatever |NS_L| needs to do to it) a helper macro needs
- * to be inserted in between to allow the macro argument to expand.
- * See "3.10.6 Separate Expansion of Macro Arguments" of the CPP manual for a
- * more accurate and precise explanation.
- */
- #define NS_L(s) NS_LL(s)
- #define NS_LITERAL_STRING(s) NS_STATIC_CAST(const nsString&, NS_MULTILINE_LITERAL_STRING(NS_LL(s)))
- #define NS_LITERAL_STRING_INIT(n,s) NS_MULTILINE_LITERAL_STRING_INIT(n, NS_LL(s))
- #define NS_NAMED_LITERAL_STRING(n,s) NS_NAMED_MULTILINE_LITERAL_STRING(n, NS_LL(s))
- #define NS_LITERAL_CSTRING(s) NS_STATIC_CAST(const nsDependentCString&, nsDependentCString(s, PRUint32(sizeof(s)-1)))
- #define NS_LITERAL_CSTRING_INIT(n,s) n(s, PRUint32(sizeof(s)-1))
- #define NS_NAMED_LITERAL_CSTRING(n,s) const nsDependentCString n(s, PRUint32(sizeof(s)-1))
- typedef nsDependentCString nsLiteralCString;
- /**
- * getter_Copies support
- *
- * NS_IMETHOD GetBlah(PRUnichar**);
- *
- * void some_function()
- * {
- * nsString blah;
- * GetBlah(getter_Copies(blah));
- * // ...
- * }
- */
- class nsGetterCopies
- {
- public:
- typedef PRUnichar char_type;
- nsGetterCopies(nsString& aStr)
- : mString(aStr), mData(nsnull)
- {}
- ~nsGetterCopies()
- {
- mString.Adopt(mData);
- }
- operator char_type**()
- {
- return &mData;
- }
- private:
- nsString& mString;
- char_type* mData;
- };
- inline nsGetterCopies
- getter_Copies(nsString& aString)
- {
- return nsGetterCopies(aString);
- }
- class nsCGetterCopies
- {
- public:
- typedef char char_type;
- nsCGetterCopies(nsCString& aStr)
- : mString(aStr), mData(nsnull)
- {}
- ~nsCGetterCopies()
- {
- mString.Adopt(mData);
- }
- operator char_type**()
- {
- return &mData;
- }
- private:
- nsCString& mString;
- char_type* mData;
- };
- inline nsCGetterCopies
- getter_Copies(nsCString& aString)
- {
- return nsCGetterCopies(aString);
- }
- /**
- * substrings
- */
- class nsDependentSubstring : public nsStringContainer
- {
- public:
- typedef nsDependentSubstring self_type;
- typedef nsAString abstract_string_type;
- ~nsDependentSubstring()
- {
- NS_StringContainerFinish(*this);
- }
- nsDependentSubstring()
- {
- NS_StringContainerInit(*this);
- }
- nsDependentSubstring(const char_type *aStart, PRUint32 aLength)
- {
- NS_StringContainerInit2(*this, aStart, aLength,
- NS_STRING_CONTAINER_INIT_DEPEND |
- NS_STRING_CONTAINER_INIT_SUBSTRING);
- }
- nsDependentSubstring(const abstract_string_type& aStr,
- PRUint32 aStartPos)
- {
- const PRUnichar* data;
- PRUint32 len = NS_StringGetData(aStr, &data);
- NS_StringContainerInit2(*this, data + aStartPos, len - aStartPos,
- NS_STRING_CONTAINER_INIT_DEPEND |
- NS_STRING_CONTAINER_INIT_SUBSTRING);
- }
- nsDependentSubstring(const abstract_string_type& aStr,
- PRUint32 aStartPos, PRUint32 aLength)
- {
- const PRUnichar* data;
- #ifdef DEBUG
- PRUint32 len =
- #endif
- NS_StringGetData(aStr, &data);
- NS_ASSERTION(aStartPos + aLength <= len, "bad length");
- NS_StringContainerInit2(*this, data + aStartPos, aLength,
- NS_STRING_CONTAINER_INIT_DEPEND |
- NS_STRING_CONTAINER_INIT_SUBSTRING);
- }
- void Rebind(const char_type *aStart, PRUint32 aLength)
- {
- NS_StringContainerFinish(*this);
- NS_StringContainerInit2(*this, aStart, aLength,
- NS_STRING_CONTAINER_INIT_DEPEND |
- NS_STRING_CONTAINER_INIT_SUBSTRING);
- }
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- class nsDependentCSubstring : public nsCStringContainer
- {
- public:
- typedef nsDependentCSubstring self_type;
- typedef nsACString abstract_string_type;
- ~nsDependentCSubstring()
- {
- NS_CStringContainerFinish(*this);
- }
- nsDependentCSubstring()
- {
- NS_CStringContainerInit(*this);
- }
- nsDependentCSubstring(const char_type *aStart, PRUint32 aLength)
- {
- NS_CStringContainerInit2(*this, aStart, aLength,
- NS_CSTRING_CONTAINER_INIT_DEPEND |
- NS_CSTRING_CONTAINER_INIT_SUBSTRING);
- }
- nsDependentCSubstring(const abstract_string_type& aStr,
- PRUint32 aStartPos)
- {
- const char* data;
- PRUint32 len = NS_CStringGetData(aStr, &data);
- NS_CStringContainerInit2(*this, data + aStartPos, len - aStartPos,
- NS_CSTRING_CONTAINER_INIT_DEPEND |
- NS_CSTRING_CONTAINER_INIT_SUBSTRING);
- }
- nsDependentCSubstring(const abstract_string_type& aStr,
- PRUint32 aStartPos, PRUint32 aLength)
- {
- const char* data;
- #ifdef DEBUG
- PRUint32 len =
- #endif
- NS_CStringGetData(aStr, &data);
- NS_ASSERTION(aStartPos + aLength <= len, "bad length");
- NS_CStringContainerInit2(*this, data + aStartPos, aLength,
- NS_CSTRING_CONTAINER_INIT_DEPEND |
- NS_CSTRING_CONTAINER_INIT_SUBSTRING);
- }
- void Rebind(const char_type *aStart, PRUint32 aLength)
- {
- NS_CStringContainerFinish(*this);
- NS_CStringContainerInit2(*this, aStart, aLength,
- NS_CSTRING_CONTAINER_INIT_DEPEND |
- NS_CSTRING_CONTAINER_INIT_SUBSTRING);
- }
- private:
- self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
- };
- /**
- * Various nsDependentC?Substring constructor functions
- */
- // PRUnichar
- inline
- const nsDependentSubstring
- Substring( const nsAString& str, PRUint32 startPos )
- {
- return nsDependentSubstring(str, startPos);
- }
- inline
- const nsDependentSubstring
- Substring( const nsAString& str, PRUint32 startPos, PRUint32 length )
- {
- return nsDependentSubstring(str, startPos, length);
- }
- inline
- const nsDependentSubstring
- Substring( const PRUnichar* start, const PRUnichar* end )
- {
- return nsDependentSubstring(start, end - start);
- }
- inline
- const nsDependentSubstring
- Substring( const PRUnichar* start, PRUint32 length )
- {
- return nsDependentSubstring(start, length);
- }
- inline
- const nsDependentSubstring
- StringHead( const nsAString& str, PRUint32 count )
- {
- return nsDependentSubstring(str, 0, count);
- }
- inline
- const nsDependentSubstring
- StringTail( const nsAString& str, PRUint32 count )
- {
- return nsDependentSubstring(str, str.Length() - count, count);
- }
- // char
- inline
- const nsDependentCSubstring
- Substring( const nsACString& str, PRUint32 startPos )
- {
- return nsDependentCSubstring(str, startPos);
- }
- inline
- const nsDependentCSubstring
- Substring( const nsACString& str, PRUint32 startPos, PRUint32 length )
- {
- return nsDependentCSubstring(str, startPos, length);
- }
- inline
- const nsDependentCSubstring
- Substring( const char* start, const char* end )
- {
- return nsDependentCSubstring(start, end - start);
- }
- inline
- const nsDependentCSubstring
- Substring( const char* start, PRUint32 length )
- {
- return nsDependentCSubstring(start, length);
- }
- inline
- const nsDependentCSubstring
- StringHead( const nsACString& str, PRUint32 count )
- {
- return nsDependentCSubstring(str, 0, count);
- }
- inline
- const nsDependentCSubstring
- StringTail( const nsACString& str, PRUint32 count )
- {
- return nsDependentCSubstring(str, str.Length() - count, count);
- }
- /*
- * Canonical empty strings
- */
- #define EmptyCString() nsCString()
- #define EmptyString() nsString()
- #endif // MOZILLA_INTERNAL_API
- #endif // nsStringAPI_h__