---

auto_buffer Class Template Reference

This class provides an efficient variable automatic buffer. More...

#include <stlsoft_auto_buffer.h>

List of all members.

Attributes
size_type	size () const
	Returns the number of elements in the auto_buffer.
ss_bool_t	empty () const
	Indicates whether the buffer has any contents.
size_type	internal_size ()
	Returns the number of elements in the auto_buffer's internal buffer.
Public Types
Types
typedef T	value_type
	The value type.
typedef A	allocator_type
	The allocator type.
typedef auto_buffer< T, A, space >	class_type
	The type of the current parameterisation.
typedef allocator_type::reference	reference
	The reference type.
typedef allocator_type::const_reference	const_reference
	The non-mutable (const) reference type.
typedef allocator_type::pointer	pointer
	The pointer type.
typedef allocator_type::const_pointer	const_pointer
	The non-mutable (const) pointer type.
typedef ss_size_t	size_type
	The size type.
typedef ss_ptrdiff_t	difference_type
	The difference type.
typedef pointer_iterator< value_type, pointer, reference >::iterator_type	iterator
	The iterator type.
typedef pointer_iterator< value_type const, const_pointer, const_reference >::iterator_type	const_iterator
	The non-mutating (const) iterator type.
typedef reverse_iterator_base< iterator, value_type, reference, pointer, difference_type >	reverse_iterator
	The mutating (non-const) reverse iterator type.
typedef const_reverse_iterator_base< const_iterator, value_type const, const_reference, const_pointer, difference_type >	const_reverse_iterator
	The non-mutating (const) reverse iterator type.
enum	{ space = SPACE }
Public Methods
Construction
	auto_buffer (size_type cItems)
	Constructs an auto_buffer with the given number of elements.
	~auto_buffer ()
	Releases the allocated element array.
Operations
ss_bool_t	resize (size_type cItems)
	Expands or contracts the number of items in the buffer.
void	swap (class_type &rhs)
	Swaps contents with the given buffer.
Operators
	operator pointer ()
	An implicit conversion to a pointer to the start of the element array.
Accessors
pointer	data ()
	Returns a pointer to the element array.
const_pointer	data () const
	Returns a pointer-to-const to the element array.
Iteration
const_iterator	begin () const
	Returns a non-mutating iterator representing the start of the sequence.
const_iterator	end () const
	Returns a non-mutating iterator representing the end of the sequence.
iterator	begin ()
	Returns a mutable iterator representing the start of the sequence.
iterator	end ()
	Returns a mutable iterator representing the end of the sequence.
const_reverse_iterator	rbegin () const
	Begins the reverse iteration.
const_reverse_iterator	rend () const
	Ends the reverse iteration.
reverse_iterator	rbegin ()
	Begins the reverse iteration.
reverse_iterator	rend ()
	Ends the reverse iteration.

---

Detailed Description

template<typename T, typename A, ss_size_t SPACE = 256>
class stlsoft::auto_buffer< T, A, SPACE >

This class provides an efficient variable automatic buffer.

This class provides an efficient replacement for dynamic memory block allocation when the block size generally falls under a certain limit. In such cases, significant performance benefits can be achieved by using an instance of a parameterisation of auto_buffer, whose size parameter SPACE is set to a level to cater for most of the requested sizes. Only where the size of the buffer needs to be larger than this limit does an allocation occur from the heap/free-store via the given allocator.

Note:

The buffer works correctly whether the given allocator throws an exception on allocation failure, or returns NULL.

Parameters:

T	The type of the elements in the array
A	The allocator type
SPACE	The number of elements in the array. With translators that support default template arguments, this is defaulted to 256

---

Member Typedef Documentation

typedef A allocator_type

The allocator type.

typedef auto_buffer<T, A, space> class_type

The type of the current parameterisation.

typedef pointer_iterator< value_type const , const_pointer , const_reference >::iterator_type const_iterator

The non-mutating (const) iterator type.

typedef allocator_type::const_pointer const_pointer

The non-mutable (const) pointer type.

typedef allocator_type::const_reference const_reference

The non-mutable (const) reference type.

typedef const_reverse_iterator_base< const_iterator , value_type const , const_reference , const_pointer , difference_type > const_reverse_iterator

The non-mutating (const) reverse iterator type.

typedef ss_ptrdiff_t difference_type

The difference type.

