LCOV - app.info - objdir/dist/include/nsStringBuffer.h

LCOV - code coverage report
| Current view: | directory - objdir/dist/include - nsStringBuffer.h (source / functions) |  | Found | Hit | Coverage |
| Test: | app.info | Lines: | 8 | 8 | 100.0 %
| Date: | 2012-07-07 | Functions: | 4 | 4 | 100.0 %

           1                 : /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
           2                 : /* vim:set ts=2 sw=2 sts=2 et cindent: */
           3                 : /* ***** BEGIN LICENSE BLOCK *****
           4                 :  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
           5                 :  *
           6                 :  * The contents of this file are subject to the Mozilla Public License Version
           7                 :  * 1.1 (the "License"); you may not use this file except in compliance with
           8                 :  * the License. You may obtain a copy of the License at
           9                 :  * http://www.mozilla.org/MPL/
          10                 :  *
          11                 :  * Software distributed under the License is distributed on an "AS IS" basis,
          12                 :  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
          13                 :  * for the specific language governing rights and limitations under the
          14                 :  * License.
          15                 :  *
          16                 :  * The Original Code is Mozilla.
          17                 :  *
          18                 :  * The Initial Developer of the Original Code is IBM Corporation.
          19                 :  * Portions created by IBM Corporation are Copyright (C) 2003
          20                 :  * IBM Corporation. All Rights Reserved.
          21                 :  *
          22                 :  * Contributor(s):
          23                 :  *   Darin Fisher <darin@meer.net>
          24                 :  *
          25                 :  * Alternatively, the contents of this file may be used under the terms of
          26                 :  * either the GNU General Public License Version 2 or later (the "GPL"), or
          27                 :  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
          28                 :  * in which case the provisions of the GPL or the LGPL are applicable instead
          29                 :  * of those above. If you wish to allow use of your version of this file only
          30                 :  * under the terms of either the GPL or the LGPL, and not to allow others to
          31                 :  * use your version of this file under the terms of the MPL, indicate your
          32                 :  * decision by deleting the provisions above and replace them with the notice
          33                 :  * and other provisions required by the GPL or the LGPL. If you do not delete
          34                 :  * the provisions above, a recipient may use your version of this file under
          35                 :  * the terms of any one of the MPL, the GPL or the LGPL.
          36                 :  *
          37                 :  * ***** END LICENSE BLOCK ***** */
          38                 :
          39                 : #ifndef nsStringBuffer_h__
          40                 : #define nsStringBuffer_h__
          41                 :
          42                 :
          43                 : /**
          44                 :  * This structure precedes the string buffers "we" allocate.  It may be the
          45                 :  * case that nsTAString::mData does not point to one of these special
          46                 :  * buffers.  The mFlags member variable distinguishes the buffer type.
          47                 :  *
          48                 :  * When this header is in use, it enables reference counting, and capacity
          49                 :  * tracking.  NOTE: A string buffer can be modified only if its reference
          50                 :  * count is 1.
          51                 :  */
          52                 : class nsStringBuffer
          53                 :   {
          54                 :     private:
          55                 :       friend class CheckStaticAtomSizes;
          56                 :
          57                 :       PRInt32  mRefCount;
          58                 :       PRUint32 mStorageSize;
          59                 :
          60                 :     public:
          61                 :
          62                 :       /**
          63                 :        * Allocates a new string buffer, with given size in bytes and a
          64                 :        * reference count of one.  When the string buffer is no longer needed,
          65                 :        * it should be released via Release.
          66                 :        *
          67                 :        * It is up to the caller to set the bytes corresponding to the string
          68                 :        * buffer by calling the Data method to fetch the raw data pointer.  Care
          69                 :        * must be taken to properly null terminate the character array.  The
          70                 :        * storage size can be greater than the length of the actual string
          71                 :        * (i.e., it is not required that the null terminator appear in the last
          72                 :        * storage unit of the string buffer's data).
          73                 :        *
          74                 :        * @return new string buffer or null if out of memory.
          75                 :        */
          76                 :       static nsStringBuffer* Alloc(size_t storageSize);
          77                 :
          78                 :       /**
          79                 :        * Resizes the given string buffer to the specified storage size.  This
          80                 :        * method must not be called on a readonly string buffer.  Use this API
          81                 :        * carefully!!
          82                 :        *
          83                 :        * This method behaves like the ANSI-C realloc function.  (i.e., If the
          84                 :        * allocation fails, null will be returned and the given string buffer
          85                 :        * will remain unmodified.)
          86                 :        *
          87                 :        * @see IsReadonly
          88                 :        */
          89                 :       static nsStringBuffer* Realloc(nsStringBuffer* buf, size_t storageSize);
          90                 :
          91                 :       /**
          92                 :        * Increment the reference count on this string buffer.
          93                 :        */
          94                 :       void NS_FASTCALL AddRef();
          95                 :
          96                 :       /**
          97                 :        * Decrement the reference count on this string buffer.  The string
          98                 :        * buffer will be destroyed when its reference count reaches zero.
          99                 :        */
         100                 :       void NS_FASTCALL Release();
         101                 :
         102                 :       /**
         103                 :        * This method returns the string buffer corresponding to the given data
         104                 :        * pointer.  The data pointer must have been returned previously by a
         105                 :        * call to the nsStringBuffer::Data method.
         106                 :        */
         107        34056570 :       static nsStringBuffer* FromData(void* data)
         108                 :         {
         109        34056570 :           return reinterpret_cast<nsStringBuffer*> (data) - 1;
         110                 :         }
         111                 :
         112                 :       /**
         113                 :        * This method returns the data pointer for this string buffer.
         114                 :        */
         115        24014007 :       void* Data() const
         116                 :         {
         117        24014007 :           return const_cast<char*> (reinterpret_cast<const char*> (this + 1));
         118                 :         }
         119                 :
         120                 :       /**
         121                 :        * This function returns the storage size of a string buffer in bytes.
         122                 :        * This value is the same value that was originally passed to Alloc (or
         123                 :        * Realloc).
         124                 :        */
         125        11040546 :       PRUint32 StorageSize() const
         126                 :         {
         127        11040546 :           return mStorageSize;
         128                 :         }
         129                 :
         130                 :       /**
         131                 :        * If this method returns false, then the caller can be sure that their
         132                 :        * reference to the string buffer is the only reference to the string
         133                 :        * buffer, and therefore it has exclusive access to the string buffer and
         134                 :        * associated data.  However, if this function returns true, then other
         135                 :        * consumers may rely on the data in this buffer being immutable and
         136                 :        * other threads may access this buffer simultaneously.
         137                 :        */
         138         7182862 :       bool IsReadonly() const
         139                 :         {
         140         7182862 :           return mRefCount > 1;
         141                 :         }
         142                 :
         143                 :       /**
         144                 :        * The FromString methods return a string buffer for the given string
         145                 :        * object or null if the string object does not have a string buffer.
         146                 :        * The reference count of the string buffer is NOT incremented by these
         147                 :        * methods.  If the caller wishes to hold onto the returned value, then
         148                 :        * the returned string buffer must have its reference count incremented
         149                 :        * via a call to the AddRef method.
         150                 :        */
         151                 :       static nsStringBuffer* FromString(const nsAString &str);
         152                 :       static nsStringBuffer* FromString(const nsACString &str);
         153                 :
         154                 :       /**
         155                 :        * The ToString methods assign this string buffer to a given string
         156                 :        * object.  If the string object does not support sharable string
         157                 :        * buffers, then its value will be set to a copy of the given string
         158                 :        * buffer.  Otherwise, these methods increment the reference count of the
         159                 :        * given string buffer.  It is important to specify the length (in
         160                 :        * storage units) of the string contained in the string buffer since the
         161                 :        * length of the string may be less than its storage size.  The string
         162                 :        * must have a null terminator at the offset specified by |len|.
         163                 :        *
         164                 :        * NOTE: storage size is measured in bytes even for wide strings;
         165                 :        *       however, string length is always measured in storage units
         166                 :        *       (2-byte units for wide strings).
         167                 :        */
         168                 :       void ToString(PRUint32 len, nsAString &str,
         169                 :                            bool aMoveOwnership = false);
         170                 :       void ToString(PRUint32 len, nsACString &str,
         171                 :                            bool aMoveOwnership = false);
         172                 :
         173                 :       /**
         174                 :        * This measures the size.  It should only be used if the StringBuffer is
         175                 :        * unshared.  This is checked.
         176                 :        */
         177                 :       size_t SizeOfIncludingThisMustBeUnshared(nsMallocSizeOfFun aMallocSizeOf) const;
         178                 :
         179                 :       /**
         180                 :        * This measures the size only if the StringBuffer is unshared.
         181                 :        */
         182                 :       size_t SizeOfIncludingThisIfUnshared(nsMallocSizeOfFun aMallocSizeOf) const;
         183                 :   };
         184                 :
         185                 : #endif /* !defined(nsStringBuffer_h__ */

Generated by: LCOV version 1.7