casacore::Block< T > Class Template Reference

simple 1-D array More...

#include <Block.h>

Inheritance diagram for casacore::Block< T >:

Public Member Functions
	Block ()
	Create a zero-length Block.
template<typename Allocator >
	Block (AllocSpec< Allocator > const &)
	Create a zero-length Block.
	Block (size_t n)
	Create a Block with the given number of points.
template<typename Allocator >
	Block (size_t n, AllocSpec< Allocator > const &)
	Create a Block with the given number of points.
	Block (size_t n, ArrayInitPolicy initPolicy)
	Create a Block with the given number of points.
template<typename Allocator >
	Block (size_t n, ArrayInitPolicy initPolicy, AllocSpec< Allocator > const &)
	Create a Block with the given number of points.
	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.
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.
	Block (size_t n, T *&storagePointer, Bool takeOverStorage=True)
	Create a `Block` from a C-array (i.e.
template<typename Allocator >
	Block (size_t n, T *&storagePointer, Bool takeOverStorage, AllocSpec< Allocator > const &)
	Create a `Block` from a C-array (i.e.
	Block (const Block< T > &other)
	Copy the other block into this one.
Block< T > &	operator= (const Block< T > &other)
	Assign other to this.
	~Block ()
	Frees up the storage pointed contained in the Block.
void	resize (size_t n, Bool forceSmaller=False, Bool copyElements=True)
	Resizes the Block.
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.
void	remove (size_t whichOne, Bool forceSmaller, ArrayInitPolicy initPolicy)
void	prohibitChangingAllocator ()
	Prohibit changing allocator for this instance.
void	permitChangingAllocator ()
	Permit changing allocator for this instance.
void	replaceStorage (size_t n, T *&storagePointer, Bool takeOverStorage=True)
	Replace the internal storage with a C-array (i.e.
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).
const T &	operator[] (size_t index) const
Block< T > &	operator= (const T &val)
	Set all values in the block to "val".
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.
const T *	storage () const
size_t	nelements () const
	The number of elements contained in this `Block<T>`.
size_t	size () const
size_t	capacity () const
	The capacity in this `Block<T>`.
Bool	empty () const
	Is the block empty (i.e.

typedef T	value_type
	Define the STL-style iterators.
typedef T *	iterator
typedef const T *	const_iterator
typedef value_type *	pointer
typedef const value_type *	const_pointer
typedef value_type &	reference
typedef const value_type &	const_reference
typedef size_t	size_type
typedef ptrdiff_t	difference_type
class	Array< T >
Allocator_private::BulkAllocator < T > *	allocator_p
	The allocator.
size_t	capacity_p
	The capacity of the vector.
size_t	used_p
	The number of used elements in the vector.
T *	array
	The actual storage.
Bool	destroyPointer
	Can we delete the storage upon destruction?
Bool	keep_allocator_p
	Can we change allocator or not?
iterator	begin ()
	Get the begin and end iterator object for this block.
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
void	deinit ()
void	dealloc ()
template<typename Allocator >
Bool	isCompatibleAllocator ()
size_t	get_size () const
	The number of used elements in the vector.
void	set_size (size_t new_value)
	Set the number of used elements in the vector.
size_t	get_capacity () const
	The capacity of the vector.
void	set_capacity (size_t new_value)
	Set the capacity of the vector.
static bool	init_anyway ()
template<typename Allocator >
static Allocator_private::BulkAllocator < typename Allocator::value_type > *	get_allocator ()

Detailed Description

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

simple 1-D array

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 246 of file Block.h.

Member Typedef Documentation

template<class T>

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

Definition at line 682 of file Block.h.

template<class T>

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

Definition at line 684 of file Block.h.

template<class T>

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

Definition at line 686 of file Block.h.

template<class T>

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

Definition at line 688 of file Block.h.

template<class T>

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

Definition at line 681 of file Block.h.

template<class T>

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

Definition at line 683 of file Block.h.

template<class T>

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

Definition at line 685 of file Block.h.

template<class T>

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

Definition at line 687 of file Block.h.

template<class 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 680 of file Block.h.

Constructor & Destructor Documentation

template<class 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 252 of file Block.h.

template<class T>

template<typename Allocator >

casacore::Block< T >::Block ( AllocSpec< Allocator > const & ) [inline, explicit]

Create a zero-length Block.

Note that any index into this Block is an error.

Definition at line 259 of file Block.h.

template<class T>

casacore::Block< T >::Block ( size_t n ) [inline, explicit]

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 267 of file Block.h.

template<class 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 276 of file Block.h.

template<class 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 285 of file Block.h.

template<class 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 294 of file Block.h.

template<class 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 304 of file Block.h.

template<class 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 319 of file Block.h.

template<class 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 341 of file Block.h.

template<class 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 354 of file Block.h.

template<class 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 364 of file Block.h.

template<class T>

casacore::Block< T >::~Block ( ) [inline]

Frees up the storage pointed contained in the Block.

Definition at line 396 of file Block.h.

template<class T>

casacore::Block< T >::Block	(	size_t	n,
		ArrayInitPolicy	initPolicy,
		Allocator_private::BulkAllocator< T > *	allocator
	)			`[inline, private]`

Definition at line 719 of file Block.h.

template<class T>

casacore::Block< T >::Block	(	size_t	n,
		Allocator_private::AllocSpec< T >	allocator
	)			`[inline, private]`

Definition at line 725 of file Block.h.

template<class T>

casacore::Block< T >::Block	(	size_t	n,
		T *&	storagePointer,
		Bool	takeOverStorage,
		Allocator_private::BulkAllocator< T > *	allocator
	)			`[inline, private]`

Definition at line 730 of file Block.h.

Member Function Documentation

template<class T>

const_iterator casacore::Block< T >::begin ( ) const [inline]

Definition at line 694 of file Block.h.

template<class T>

iterator casacore::Block< T >::begin ( ) [inline]

Get the begin and end iterator object for this block.

Definition at line 692 of file Block.h.

template<class T>

size_t casacore::Block< T >::capacity ( ) const [inline]

The capacity in this Block<T>.

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

Definition at line 664 of file Block.h.

template<class T>

void casacore::Block< T >::construct	(	size_t	pos,
		size_type	n
	)			`[inline, private]`

Definition at line 745 of file Block.h.

template<class T>

void casacore::Block< T >::construct	(	size_t	pos,
		size_t	n,
		T const &	initial_value
	)			`[inline, private]`

Definition at line 741 of file Block.h.

template<class T>

void casacore::Block< T >::construct	(	size_t	pos,
		size_t	n,
		T const *	src
	)			`[inline, private]`

Definition at line 738 of file Block.h.

template<class T>

void casacore::Block< T >::dealloc ( ) [inline, private]

Definition at line 786 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::Block(), casacore::Block< RecordFieldPtr< uChar > >::deinit(), and casacore::Block< RecordFieldPtr< uChar > >::init().

template<class T>

void casacore::Block< T >::deinit ( ) [inline, private]

Definition at line 780 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::resize(), and casacore::Block< RecordFieldPtr< uChar > >::~Block().

template<class T>

void casacore::Block< T >::destroy	(	size_t	pos,
		size_type	n
	)			`[inline, private]`

Definition at line 748 of file Block.h.

template<class T>

Bool casacore::Block< T >::empty ( ) const [inline]

Is the block empty (i.e.

no elements)?

Definition at line 667 of file Block.h.

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

template<class T>

const_iterator casacore::Block< T >::end ( ) const [inline]

Definition at line 698 of file Block.h.

template<class T>

iterator casacore::Block< T >::end ( ) [inline]

Definition at line 696 of file Block.h.

template<class T>

template<typename Allocator >

static Allocator_private::BulkAllocator< typename Allocator::value_type>* casacore::Block< T >::get_allocator ( ) [inline, static, private]

Definition at line 796 of file Block.h.

template<class T>

Allocator_private::BulkAllocator<T>* casacore::Block< T >::get_allocator ( ) [inline, private]

Definition at line 751 of file Block.h.

template<class T>

size_t casacore::Block< T >::get_capacity ( ) const [inline, private]

The capacity of the vector.

Definition at line 817 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::capacity(), casacore::Block< RecordFieldPtr< uChar > >::dealloc(), casacore::Block< RecordFieldPtr< uChar > >::init(), casacore::Block< RecordFieldPtr< uChar > >::remove(), casacore::Block< RecordFieldPtr< uChar > >::replaceStorage(), casacore::Block< RecordFieldPtr< uChar > >::resize(), casacore::Block< RecordFieldPtr< uChar > >::set_size(), and casacore::Block< RecordFieldPtr< uChar > >::size().

template<class T>

size_t casacore::Block< T >::get_size ( ) const [inline, private]

The number of used elements in the vector.

Definition at line 810 of file Block.h.

template<class T>

void casacore::Block< T >::init ( ArrayInitPolicy initPolicy ) [inline, private]

end of friend

Definition at line 762 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::Block().

template<class T>

static bool casacore::Block< T >::init_anyway ( ) [inline, static, private]

Definition at line 755 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::Block(), casacore::Block< RecordFieldPtr< uChar > >::remove(), and casacore::Block< RecordFieldPtr< uChar > >::resize().

template<class T>

template<typename Allocator >

Bool casacore::Block< T >::isCompatibleAllocator ( ) [inline, private]

Definition at line 802 of file Block.h.

template<class T>

size_t casacore::Block< T >::nelements ( ) const [inline]

The number of elements contained in this Block<T>.

Definition at line 658 of file Block.h.

Referenced by casacore::CompoundParam< AutoDiff< Double > >::CompoundParam(), casacore::genSort(), casacore::MeasConvert< MEpoch >::isNOP(), casacore::PtrBlock< SSMIndex * >::nelements(), casacore::MeasureHolder::nelements(), casacore::SimpleOrderedMap< String, RefColumn * >::ntot(), casacore::BlockIO_global_functions_BlockIO::putBlock(), and casacore::BlockIO_global_functions_BlockIO::showBlock().

template<class T>

Block<T>& casacore::Block< T >::operator= ( const T & val ) [inline]

Set all values in the block to "val".

Definition at line 632 of file Block.h.

template<class 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 381 of file Block.h.

template<class T>

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

Definition at line 619 of file Block.h.

template<class 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

indexError

Definition at line 608 of file Block.h.

template<class T>

void casacore::Block< T >::permitChangingAllocator ( ) [inline]

Permit changing allocator for this instance.

Definition at line 558 of file Block.h.

template<class T>

void casacore::Block< T >::prohibitChangingAllocator ( ) [inline]

Prohibit changing allocator for this instance.

Definition at line 554 of file Block.h.

template<class T>

void casacore::Block< T >::remove	(	size_t	whichOne,
		Bool	forceSmaller,
		ArrayInitPolicy	initPolicy
	)			`[inline]`

Definition at line 495 of file Block.h.

template<class 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 491 of file Block.h.

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

template<class T>

template<typename Allocator >

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

Definition at line 580 of file Block.h.

template<class 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 576 of file Block.h.

Referenced by casacore::PtrBlock< SSMIndex * >::replaceStorage(), and casacore::Block< RecordFieldPtr< uChar > >::replaceStorage().

template<class T>

void casacore::Block< T >::resize	(	size_t	n,
		Bool	forceSmaller,
		Bool	copyElements,
		ArrayInitPolicy	initPolicy
	)			`[inline]`

Definition at line 428 of file Block.h.

template<class 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 424 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::operator=(), casacore::ConcatRows::reserve(), casacore::Block< RecordFieldPtr< uChar > >::resize(), and casacore::PtrBlock< SSMIndex * >::resize().

template<class T>

void casacore::Block< T >::set ( const T & val ) [inline]

Definition at line 634 of file Block.h.

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

template<class T>

void casacore::Block< T >::set_capacity ( size_t new_value ) [inline, private]

Set the capacity of the vector.

Definition at line 819 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::init(), casacore::Block< RecordFieldPtr< uChar > >::remove(), casacore::Block< RecordFieldPtr< uChar > >::replaceStorage(), and casacore::Block< RecordFieldPtr< uChar > >::resize().

template<class T>

void casacore::Block< T >::set_size ( size_t new_value ) [inline, private]

Set the number of used elements in the vector.

Definition at line 812 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::remove(), casacore::Block< RecordFieldPtr< uChar > >::replaceStorage(), casacore::Block< RecordFieldPtr< uChar > >::resize(), and casacore::Block< RecordFieldPtr< uChar > >::set_capacity().

template<class T>

size_t casacore::Block< T >::size ( ) const [inline]

Definition at line 659 of file Block.h.

Referenced by casacore::Block< RecordFieldPtr< uChar > >::empty(), casacore::Block< RecordFieldPtr< uChar > >::end(), casacore::Block< RecordFieldPtr< uChar > >::nelements(), casacore::Block< RecordFieldPtr< uChar > >::operator=(), and casacore::PtrBlock< SSMIndex * >::size().

template<class T>

const T* casacore::Block< T >::storage ( ) const [inline]

Definition at line 653 of file Block.h.

template<class 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 652 of file Block.h.

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

template<class T>