1 files changed, 160 insertions, 0 deletions
diff --git a/xpcom/string/nsStringBuffer.h b/xpcom/string/nsStringBuffer.h
new file mode 100644
index 000000000..432289bf6
--- /dev/null
+++ b/xpcom/string/nsStringBuffer.h
@@ -0,0 +1,160 @@
+/* -*- 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 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__ */