casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | List of all members
casacore::Block< T > Class Template Reference

simple 1-D array More...

#include <Allocator.h>

Inheritance diagram for casacore::Block< T >:
casacore::BlockTrace

Public Member Functions

 Block ()
 Create a zero-length Block. More...
 
template<typename Allocator >
 Block (AllocSpec< Allocator > const &)
 Create a zero-length Block. More...
 
 Block (size_t n)
 Create a Block with the given number of points. More...
 
template<typename Allocator >
 Block (size_t n, AllocSpec< Allocator > const &)
 Create a Block with the given number of points. More...
 
 Block (size_t n, ArrayInitPolicy initPolicy)
 Create a Block with the given number of points. More...
 
template<typename Allocator >
 Block (size_t n, ArrayInitPolicy initPolicy, AllocSpec< Allocator > const &)
 Create a Block with the given number of points. More...
 
 Block (size_t n, T const &val)
 Create a Block of the given length, and initialize (via copy constructor for objects of type T) with the provided value. More...
 
template<typename Allocator >
 Block (size_t n, T const &val, AllocSpec< Allocator > const &)
 Create a Block of the given length, and initialize (via copy constructor for objects of type T) with the provided value. More...
 
 Block (size_t n, T *&storagePointer, Bool takeOverStorage=True)
 Create a Block from a C-array (i.e. More...
 
template<typename Allocator >
 Block (size_t n, T *&storagePointer, Bool takeOverStorage, AllocSpec< Allocator > const &)
 Create a Block from a C-array (i.e. More...
 
 Block (const Block< T > &other)
 Copy the other block into this one. More...
 
Block< T > & operator= (const Block< T > &other)
 Assign other to this. More...
 
 ~Block ()
 Frees up the storage pointed contained in the Block. More...
 
void resize (size_t n, Bool forceSmaller=False, Bool copyElements=True)
 Resizes the Block. More...
 
void resize (size_t n, Bool forceSmaller, Bool copyElements, ArrayInitPolicy initPolicy)
 
void remove (size_t whichOne, Bool forceSmaller=True)
 Remove a single element from the Block. More...
 
void remove (size_t whichOne, Bool forceSmaller, ArrayInitPolicy initPolicy)
 
void prohibitChangingAllocator ()
 Prohibit changing allocator for this instance. More...
 
void permitChangingAllocator ()
 Permit changing allocator for this instance. More...
 
void replaceStorage (size_t n, T *&storagePointer, Bool takeOverStorage=True)
 Replace the internal storage with a C-array (i.e. More...
 
template<typename Allocator >
void replaceStorage (size_t n, T *&storagePointer, Bool takeOverStorage, AllocSpec< Allocator > const &)
 
T & operator[] (size_t index)
 Index into the block (0-based). More...
 
const T & operator[] (size_t index) const
 
Block< T > & operator= (const T &val)
 Set all values in the block to "val". More...
 
void set (const T &val)
 
T * storage ()
 If you really, really, need a "raw" pointer to the beginning of the storage area this will give it to you. More...
 
const T * storage () const
 
size_t nelements () const
 The number of elements contained in this Block<T>. More...
 
size_t size () const
 
size_t capacity () const
 The capacity in this Block<T>. More...
 
Bool empty () const
 Is the block empty (i.e. More...
 
typedef T value_type
 Define the STL-style iterators. More...
 
typedef T * iterator
 
typedef const T * const_iterator
 
typedef value_typepointer
 
typedef const value_typeconst_pointer
 
typedef value_typereference
 
typedef const value_typeconst_reference
 
typedef size_t size_type
 
typedef ptrdiff_t difference_type
 
class Array< T >
 
Allocator_private::BulkAllocator
< T > * 
allocator_p
 The allocator. More...
 
size_t capacity_p
 The capacity of the vector. More...
 
size_t used_p
 The number of used elements in the vector. More...
 
T * array
 The actual storage. More...
 
Bool destroyPointer
 Can we delete the storage upon destruction? More...
 
Bool keep_allocator_p
 Can we change allocator or not? More...
 
iterator begin ()
 Get the begin and end iterator object for this block. More...
 
const_iterator begin () const
 
iterator end ()
 
const_iterator end () const
 
void traceAlloc (const void *addr, size_t sz) const
 
void traceFree (const void *addr, size_t sz) const
 
 Block (size_t n, ArrayInitPolicy initPolicy, Allocator_private::BulkAllocator< T > *allocator)
 
 Block (size_t n, Allocator_private::AllocSpec< T > allocator)
 
 Block (size_t n, T *&storagePointer, Bool takeOverStorage, Allocator_private::BulkAllocator< T > *allocator)
 
void construct (size_t pos, size_t n, T const *src)
 
void construct (size_t pos, size_t n, T const &initial_value)
 
void construct (size_t pos, size_type n)
 
void destroy (size_t pos, size_type n)
 
Allocator_private::BulkAllocator
< T > * 
get_allocator ()
 
void init (ArrayInitPolicy initPolicy)
 end of friend More...
 
void deinit ()
 
void dealloc ()
 
template<typename Allocator >
Bool isCompatibleAllocator ()
 
size_t get_size () const
 The number of used elements in the vector. More...
 
void set_size (size_t new_value)
 Set the number of used elements in the vector. More...
 
size_t get_capacity () const
 The capacity of the vector. More...
 
void set_capacity (size_t new_value)
 Set the capacity of the vector. More...
 
static bool init_anyway ()
 
template<typename Allocator >
static
Allocator_private::BulkAllocator
< typename
Allocator::value_type > * 
get_allocator ()
 

Additional Inherited Members

- Static Public Member Functions inherited from casacore::BlockTrace
static void setTraceSize (size_t sz)
 Set the trace size. More...
 
- Static Protected Member Functions inherited from casacore::BlockTrace
static void doTraceAlloc (const void *addr, size_t nelem, DataType type, size_t sz)
 Write alloc and free trace messages. More...
 
static void doTraceFree (const void *addr, size_t nelem, DataType type, size_t sz)
 
- Static Protected Attributes inherited from casacore::BlockTrace
static size_t itsTraceSize
 

Detailed Description

template<typename T>
class casacore::Block< T >

simple 1-D array

forward declarations:

Intended use:

Public interface

Review Status

Reviewed By:
UNKNOWN
Date Reviewed:
before2004/08/25

Etymology

This should be viewed as a block of memory without sophisticated manipulation functions. Thus it is called Block.

Synopsis

Block<T> is a simple templated 1-D array class. Indices are always 0-based. For efficiency reasons, no index checking is done unless the preprocessor symbol AIPS_ARRAY_INDEX_CHECK is defined. Block<T>'s may be assigned to and constructed from other Block<T>'s. As no reference counting is done this can be an expensive operation, however.

The net effect of this class is meant to be unsurprising to users who think of arrays as first class objects. The name "Block" is intended to convey the concept of a solid "chunk" of things without any intervening "fancy" memory management, etc. This class was written to be used in the implementations of more functional Vector, Matrix, etc. classes, although it is expected Block<T> will be useful on its own.

The Block class should be efficient. You should normally use Block.


Warning: If you use the assignment operator on an element of this class, you may leave dangling references to pointers released from storage(); Resizing the array will also have this effect if the underlying storage is actually affected;

If index checking is turned on, an out-of-bounds index will generate an indexError<uInt> exception.

Example

Block<Int> a(100,0); // 100 ints initialized to 0
Block<Int> b; // 0-length Block
//..\.
b = a; // resize b and copy a into it
for (size_t i=0; i < a.nelements(); i++) {
a[i] = i; // Generate a sequence
// with Vectors, could simply say "indgen(myVector);"
}
b.set(-1); // All positions in b have the value -1
b.resize(b.nelements()*2); // Make b twice as long, by default the old
// elements are copied over, although this can
// be defeated.
some_c_function(b.storage()); // Use a fn that takes an
// <tt>Int *</tt> pointer

Definition at line 210 of file Allocator.h.

Member Typedef Documentation

template<typename T>
typedef const T* casacore::Block< T >::const_iterator

Definition at line 635 of file Block.h.

template<typename T>
typedef const value_type* casacore::Block< T >::const_pointer

Definition at line 637 of file Block.h.

template<typename T>
typedef const value_type& casacore::Block< T >::const_reference

Definition at line 639 of file Block.h.

template<typename T>
typedef ptrdiff_t casacore::Block< T >::difference_type

Definition at line 641 of file Block.h.

template<typename T>
typedef T* casacore::Block< T >::iterator

Definition at line 634 of file Block.h.

template<typename T>
typedef value_type* casacore::Block< T >::pointer

Definition at line 636 of file Block.h.

template<typename T>
typedef value_type& casacore::Block< T >::reference

Definition at line 638 of file Block.h.

template<typename T>
typedef size_t casacore::Block< T >::size_type

Definition at line 640 of file Block.h.

template<typename T>
typedef T casacore::Block< T >::value_type

Define the STL-style iterators.

It makes it possible to iterate through all data elements.

Block<Int> bl(100,0);
for (Block<Int>::iterator iter=bl.begin(); iter!=bl.end(); iter++) {
*iter += 1;
}

STL-style typedefs.

Definition at line 633 of file Block.h.

Constructor & Destructor Documentation

template<typename T>
casacore::Block< T >::Block ( )
inline

Create a zero-length Block.

Note that any index into this Block is an error. DefaultAllocator<T> is used as an allocator.

Definition at line 205 of file Block.h.

template<typename T>
template<typename Allocator >
casacore::Block< T >::Block ( AllocSpec< Allocator > const &  )
inlineexplicit

Create a zero-length Block.

Note that any index into this Block is an error.

Definition at line 212 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( size_t  n)
inlineexplicit

Create a Block with the given number of points.

The values in Block are initialized. Note that indices range between 0 and n-1. DefaultAllocator<T> is used as an allocator.

Definition at line 220 of file Block.h.

template<typename T>
template<typename Allocator >
casacore::Block< T >::Block ( size_t  n,
AllocSpec< Allocator > const &   
)
inline

Create a Block with the given number of points.

The values in Block are initialized. Note that indices range between 0 and n-1.

Definition at line 229 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( size_t  n,
ArrayInitPolicy  initPolicy 
)
inline

Create a Block with the given number of points.

The values in Block are uninitialized. Note that indices range between 0 and n-1. DefaultAllocator<T> is used as an allocator.

Definition at line 238 of file Block.h.

template<typename T>
template<typename Allocator >
casacore::Block< T >::Block ( size_t  n,
ArrayInitPolicy  initPolicy,
AllocSpec< Allocator > const &   
)
inline

Create a Block with the given number of points.

Note that indices range between 0 and n-1.

Definition at line 247 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( size_t  n,
T const &  val 
)
inline

Create a Block of the given length, and initialize (via copy constructor for objects of type T) with the provided value.

DefaultAllocator<T> is used as an allocator.

Definition at line 257 of file Block.h.

template<typename T>
template<typename Allocator >
casacore::Block< T >::Block ( size_t  n,
T const &  val,
AllocSpec< Allocator > const &   
)
inline

Create a Block of the given length, and initialize (via copy constructor for objects of type T) with the provided value.

Definition at line 272 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( size_t  n,
T *&  storagePointer,
Bool  takeOverStorage = True 
)
inline

Create a Block from a C-array (i.e.

pointer). If takeOverStorage is True, The Block assumes that it owns the pointer, i.e. that it is safe to release it via allocator when the Block is destructed, otherwise the actual storage is not destroyed. If true, storagePointer is set to 0. It is strongly recommended to supply an appropriate allocator argument explicitly whenever takeOverStorage == True to let Block to know how to release the storagePointer. The default allocator set by this constructor will be changed from NewDelAllocator<T>value to DefaultAllocator<T>value in future.

Definition at line 294 of file Block.h.

template<typename T>
template<typename Allocator >
casacore::Block< T >::Block ( size_t  n,
T *&  storagePointer,
Bool  takeOverStorage,
AllocSpec< Allocator > const &   
)
inline

Create a Block from a C-array (i.e.

pointer). If takeOverStorage is True, The Block assumes that it owns the pointer, i.e. that it is safe to release it via allocator when the Block is destructed, otherwise the actual storage is not destroyed. If true, storagePointer is set to 0.

Definition at line 307 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( const Block< T > &  other)
inline

Copy the other block into this one.

Uses copy, not reference, semantics.

objcopy(array, other.array, get_size());

Definition at line 317 of file Block.h.

template<typename T>
casacore::Block< T >::~Block ( )
inline

Frees up the storage pointed contained in the Block.

Definition at line 349 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( size_t  n,
ArrayInitPolicy  initPolicy,
Allocator_private::BulkAllocator< T > *  allocator 
)
inlineprivate

Definition at line 672 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( size_t  n,
Allocator_private::AllocSpec< T >  allocator 
)
inlineprivate

Definition at line 678 of file Block.h.

template<typename T>
casacore::Block< T >::Block ( size_t  n,
T *&  storagePointer,
Bool  takeOverStorage,
Allocator_private::BulkAllocator< T > *  allocator 
)
inlineprivate

Definition at line 683 of file Block.h.

Member Function Documentation

template<typename T>
iterator casacore::Block< T >::begin ( )
inline

Get the begin and end iterator object for this block.

Definition at line 645 of file Block.h.

template<typename T>
const_iterator casacore::Block< T >::begin ( ) const
inline

Definition at line 647 of file Block.h.

template<typename T>
size_t casacore::Block< T >::capacity ( ) const
inline

The capacity in this Block<T>.

size() <= capacity() is always true.

Definition at line 617 of file Block.h.

template<typename T>
void casacore::Block< T >::construct ( size_t  pos,
size_t  n,
T const *  src 
)
inlineprivate

Definition at line 691 of file Block.h.

template<typename T>
void casacore::Block< T >::construct ( size_t  pos,
size_t  n,
T const &  initial_value 
)
inlineprivate

Definition at line 694 of file Block.h.

template<typename T>
void casacore::Block< T >::construct ( size_t  pos,
size_type  n 
)
inlineprivate

Definition at line 698 of file Block.h.

template<typename T>
void casacore::Block< T >::dealloc ( )
inlineprivate
template<typename T>
void casacore::Block< T >::deinit ( )
inlineprivate
template<typename T>
void casacore::Block< T >::destroy ( size_t  pos,
size_type  n 
)
inlineprivate

Definition at line 701 of file Block.h.

template<typename T>
Bool casacore::Block< T >::empty ( ) const
inline

Is the block empty (i.e.

no elements)?

Definition at line 620 of file Block.h.

Referenced by casacore::PtrBlock< casacore::RecordDesc * >::empty().

template<typename T>
iterator casacore::Block< T >::end ( )
inline

Definition at line 649 of file Block.h.

template<typename T>
const_iterator casacore::Block< T >::end ( ) const
inline

Definition at line 651 of file Block.h.

template<typename T>
Allocator_private::BulkAllocator<T>* casacore::Block< T >::get_allocator ( )
inlineprivate

Definition at line 704 of file Block.h.

template<typename T>
template<typename Allocator >
static Allocator_private::BulkAllocator< typename Allocator::value_type>* casacore::Block< T >::get_allocator ( )
inlinestaticprivate

Definition at line 749 of file Block.h.

template<typename T>
size_t casacore::Block< T >::get_capacity ( ) const
inlineprivate
template<typename T>
size_t casacore::Block< T >::get_size ( ) const
inlineprivate
template<typename T>
void casacore::Block< T >::init ( ArrayInitPolicy  initPolicy)
inlineprivate

end of friend

Definition at line 715 of file Block.h.

Referenced by casacore::Block< casacore::String >::Block().

template<typename T>
static bool casacore::Block< T >::init_anyway ( )
inlinestaticprivate
template<typename T>
template<typename Allocator >
Bool casacore::Block< T >::isCompatibleAllocator ( )
inlineprivate

Definition at line 755 of file Block.h.

template<typename T>
size_t casacore::Block< T >::nelements ( ) const
inline
template<typename T>
Block<T>& casacore::Block< T >::operator= ( const Block< T > &  other)
inline

Assign other to this.

this resizes itself to the size of other, so after the assignment, this->nelements() == other.nelements() always.

Definition at line 334 of file Block.h.

template<typename T>
Block<T>& casacore::Block< T >::operator= ( const T &  val)
inline

Set all values in the block to "val".

Definition at line 585 of file Block.h.

template<typename T>
T& casacore::Block< T >::operator[] ( size_t  index)
inline

Index into the block (0-based).

If the preprocessor symbol AIPS_ARRAY_INDEX_CHECK is defined, index checking will be done and an out-of-bounds index will cause an indexError<uInt> to be thrown. Note that valid indices range between 0 and nelements()-1.

Thrown Exceptions

Definition at line 561 of file Block.h.

template<typename T>
const T& casacore::Block< T >::operator[] ( size_t  index) const
inline

Definition at line 572 of file Block.h.

template<typename T>
void casacore::Block< T >::permitChangingAllocator ( )
inline

Permit changing allocator for this instance.

Definition at line 511 of file Block.h.

template<typename T>
void casacore::Block< T >::prohibitChangingAllocator ( )
inline

Prohibit changing allocator for this instance.

Definition at line 507 of file Block.h.

template<typename T>
void casacore::Block< T >::remove ( size_t  whichOne,
Bool  forceSmaller = True 
)
inline

Remove a single element from the Block.

If forceSmaller is True this will resize the Block and hence involve new memory allocations. This is relatively expensive so setting forceSmaller to False is preferred. When forceSmaller is False the Block is not resized but the elements with an index above the removed element are shuffled down by one. For backward compatibility forceSmaller is True by default.

initPolicy makes sense to determine whether new storage should be initialized or not before copying when forceSmaller is True.

Definition at line 444 of file Block.h.

Referenced by casacore::PtrBlock< casacore::RecordDesc * >::remove().

template<typename T>
void casacore::Block< T >::remove ( size_t  whichOne,
Bool  forceSmaller,
ArrayInitPolicy  initPolicy 
)
inline

Definition at line 448 of file Block.h.

template<typename T>
void casacore::Block< T >::replaceStorage ( size_t  n,
T *&  storagePointer,
Bool  takeOverStorage = True 
)
inline

Replace the internal storage with a C-array (i.e.

pointer). If takeOverStorage is True, The Block assumes that it owns the pointer, i.e. that it is safe to release it via allocator when the Blockis destructed, otherwise the actual storage is not destroyed. If true, storagePointer is set to NULL. It is strongly recommended to supply an appropriate allocator argument explicitly whenever takeOverStorage == True to let Block to know how to release the storagePointer. The default parameter of allocator will be changed from AllocSpec<NewDelAllocator<T> >value to AllocSpec<DefaultAllocator<T> >value in future. AipsError is thrown if allocator is incompatible with the current allocator of the instance and changing allocator is prohibited, even if takeOverStorage == False.

Definition at line 529 of file Block.h.

Referenced by casacore::Block< casacore::String >::replaceStorage(), and casacore::PtrBlock< casacore::RecordDesc * >::replaceStorage().

template<typename T>
template<typename Allocator >
void casacore::Block< T >::replaceStorage ( size_t  n,
T *&  storagePointer,
Bool  takeOverStorage,
AllocSpec< Allocator > const &   
)
inline

Definition at line 533 of file Block.h.

template<typename T>
void casacore::Block< T >::resize ( size_t  n,
Bool  forceSmaller = False,
Bool  copyElements = True 
)
inline

Resizes the Block.

If n == nelements() resize just returns. If a larger size is requested (n > nelements()) the Block always resizes. If the requested size is smaller (n < nelements()), by default the Block does not resize smaller, although it can be forced to with forceSmaller. The reasoning behind this is that often the user will just want a buffer of at least a certain size, and won't want to pay the cost of multiple resizings.

Block<float> bf(100, 0.0);
bf.resize(10); // bf.nelements() == 100
bf.resize(10, True) // bf.nelements() == 10
bf.resize(200) // bf.nelements() == 200

Normally the old elements are copied over (although if the Block is lengthened the trailing elements will have undefined values), however this can be turned off by setting copyElements to False.

This is written as three functions because default parameters do not always work properly with templates.

initPolicy makes sense to determine whether extended elements should be initialized or not when you enlarge Block.

Definition at line 377 of file Block.h.

Referenced by casacore::Block< casacore::String >::operator=(), casacore::ConcatRows::reserve(), casacore::Block< casacore::String >::resize(), and casacore::PtrBlock< casacore::RecordDesc * >::resize().

template<typename T>
void casacore::Block< T >::resize ( size_t  n,
Bool  forceSmaller,
Bool  copyElements,
ArrayInitPolicy  initPolicy 
)
inline

Definition at line 381 of file Block.h.

template<typename T>
void casacore::Block< T >::set ( const T &  val)
inline

Definition at line 587 of file Block.h.

Referenced by casacore::PtrBlock< casacore::RecordDesc * >::set().

template<typename T>
void casacore::Block< T >::set_capacity ( size_t  new_value)
inlineprivate
template<typename T>
void casacore::Block< T >::set_size ( size_t  new_value)
inlineprivate
template<typename T>
size_t casacore::Block< T >::size ( ) const
inline
template<typename T>
T* casacore::Block< T >::storage ( )
inline

If you really, really, need a "raw" pointer to the beginning of the storage area this will give it to you.

This may leave dangling pointers if the block is destructed or if the assignment operator or resize is used. Returns a null pointer if nelements() == 0. It is best to only use this if you completely control the extent and lifetime of the Block.

Examples of misuse

Block<Int> *bp = new Block<Int>(100);
Int *ip = bp->storage();
DefaultAllocator<Int>::value.deallocate(bp, bp->capacity()); // Oops, ip is now dangling
Block<Int> a(100),b(100);
Int *ip = a.storage();
a = b; // Likewise

Definition at line 605 of file Block.h.

Referenced by casacore::PtrBlock< casacore::RecordDesc * >::storage().

template<typename T>
const T* casacore::Block< T >::storage ( ) const
inline

Definition at line 606 of file Block.h.

template<typename T>
void casacore::Block< T >::traceAlloc ( const void *  addr,
size_t  sz 
) const
inline
template<typename T>
void casacore::Block< T >::traceFree ( const void *  addr,
size_t  sz 
) const
inline

Friends And Related Function Documentation

template<typename T>
friend class Array< T >
friend

Definition at line 670 of file Block.h.

Member Data Documentation

template<typename T>
Allocator_private::BulkAllocator<T>* casacore::Block< T >::allocator_p
private
template<typename T>
T* casacore::Block< T >::array
private
template<typename T>
size_t casacore::Block< T >::capacity_p
private

The capacity of the vector.

Definition at line 780 of file Block.h.

Referenced by casacore::Block< casacore::String >::get_capacity(), and casacore::Block< casacore::String >::set_capacity().

template<typename T>
Bool casacore::Block< T >::destroyPointer
private
template<typename T>
Bool casacore::Block< T >::keep_allocator_p
private
template<typename T>
size_t casacore::Block< T >::used_p
private

The number of used elements in the vector.

Definition at line 782 of file Block.h.

Referenced by casacore::Block< casacore::String >::get_size(), and casacore::Block< casacore::String >::set_size().


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