gecko-dev/xpcom/string/nsStringBuffer.h
Birunthan Mohanathas 889d778644 Bug 1028559 - Flatten xpcom/string/{public,src}/ directories. r=dbaron
--HG--
rename : xpcom/string/public/nsAString.h => xpcom/string/nsAString.h
rename : xpcom/string/public/nsAlgorithm.h => xpcom/string/nsAlgorithm.h
rename : xpcom/string/public/nsCharTraits.h => xpcom/string/nsCharTraits.h
rename : xpcom/string/src/nsDependentString.cpp => xpcom/string/nsDependentString.cpp
rename : xpcom/string/public/nsDependentString.h => xpcom/string/nsDependentString.h
rename : xpcom/string/src/nsDependentSubstring.cpp => xpcom/string/nsDependentSubstring.cpp
rename : xpcom/string/public/nsDependentSubstring.h => xpcom/string/nsDependentSubstring.h
rename : xpcom/string/public/nsEmbedString.h => xpcom/string/nsEmbedString.h
rename : xpcom/string/public/nsLiteralString.h => xpcom/string/nsLiteralString.h
rename : xpcom/string/public/nsPrintfCString.h => xpcom/string/nsPrintfCString.h
rename : xpcom/string/src/nsPromiseFlatString.cpp => xpcom/string/nsPromiseFlatString.cpp
rename : xpcom/string/public/nsPromiseFlatString.h => xpcom/string/nsPromiseFlatString.h
rename : xpcom/string/src/nsReadableUtils.cpp => xpcom/string/nsReadableUtils.cpp
rename : xpcom/string/public/nsReadableUtils.h => xpcom/string/nsReadableUtils.h
rename : xpcom/string/src/nsString.cpp => xpcom/string/nsString.cpp
rename : xpcom/string/public/nsString.h => xpcom/string/nsString.h
rename : xpcom/string/public/nsStringBuffer.h => xpcom/string/nsStringBuffer.h
rename : xpcom/string/src/nsStringComparator.cpp => xpcom/string/nsStringComparator.cpp
rename : xpcom/string/public/nsStringFwd.h => xpcom/string/nsStringFwd.h
rename : xpcom/string/public/nsStringIterator.h => xpcom/string/nsStringIterator.h
rename : xpcom/string/src/nsStringObsolete.cpp => xpcom/string/nsStringObsolete.cpp
rename : xpcom/string/src/nsSubstring.cpp => xpcom/string/nsSubstring.cpp
rename : xpcom/string/public/nsSubstring.h => xpcom/string/nsSubstring.h
rename : xpcom/string/src/nsSubstringTuple.cpp => xpcom/string/nsSubstringTuple.cpp
rename : xpcom/string/public/nsSubstringTuple.h => xpcom/string/nsSubstringTuple.h
rename : xpcom/string/src/nsTDependentString.cpp => xpcom/string/nsTDependentString.cpp
rename : xpcom/string/public/nsTDependentString.h => xpcom/string/nsTDependentString.h
rename : xpcom/string/src/nsTDependentSubstring.cpp => xpcom/string/nsTDependentSubstring.cpp
rename : xpcom/string/public/nsTDependentSubstring.h => xpcom/string/nsTDependentSubstring.h
rename : xpcom/string/public/nsTLiteralString.h => xpcom/string/nsTLiteralString.h
rename : xpcom/string/src/nsTPromiseFlatString.cpp => xpcom/string/nsTPromiseFlatString.cpp
rename : xpcom/string/public/nsTPromiseFlatString.h => xpcom/string/nsTPromiseFlatString.h
rename : xpcom/string/src/nsTString.cpp => xpcom/string/nsTString.cpp
rename : xpcom/string/public/nsTString.h => xpcom/string/nsTString.h
rename : xpcom/string/src/nsTStringComparator.cpp => xpcom/string/nsTStringComparator.cpp
rename : xpcom/string/src/nsTStringObsolete.cpp => xpcom/string/nsTStringObsolete.cpp
rename : xpcom/string/src/nsTSubstring.cpp => xpcom/string/nsTSubstring.cpp
rename : xpcom/string/public/nsTSubstring.h => xpcom/string/nsTSubstring.h
rename : xpcom/string/src/nsTSubstringTuple.cpp => xpcom/string/nsTSubstringTuple.cpp
rename : xpcom/string/public/nsTSubstringTuple.h => xpcom/string/nsTSubstringTuple.h
rename : xpcom/string/public/nsUTF8Utils.h => xpcom/string/nsUTF8Utils.h
rename : xpcom/string/src/nsUTF8UtilsSSE2.cpp => xpcom/string/nsUTF8UtilsSSE2.cpp
rename : xpcom/string/public/nsXPCOMStrings.h => xpcom/string/nsXPCOMStrings.h
rename : xpcom/string/public/nsXPIDLString.h => xpcom/string/nsXPIDLString.h
rename : xpcom/string/public/string-template-def-char.h => xpcom/string/string-template-def-char.h
rename : xpcom/string/public/string-template-def-unichar.h => xpcom/string/string-template-def-unichar.h
rename : xpcom/string/public/string-template-undef.h => xpcom/string/string-template-undef.h
2014-06-25 15:08:54 -07:00

