Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Static Public Member Functions | Private Attributes
nsStringBuffer Class Reference

This structure precedes the string buffers "we" allocate. More...

#include <nsStringBuffer.h>

List of all members.

Public Member Functions

NS_COM void NS_FASTCALL AddRef ()
 Increment the reference count on this string buffer.
NS_COM void NS_FASTCALL Release ()
 Decrement the reference count on this string buffer.
voidData () const
 This method returns the data pointer for this string buffer.
PRUint32 StorageSize () const
 This function returns the storage size of a string buffer in bytes.
PRBool IsReadonly () const
 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.
NS_COM void ToString (PRUint32 len, nsAString &str)
 The ToString methods assign this string buffer to a given string object.
NS_COM void ToString (PRUint32 len, nsACString &str)

Static Public Member Functions

static NS_COM nsStringBufferAlloc (size_t storageSize)
 Allocates a new string buffer, with given size in bytes and a reference count of one.
static NS_COM nsStringBufferRealloc (nsStringBuffer *buf, size_t storageSize)
 Resizes the given string buffer to the specified storage size.
static nsStringBufferFromData (void *data)
 This method returns the string buffer corresponding to the given data pointer.
static NS_COM nsStringBufferFromString (const nsAString &str)
 The FromString methods return a string buffer for the given string object or null if the string object does not have a string buffer.
static NS_COM nsStringBufferFromString (const nsACString &str)

Private Attributes

PRInt32 mRefCount
PRUint32 mStorageSize

Detailed Description

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.

Definition at line 51 of file nsStringBuffer.h.


Member Function Documentation

Increment the reference count on this string buffer.

Definition at line 177 of file nsSubstring.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

nsStringBuffer * nsStringBuffer::Alloc ( size_t  storageSize) [static]

Allocates a new string buffer, with given size in bytes and a reference count of one.

Alloc returns a pointer to a new string header with set capacity.

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).

Returns:
new string buffer or null if out of memory.

Definition at line 197 of file nsSubstring.cpp.

  {
    STRING_STAT_INCREMENT(Alloc);

    NS_ASSERTION(size != 0, "zero capacity allocation not allowed");

    nsStringBuffer *hdr =
        (nsStringBuffer *) malloc(sizeof(nsStringBuffer) + size);
    if (hdr)
      {
        hdr->mRefCount = 1;
        hdr->mStorageSize = size;
      }
    return hdr;
  }

Here is the caller graph for this function:

void* nsStringBuffer::Data ( ) const [inline]

This method returns the data pointer for this string buffer.

Definition at line 113 of file nsStringBuffer.h.

        {
          return (void*) ( ((char*) this) + sizeof(nsStringBuffer) );
        }

Here is the caller graph for this function:

static nsStringBuffer* nsStringBuffer::FromData ( void data) [inline, static]

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.

Definition at line 105 of file nsStringBuffer.h.

        {
          return (nsStringBuffer*) ( ((char*) data) - sizeof(nsStringBuffer) );
        }

Here is the caller graph for this function:

nsStringBuffer * nsStringBuffer::FromString ( const nsAString &  str) [static]

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.

Definition at line 231 of file nsSubstring.cpp.

  {
    const nsAStringAccessor* accessor =
        NS_STATIC_CAST(const nsAStringAccessor*, &str);

#ifdef MOZ_V1_STRING_ABI
    if (accessor->vtable() != nsObsoleteAString::sCanonicalVTable)
      return nsnull;
#endif
    if (!(accessor->flags() & nsSubstring::F_SHARED))
      return nsnull;

    return FromData(accessor->data());
  }

Here is the call graph for this function:

Here is the caller graph for this function:

nsStringBuffer * nsStringBuffer::FromString ( const nsACString &  str) [static]

Definition at line 247 of file nsSubstring.cpp.

  {
    const nsACStringAccessor* accessor =
        NS_STATIC_CAST(const nsACStringAccessor*, &str);

#ifdef MOZ_V1_STRING_ABI
    if (accessor->vtable() != nsObsoleteACString::sCanonicalVTable)
      return nsnull;
#endif
    if (!(accessor->flags() & nsCSubstring::F_SHARED))
      return nsnull;

    return FromData(accessor->data());
  }

Here is the call graph for this function:

PRBool nsStringBuffer::IsReadonly ( ) const [inline]

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.

Definition at line 136 of file nsStringBuffer.h.

        {
          return mRefCount > 1;
        }

Here is the caller graph for this function:

nsStringBuffer * nsStringBuffer::Realloc ( nsStringBuffer buf,
size_t  storageSize 
) [static]

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 also:
IsReadonly

Definition at line 214 of file nsSubstring.cpp.

  {
    STRING_STAT_INCREMENT(Realloc);

    NS_ASSERTION(size != 0, "zero capacity allocation not allowed");

    // no point in trying to save ourselves if we hit this assertion
    NS_ASSERTION(!hdr->IsReadonly(), "|Realloc| attempted on readonly string");

    hdr = (nsStringBuffer*) realloc(hdr, sizeof(nsStringBuffer) + size);
    if (hdr)
      hdr->mStorageSize = size;

    return hdr;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Decrement the reference count on this string buffer.

The string buffer will be destroyed when its reference count reaches zero.

Definition at line 184 of file nsSubstring.cpp.

  {
    if (PR_AtomicDecrement(&mRefCount) == 0)
      {
        STRING_STAT_INCREMENT(Free);
        free(this); // we were allocated with |malloc|
      }
  }

Here is the call graph for this function:

Here is the caller graph for this function:

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).

Definition at line 123 of file nsStringBuffer.h.

        {
          return mStorageSize;
        }

Here is the caller graph for this function:

void nsStringBuffer::ToString ( PRUint32  len,
nsAString &  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).

Definition at line 263 of file nsSubstring.cpp.

  {
    PRUnichar* data = NS_STATIC_CAST(PRUnichar*, Data());

    nsAStringAccessor* accessor = NS_STATIC_CAST(nsAStringAccessor*, &str);
#ifdef MOZ_V1_STRING_ABI
    if (accessor->vtable() != nsObsoleteAString::sCanonicalVTable)
      {
        str.Assign(data, len);
        return;
      }
#endif
    NS_ASSERTION(data[len] == PRUnichar(0), "data should be null terminated");

    // preserve class flags
    PRUint32 flags = accessor->flags();
    flags = (flags & 0xFFFF0000) | nsSubstring::F_SHARED | nsSubstring::F_TERMINATED;

    AddRef();
    accessor->set(data, len, flags);
  }

Here is the call graph for this function:

Here is the caller graph for this function:

void nsStringBuffer::ToString ( PRUint32  len,
nsACString &  str 
)

Definition at line 286 of file nsSubstring.cpp.

  {
    char* data = NS_STATIC_CAST(char*, Data());

    nsACStringAccessor* accessor = NS_STATIC_CAST(nsACStringAccessor*, &str);
#ifdef MOZ_V1_STRING_ABI
    if (accessor->vtable() != nsObsoleteACString::sCanonicalVTable)
      {
        str.Assign(data, len);
        return;
      }
#endif
    NS_ASSERTION(data[len] == char(0), "data should be null terminated");

    // preserve class flags
    PRUint32 flags = accessor->flags();
    flags = (flags & 0xFFFF0000) | nsCSubstring::F_SHARED | nsCSubstring::F_TERMINATED;

    AddRef();
    accessor->set(data, len, flags);
  }

Here is the call graph for this function:


Member Data Documentation

Definition at line 55 of file nsStringBuffer.h.

Definition at line 56 of file nsStringBuffer.h.


The documentation for this class was generated from the following files: