pjs/xpcom/string/public/nsStringBuffer.h

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=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 nsStringBuffer_h__
#define nsStringBuffer_h__

/**
 * 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:

      PRInt32  mRefCount;
      PRUint32 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.
       */
      NS_COM static nsStringBuffer* Alloc(size_t storageSize);

      /**
       * 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
       */
      NS_COM static nsStringBuffer* Realloc(nsStringBuffer* buf, size_t storageSize);

      /**
       * Increment the reference count on this string buffer.
       */
      NS_COM void NS_FASTCALL AddRef();

      /**
       * Decrement the reference count on this string buffer.  The string
       * buffer will be destroyed when its reference count reaches zero.
       */
      NS_COM 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* data)
        {
          return (nsStringBuffer*) ( ((char*) data) - sizeof(nsStringBuffer) );
        }

      /**
       * This method returns the data pointer for this string buffer.
       */
      void* Data() const
        {
          return (void*) ( ((char*) this) + sizeof(nsStringBuffer) );
        }

      /**
       * 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).
       */
      PRUint32 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.
       */
      PRBool 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.
       */
      NS_COM static nsStringBuffer* FromString(const nsAString &str);
      NS_COM static nsStringBuffer* FromString(const nsACString &str);

      /**
       * 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).
       */
      NS_COM void ToString(PRUint32 len, nsAString &str);
      NS_COM void ToString(PRUint32 len, nsACString &str);
  };

#endif /* !defined(nsStringBuffer_h__ */