typedef pointer_iterator< value_type , pointer , reference >::iterator_type iterator

The iterator type.

typedef allocator_type::pointer pointer

The pointer type.

typedef allocator_type::reference reference

The reference type.

typedef reverse_iterator_base< iterator , value_type , reference , pointer , difference_type > reverse_iterator

The mutating (non-const) reverse iterator type.

typedef ss_size_t size_type

The size type.

typedef T value_type

The value type.

---

Member Enumeration Documentation

anonymous enum

Enumeration values: space  The number of items in the internal buffer.

---

Constructor & Destructor Documentation

auto_buffer (  size_type    cItems )  [inline, explicit]

Constructs an auto_buffer with the given number of elements. Constructs an auto_buffer with the given number of elements. If the allocation fails by throwing an exception, that exception is passed through to the caller. If allocation fails by returning a null pointer the auto_buffer instance is correctly constructed, and the size() method returns 0. See also: size() Parameters: cItems  The number of items in the constructed instance

~auto_buffer (    )  [inline]

Releases the allocated element array. Releases any allocated memory. If the internal memory buffer was used, then nothing is done, otherwise the allocated memory is returned to the allocator.

---

Member Function Documentation

iterator begin (    )  [inline]

Returns a mutable iterator representing the start of the sequence.

const_iterator begin (    )  const [inline]

Returns a non-mutating iterator representing the start of the sequence.

const_pointer data (    )  const [inline]

Returns a pointer-to-const to the element array.

pointer data (    )  [inline]

Returns a pointer to the element array.

ss_bool_t empty (    )  const [inline]

Indicates whether the buffer has any contents. Note: This will only ever be true when an allocation above the number of elements in the internal array has been requested, and failed.

iterator end (    )  [inline]

Returns a mutable iterator representing the end of the sequence. Note: In the case where memory allocation has failed in the context where exceptions are not thrown for allocation failure, this method will return the same value as begin(). Hence, operations on the empty auto_buffer<> instance will be safe if made in respect of the range defined by [begin(), end()).

const_iterator end (    )  const [inline]

Returns a non-mutating iterator representing the end of the sequence. Note: In the case where memory allocation has failed in the context where exceptions are not thrown for allocation failure, this method will return the same value as begin(). Hence, operations on the empty auto_buffer<> instance will be safe if made in respect of the range defined by [begin(), end()).

size_type internal_size (    )  [inline, static]

Returns the number of elements in the auto_buffer's internal buffer.

operator pointer (    )  [inline]

An implicit conversion to a pointer to the start of the element array.

reverse_iterator rbegin (    )  [inline]

Begins the reverse iteration. Returns: An iterator representing the start of the reverse sequence

const_reverse_iterator rbegin (    )  const [inline]

Begins the reverse iteration. Returns: An iterator representing the start of the reverse sequence

reverse_iterator rend (    )  [inline]

Ends the reverse iteration. Returns: An iterator representing the end of the reverse sequence

const_reverse_iterator rend (    )  const [inline]

Ends the reverse iteration. Returns: An iterator representing the end of the reverse sequence

ss_bool_t resize (  size_type    cItems )  [inline]

Expands or contracts the number of items in the buffer. Parameters: cItems  The number of items to change in the buffer Returns: Returns true if successful. Function failure occurs when sufficient storage for the requested items cannot be allocated. In that case, std::bad_alloc will be throw for allocators that support it, otherwise the function will return false. In either case, the original storage and contents of the buffer will remain unchanged. Note: When reducing the number of elements, the implementation favours speed above memory consumption. If the new item size is still larger than the internal storage size (internal_size()) then the heap allocated block will not be changed (i.e. it will not be exchanged for a smaller block).

size_type size (    )  const [inline]

Returns the number of elements in the auto_buffer. Note: In the case where memory allocation has failed in the context where exceptions are not thrown for allocation failure in the constructor, this method will return 0. Hence, operations on the empty auto_buffer<> instance will be safe if made in respect of the value returned by this method.

void swap (  class_type &    rhs )  [inline]

Swaps contents with the given buffer. Note: This method is only constant time when the memory for two buffers has been acquired via the allocator. Otherwise, it will depend on the costs of exchanging the memory

---

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

• stlsoft_auto_buffer.h

STLSoft Libraries documentation © Synesis Software Pty Ltd, 2001-2004