167 lines
5.9 KiB
C++

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#ifndef nsStringBuffer_h__
#define nsStringBuffer_h__
#include "mozilla/Atomics.h"
#include "mozilla/MemoryReporting.h"
template<class T> struct already_AddRefed;
/**
* This structure precedes the string buffers "we" allocate. It may be the
* case that nsTAString::mData does not point to one of these special
* buffers. The mFlags member variable distinguishes the buffer type.
*
* When this header is in use, it enables reference counting, and capacity
* tracking. NOTE: A string buffer can be modified only if its reference
* count is 1.
*/
class nsStringBuffer
{
private:
friend class CheckStaticAtomSizes;
mozilla::Atomic<int32_t> mRefCount;
uint32_t mStorageSize;
public:
/**
* Allocates a new string buffer, with given size in bytes and a
* reference count of one. When the string buffer is no longer needed,
* it should be released via Release.
*
* It is up to the caller to set the bytes corresponding to the string
* buffer by calling the Data method to fetch the raw data pointer. Care
* must be taken to properly null terminate the character array. The
* storage size can be greater than the length of the actual string
* (i.e., it is not required that the null terminator appear in the last
* storage unit of the string buffer's data).
*
* @return new string buffer or null if out of memory.
*/
static already_AddRefed<nsStringBuffer> Alloc(size_t aStorageSize);
/**
* Resizes the given string buffer to the specified storage size. This
* method must not be called on a readonly string buffer. Use this API
* carefully!!
*
* This method behaves like the ANSI-C realloc function. (i.e., If the
* allocation fails, null will be returned and the given string buffer
* will remain unmodified.)
*
* @see IsReadonly
*/
static nsStringBuffer* Realloc(nsStringBuffer* aBuf, size_t aStorageSize);
/**
* Increment the reference count on this string buffer.
*/
void NS_FASTCALL AddRef();
/**
* Decrement the reference count on this string buffer. The string
* buffer will be destroyed when its reference count reaches zero.
*/
void NS_FASTCALL Release();
/**
* This method returns the string buffer corresponding to the given data
* pointer. The data pointer must have been returned previously by a
* call to the nsStringBuffer::Data method.
*/
static nsStringBuffer* FromData(void* aData)
{
return reinterpret_cast<nsStringBuffer*>(aData) - 1;
}
/**
* This method returns the data pointer for this string buffer.
*/
void* Data() const
{
return const_cast<char*>(reinterpret_cast<const char*>(this + 1));
}
/**
* This function returns the storage size of a string buffer in bytes.
* This value is the same value that was originally passed to Alloc (or
* Realloc).
*/
uint32_t StorageSize() const
{
return mStorageSize;
}
/**
* If this method returns false, then the caller can be sure that their
* reference to the string buffer is the only reference to the string
* buffer, and therefore it has exclusive access to the string buffer and
* associated data. However, if this function returns true, then other
* consumers may rely on the data in this buffer being immutable and
* other threads may access this buffer simultaneously.
*/
bool IsReadonly() const
{
return mRefCount > 1;
}
/**
* The FromString methods return a string buffer for the given string
* object or null if the string object does not have a string buffer.
* The reference count of the string buffer is NOT incremented by these
* methods. If the caller wishes to hold onto the returned value, then
* the returned string buffer must have its reference count incremented
* via a call to the AddRef method.
*/
static nsStringBuffer* FromString(const nsAString& aStr);
static nsStringBuffer* FromString(const nsACString& aStr);
/**
* The ToString methods assign this string buffer to a given string
* object. If the string object does not support sharable string
* buffers, then its value will be set to a copy of the given string
* buffer. Otherwise, these methods increment the reference count of the
* given string buffer. It is important to specify the length (in
* storage units) of the string contained in the string buffer since the
* length of the string may be less than its storage size. The string
* must have a null terminator at the offset specified by |len|.
*
* NOTE: storage size is measured in bytes even for wide strings;
* however, string length is always measured in storage units
* (2-byte units for wide strings).
*/
void ToString(uint32_t aLen, nsAString& aStr, bool aMoveOwnership = false);
void ToString(uint32_t aLen, nsACString& aStr, bool aMoveOwnership = false);
/**
* This measures the size. It should only be used if the StringBuffer is
* unshared. This is checked.
*/
size_t SizeOfIncludingThisMustBeUnshared(mozilla::MallocSizeOf aMallocSizeOf) const;
/**
* This measures the size only if the StringBuffer is unshared.
*/
size_t SizeOfIncludingThisIfUnshared(mozilla::MallocSizeOf aMallocSizeOf) const;
/**
* This measures the size regardless of whether the StringBuffer is
* unshared.
*
* WARNING: Only use this if you really know what you are doing, because
* it can easily lead to double-counting strings. If you do use them,
* please explain clearly in a comment why it's safe and won't lead to
* double-counting.
*/
size_t SizeOfIncludingThisEvenIfShared(mozilla::MallocSizeOf aMallocSizeOf) const;
};
#endif /* !defined(nsStringBuffer_h__ */