Public Member Functions | Static Public Member Functions

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.
void * Data () 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)

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.


Member Function Documentation

NS_COM void NS_FASTCALL nsStringBuffer::AddRef (  ) 

Increment the reference count on this string buffer.

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

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

Returns:
new string buffer or null if out of memory.
void* nsStringBuffer::Data (  )  const [inline]

This method returns the data pointer for this string buffer.

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.

static NS_COM 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.

static NS_COM nsStringBuffer* nsStringBuffer::FromString ( const nsACString str  )  [static]
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.

static NS_COM 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
NS_COM void NS_FASTCALL nsStringBuffer::Release (  ) 

Decrement the reference count on this string buffer.

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

PRUint32 nsStringBuffer::StorageSize (  )  const [inline]

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

NS_COM void nsStringBuffer::ToString ( PRUint32  len,
nsACString str 
)
NS_COM 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).


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