pl-nk v0.4.5
Plonk|Plink|Plank are a set of cross-platform C/C++ frameworks for audio software development
Public Member Functions | Static Public Member Functions
ObjectArray< ObjectType > Class Template Reference

This is the base class for arrays. More...

Inherits SmartPointerContainer< SmartPointerType, enableWeak >.

List of all members.

Public Member Functions

 ObjectArray () throw ()
 Creates an empty array.
 ObjectArray (const int size, const bool needsNullTermination) throw ()
 Creates an array with a particular size/length.
 ObjectArray (const int size, ObjectType *dataToUse, const bool needsNullTermination=false, const bool shouldTakeOwnership=false) throw ()
 Wraps an existing array in an ObjectArray.
 ObjectArray (ObjectArray const &copy) throw ()
 Copy constructor.
ObjectArrayoperator= (ObjectArray const &other) throw ()
 Assignment operator.
template<class CopyType >
 ObjectArray (ObjectArray< CopyType > const &copy) throw ()
 Create a copy of another array.
ObjectArray< ObjectType > copy () const throw ()
 Creates a deep copy of the array.
 ObjectArray (ObjectType const &single) throw ()
 Create an array with a single item.
 ObjectArray (ObjectArray< ObjectType > const &array0, ObjectArray< ObjectType > const &array1) throw ()
 Concatenate two arrays into one.
bool setSize (const int newSize, const bool keepContents) throw ()
 Sets a new size for the array.
void clear () throw ()
 Sets the length of the array to zero.
int size () const throw ()
 Size is the actual number of elements of storage needed for the array.
int sizeAllocated () const throw ()
 This is the memory allocated to the array.
int length () const throw ()
 Length is the number of real elements of storage available.
int memorySize () const throw ()
 Actual memory requirements of the array elements and the null terminator (if needed).
ObjectType * getArray () throw ()
 Returns a pointer to the raw array.
const ObjectType * getArray () const throw ()
 Returns a pointer to the raw array for read-only ops.
 operator const ObjectType * () const throw ()
 Returns a pointer to the raw array for read-only ops.
 operator ObjectType * () throw ()
 Returns a pointer to the raw array.
bool isNullTerminated () const throw ()
 Returns whether this is a null terminated array or not.
void setNullTerminated (const bool state) throw ()
 Changes this array's null terminator flag.
void referTo (const int size, ObjectType *dataToUse, const bool needsNullTermination=false)
 Force the internal array to refer to other data.
ObjectArray< ObjectType > & add (ObjectType const &item) throw ()
 Adds an item in-place.
ObjectArray< ObjectType > & add (ObjectArray< ObjectType > const &other) throw ()
 Adds several items in-place.
ObjectArray< ObjectType > & remove (const int index) throw ()
 Removes an item at the given index in-place.
ObjectArray< ObjectType > & put (const int index, ObjectType const &item) throw ()
 Places an item at the given index.
ObjectType & operator[] (const int index) throw ()
 Returns a reference to an item at the specified index.
const ObjectType & operator[] (const int index) const throw ()
 Returns a reference to an item at the specified index.
ObjectType & at (const int index) throw ()
 Returns a reference to an item at the specified index.
const ObjectType & at (const int index) const throw ()
 Returns a reference to an item at the specified index.
ObjectArray< ObjectType > at (ObjectArray< int > const &indices) const throw ()
 Returns a new array by iterating through an array of indices provided.
ObjectArray< ObjectType > atUnchecked (ObjectArray< int > const &indices) const throw ()
 Returns a new array by iterating through an array of indices provided.
ObjectType & atUnchecked (const int index) throw ()
 Returns a reference to an itemn at the specified index.
const ObjectType & atUnchecked (const int index) const throw ()
 Returns a refernce to an itemn at the specified index.
ObjectType & wrapAt (const int index) throw ()
 Returns a reference to an item at the specified index.
const ObjectType & wrapAt (const int index) const throw ()
 Returns a reference to an item at the specified index.
ObjectType & first () throw ()
 Returns the first item in the array.
const ObjectType & first () const throw ()
 Returns the first item in the array.
ObjectType & last () throw ()
 Returns the last item in the array.
const ObjectType & last () const throw ()
 Returns the last item in the array.
ObjectType & choose () throw ()
 Returns an item from the array chosen at random.
const ObjectType & choose () const throw ()
 Returns an item from the array chosen at random.
template<class WeightType >
ObjectType & wchoose (ObjectArray< WeightType > const &weights) throw ()
 Returns an item from the array using a weighted random choice.
template<class WeightType >
const ObjectType & wchoose (ObjectArray< WeightType > const &weights) const throw ()
 Returns an item from the array using a weighted random choice.
bool areAllEqual () const throw ()
 Determine if each item in the array is equal to the others.
bool operator== (ObjectArray< ObjectType > const &other) const throw ()
 Compares whether the contents of two arrays are the same.
bool operator== (const ObjectType *otherArray) const throw ()
 Compares whether the contents of two arrays are the same.
bool operator!= (ObjectArray< ObjectType > const &other) const throw ()
 Compares whether the contents of two arrays are the different.
bool operator!= (const ObjectType *otherArray) const throw ()
 Compares whether the contents of two arrays are the different.
bool contains (ObjectType const &itemToSearchFor) const throw ()
 Returns whether the array contains a particular item.
bool contains (ObjectArray< ObjectType > const &itemsToSearchFor) const throw ()
 Returns whether the array contains one or more other items.
int indexOf (ObjectType const &itemToSearchFor, const int startIndex=0) const throw ()
 Gets the index of a particular item.
int indexOf (ObjectArray< ObjectType > const &itemsToSearchFor, const int startIndex=0) const throw ()
 Search for a particular sub sequence withing the array.
int indexOfAny (ObjectArray< ObjectType > const &itemsToSearchFor, const int startIndex=0) const throw ()
 Search for any items in a given array.
ObjectArray< ObjectType > from (const int startIndex) const throw ()
 Return a new array which is a subarray of this one.
ObjectArray< ObjectType > range (const int startIndex) const throw ()
 Return a new array which is a subarray of this one.
ObjectArray< ObjectType > to (const int endIndex) const throw ()
 Return a new array which is a subarray of this one.
ObjectArray< ObjectType > range (const int startIndex, const int endIndex) const throw ()
 Return a new array which is a subarray of this one.
ObjectArray< ObjectType > replace (ObjectArray< ObjectType > const &find, ObjectArray< ObjectType > const &substitute) const throw ()
 Perform a find and replace on the array and return the result.
ObjectArray< ObjectType > & removeItem (const ObjectType item) throw ()
 Remove an item in-place.
ObjectArray< ObjectType > & removeItems (ObjectArray< ObjectType > const &items) throw ()
 Remove several items in-place.
ObjectArray2DType group (const int groupSize) const throw ()
 Group this array into a 2D array with a particular group size.
ObjectArray2DType split (ObjectArray< ObjectType > delimiters) const throw ()
 Split the array into a 2D array using delimiters.
ObjectArray2DType splitSequence (ObjectArray< ObjectType > delimitingSequence) const throw ()
 Split the array into a 2D array using a delimiting sequence.
ObjectArray2DType deinterleave (const int numGroups) const throw ()
 De-interleave an array into a 2D array.

Static Public Member Functions

static ObjectArray fromWeak (Weak const &weak) throw ()
 Get a weakly linked copy of this object.
static ObjectArray< ObjectType > withSize (const int size) throw ()
 Returns an array with a given size.
static ObjectArray< ObjectType > emptyWithAllocatedSize (const int size) throw ()
 Returns an empty array with a given size of allocated storage.
template<class CollectionType >
static ObjectArray< ObjectType > collect (ObjectArray< CollectionType > const &collection) throw ()
 Collect a new array based on the contents of another array.

Detailed Description

template<class ObjectType>
class ObjectArray< ObjectType >

This is the base class for arrays.

You can pass ObjectArray instances around relatively efficiently since copies simply refer to the same (reference counted) internal data.

This is particulary useful for storing arrays of other reference counted objects It should work on all types. For numerical types it may be more convenient to use NumericalArray (which is a subclass of ObjectArray) since it includes numerical operations on the arrays. Use Text for text strings.


Constructor & Destructor Documentation

template<class ObjectType>
ObjectArray< ObjectType >::ObjectArray ( ) throw () [inline]

Creates an empty array.

template<class ObjectType>
ObjectArray< ObjectType >::ObjectArray ( const int  size,
const bool  needsNullTermination 
) throw () [inline]

Creates an array with a particular size/length.

Parameters:
sizeThe total number of elements in the array.
needsNullTerminationIf true the last element will be used as a null terminator (e.g., for C strings but can be used for other purposes.
template<class ObjectType>
ObjectArray< ObjectType >::ObjectArray ( const int  size,
ObjectType *  dataToUse,
const bool  needsNullTermination = false,
const bool  shouldTakeOwnership = false 
) throw () [inline]

Wraps an existing array in an ObjectArray.

Warning:
This does NOT copy the data so take care that the array passed in does not get deallocated before the ObjectArray that uses it.
template<class ObjectType>
ObjectArray< ObjectType >::ObjectArray ( ObjectArray< ObjectType > const &  copy) throw () [inline]

Copy constructor.

Note that a deep copy is not made, the copy will refer to exactly the same data.

template<class ObjectType>
template<class CopyType >
ObjectArray< ObjectType >::ObjectArray ( ObjectArray< CopyType > const &  copy) throw () [inline]

Create a copy of another array.

You need to be sure that the other array type can be casted to the type of this array.

template<class ObjectType>
ObjectArray< ObjectType >::ObjectArray ( ObjectType const &  single) throw () [inline]

Create an array with a single item.

template<class ObjectType>
ObjectArray< ObjectType >::ObjectArray ( ObjectArray< ObjectType > const &  array0,
ObjectArray< ObjectType > const &  array1 
) throw () [inline]

Concatenate two arrays into one.


Member Function Documentation

template<class ObjectType>
ObjectArray<ObjectType>& ObjectArray< ObjectType >::add ( ObjectType const &  item) throw () [inline]

Adds an item in-place.

template<class ObjectType>
ObjectArray<ObjectType>& ObjectArray< ObjectType >::add ( ObjectArray< ObjectType > const &  other) throw () [inline]

Adds several items in-place.

template<class ObjectType>
bool ObjectArray< ObjectType >::areAllEqual ( ) const throw () [inline]

Determine if each item in the array is equal to the others.

If the array is empty it will return true.

template<class ObjectType>
ObjectType& ObjectArray< ObjectType >::at ( const int  index) throw () [inline]

Returns a reference to an item at the specified index.

If you are not sure about the index being in range check for the object being "null" as a separate internal null value may have been returned instead.

template<class ObjectType>
const ObjectType& ObjectArray< ObjectType >::at ( const int  index) const throw () [inline]

Returns a reference to an item at the specified index.

If you are not sure about the index being in range check for the object being "null" as a separate internal null value may have been returned instead.

template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::at ( ObjectArray< int > const &  indices) const throw () [inline]

Returns a new array by iterating through an array of indices provided.

template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::atUnchecked ( ObjectArray< int > const &  indices) const throw () [inline]

Returns a new array by iterating through an array of indices provided.

template<class ObjectType>
ObjectType& ObjectArray< ObjectType >::atUnchecked ( const int  index) throw () [inline]

Returns a reference to an itemn at the specified index.

You must make sure that the array index is in range when using this version.

template<class ObjectType>
const ObjectType& ObjectArray< ObjectType >::atUnchecked ( const int  index) const throw () [inline]

Returns a refernce to an itemn at the specified index.

You must make sure that the array index is in range when using this version.

template<class ObjectType>
ObjectType& ObjectArray< ObjectType >::choose ( ) throw () [inline]

Returns an item from the array chosen at random.

The weighting for the random choice should be roughtly equally distributed. If the array is empty it returns a "null" ersion of the object.

template<class ObjectType>
const ObjectType& ObjectArray< ObjectType >::choose ( ) const throw () [inline]

Returns an item from the array chosen at random.

The weighting for the random choice should be roughtly equally distributed. If the array is empty it returns a "null" ersion of the object.

template<class ObjectType>
void ObjectArray< ObjectType >::clear ( ) throw () [inline]

Sets the length of the array to zero.

template<class ObjectType>
template<class CollectionType >
static ObjectArray<ObjectType> ObjectArray< ObjectType >::collect ( ObjectArray< CollectionType > const &  collection) throw () [inline, static]

Collect a new array based on the contents of another array.

Each element in turn is passed to the new object's constructor.

template<class ObjectType>
bool ObjectArray< ObjectType >::contains ( ObjectType const &  itemToSearchFor) const throw () [inline]

Returns whether the array contains a particular item.

template<class ObjectType>
bool ObjectArray< ObjectType >::contains ( ObjectArray< ObjectType > const &  itemsToSearchFor) const throw () [inline]

Returns whether the array contains one or more other items.

Parameters:
itemsToSearchForThe array of other items.
template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::copy ( ) const throw () [inline]

Creates a deep copy of the array.

Note that items themselves are not deep-copied so reference counted objects will still refer to the same objects.

template<class ObjectType>
ObjectArray2DType ObjectArray< ObjectType >::deinterleave ( const int  numGroups) const throw () [inline]

De-interleave an array into a 2D array.

The 2D array will contain numGroups sub-arrays. Items in the source array are added to the sub-arrays in turn until all items are added.

Example:

     IntArray source1d (1, 2, 3, 4, 5, 6, 7);
     IntArray2D dest2d = source1d.deinterleave (2);
      // result will be {{1, 3, 5, 7}, {2, 4, 6}}
template<class ObjectType>
static ObjectArray<ObjectType> ObjectArray< ObjectType >::emptyWithAllocatedSize ( const int  size) throw () [inline, static]

Returns an empty array with a given size of allocated storage.

This will make expanding this array's size upto this allocated size more efficient than bulding it up from a zero-size array. The array will NOT be a null terminated type.

template<class ObjectType>
ObjectType& ObjectArray< ObjectType >::first ( ) throw () [inline]

Returns the first item in the array.

If the array is empty it returns a "null" ersion of the object.

template<class ObjectType>
const ObjectType& ObjectArray< ObjectType >::first ( ) const throw () [inline]

Returns the first item in the array.

If the array is empty it returns a "null" ersion of the object.

template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::from ( const int  startIndex) const throw () [inline]

Return a new array which is a subarray of this one.

Returns:
An array from startIndex to the end of the array.
template<class ObjectType>
static ObjectArray ObjectArray< ObjectType >::fromWeak ( Weak const &  weak) throw () [inline, static]

Get a weakly linked copy of this object.

This will return a blank/empty/null object of this type if the original has already been deleted.

Reimplemented in Text, UnitBase< SampleType >, and UnitBase< float >.

template<class ObjectType>
const ObjectType* ObjectArray< ObjectType >::getArray ( ) const throw () [inline]

Returns a pointer to the raw array for read-only ops.

template<class ObjectType>
ObjectType* ObjectArray< ObjectType >::getArray ( ) throw () [inline]

Returns a pointer to the raw array.

template<class ObjectType>
ObjectArray2DType ObjectArray< ObjectType >::group ( const int  groupSize) const throw () [inline]

Group this array into a 2D array with a particular group size.

Reimplemented in UnitBase< SampleType >, and UnitBase< float >.

template<class ObjectType>
int ObjectArray< ObjectType >::indexOf ( ObjectType const &  itemToSearchFor,
const int  startIndex = 0 
) const throw () [inline]
template<class ObjectType>
int ObjectArray< ObjectType >::indexOf ( ObjectArray< ObjectType > const &  itemsToSearchFor,
const int  startIndex = 0 
) const throw () [inline]

Search for a particular sub sequence withing the array.

template<class ObjectType>
int ObjectArray< ObjectType >::indexOfAny ( ObjectArray< ObjectType > const &  itemsToSearchFor,
const int  startIndex = 0 
) const throw () [inline]

Search for any items in a given array.

template<class ObjectType>
bool ObjectArray< ObjectType >::isNullTerminated ( ) const throw () [inline]

Returns whether this is a null terminated array or not.

template<class ObjectType>
ObjectType& ObjectArray< ObjectType >::last ( ) throw () [inline]

Returns the last item in the array.

If the array is empty it returns a "null" ersion of the object.

template<class ObjectType>
const ObjectType& ObjectArray< ObjectType >::last ( ) const throw () [inline]

Returns the last item in the array.

If the array is empty it returns a "null" ersion of the object.

template<class ObjectType>
int ObjectArray< ObjectType >::length ( ) const throw () [inline]

Length is the number of real elements of storage available.

For arrays that are NOT null terminated this is synonymous with size(). If this is a null terminated array the length is one less than the size.

template<class ObjectType>
int ObjectArray< ObjectType >::memorySize ( ) const throw () [inline]

Actual memory requirements of the array elements and the null terminator (if needed).

Equivalent to size() * sizeof(ObjectType).

template<class ObjectType>
ObjectArray< ObjectType >::operator const ObjectType * ( ) const throw () [inline]

Returns a pointer to the raw array for read-only ops.

template<class ObjectType>
ObjectArray< ObjectType >::operator ObjectType * ( ) throw () [inline]

Returns a pointer to the raw array.

template<class ObjectType>
bool ObjectArray< ObjectType >::operator!= ( const ObjectType *  otherArray) const throw () [inline]

Compares whether the contents of two arrays are the different.

template<class ObjectType>
bool ObjectArray< ObjectType >::operator!= ( ObjectArray< ObjectType > const &  other) const throw () [inline]

Compares whether the contents of two arrays are the different.

template<class ObjectType>
ObjectArray& ObjectArray< ObjectType >::operator= ( ObjectArray< ObjectType > const &  other) throw () [inline]

Assignment operator.

template<class ObjectType>
bool ObjectArray< ObjectType >::operator== ( const ObjectType *  otherArray) const throw () [inline]

Compares whether the contents of two arrays are the same.

template<class ObjectType>
bool ObjectArray< ObjectType >::operator== ( ObjectArray< ObjectType > const &  other) const throw () [inline]

Compares whether the contents of two arrays are the same.

template<class ObjectType>
const ObjectType& ObjectArray< ObjectType >::operator[] ( const int  index) const throw () [inline]

Returns a reference to an item at the specified index.

If you are not sure about the index being in range check for the object being "null" as a separate internal null value may have been returned instead.

Reimplemented in UnitBase< SampleType >, and UnitBase< float >.

template<class ObjectType>
ObjectType& ObjectArray< ObjectType >::operator[] ( const int  index) throw () [inline]

Returns a reference to an item at the specified index.

If you are not sure about the index being in range check for the object being "null" as a separate internal null value may have been returned instead.

Reimplemented in UnitBase< SampleType >, and UnitBase< float >.

template<class ObjectType>
ObjectArray<ObjectType>& ObjectArray< ObjectType >::put ( const int  index,
ObjectType const &  item 
) throw () [inline]

Places an item at the given index.

Indices out of range will be ignored.

template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::range ( const int  startIndex) const throw () [inline]

Return a new array which is a subarray of this one.

Returns:
An array from startIndex (inclusive) to the end of the array.
template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::range ( const int  startIndex,
const int  endIndex 
) const throw () [inline]

Return a new array which is a subarray of this one.

Returns:
An array from startIndex (inclusive) to endIndex (exclusive).
template<class ObjectType>
void ObjectArray< ObjectType >::referTo ( const int  size,
ObjectType *  dataToUse,
const bool  needsNullTermination = false 
) [inline]

Force the internal array to refer to other data.

This will deallocate internally allocated memory and use the data provided. Take care to ensure that the data to which this array refers exists until this ObjectArray has been deleted and that the size argument is correct.

template<class ObjectType>
ObjectArray<ObjectType>& ObjectArray< ObjectType >::remove ( const int  index) throw () [inline]

Removes an item at the given index in-place.

Indices out of range will be ignored.

template<class ObjectType>
ObjectArray<ObjectType>& ObjectArray< ObjectType >::removeItem ( const ObjectType  item) throw () [inline]

Remove an item in-place.

template<class ObjectType>
ObjectArray<ObjectType>& ObjectArray< ObjectType >::removeItems ( ObjectArray< ObjectType > const &  items) throw () [inline]

Remove several items in-place.

template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::replace ( ObjectArray< ObjectType > const &  find,
ObjectArray< ObjectType > const &  substitute 
) const throw () [inline]

Perform a find and replace on the array and return the result.

All occurrences of find are replaced with substitute.

template<class ObjectType>
void ObjectArray< ObjectType >::setNullTerminated ( const bool  state) throw () [inline]

Changes this array's null terminator flag.

template<class ObjectType>
bool ObjectArray< ObjectType >::setSize ( const int  newSize,
const bool  keepContents 
) throw () [inline]

Sets a new size for the array.

If the contents are retained the overalapping size is copied and/or any additionally allocated space is cleared. Otherwise the data is left unitialised.

Returns:
True the buffer was resized.
template<class ObjectType>
int ObjectArray< ObjectType >::size ( ) const throw () [inline]

Size is the actual number of elements of storage needed for the array.

If this is a null terminated array the null value is inlcuded in the size.

template<class ObjectType>
int ObjectArray< ObjectType >::sizeAllocated ( ) const throw () [inline]

This is the memory allocated to the array.

It includes memory reserved for future expansion.

template<class ObjectType>
ObjectArray2DType ObjectArray< ObjectType >::split ( ObjectArray< ObjectType >  delimiters) const throw () [inline]

Split the array into a 2D array using delimiters.

The array will the split when ANY of the delimiters is found.

template<class ObjectType>
ObjectArray2DType ObjectArray< ObjectType >::splitSequence ( ObjectArray< ObjectType >  delimitingSequence) const throw () [inline]

Split the array into a 2D array using a delimiting sequence.

The array will the split when ALL of the delimiters are found in the same sequence.

template<class ObjectType>
ObjectArray<ObjectType> ObjectArray< ObjectType >::to ( const int  endIndex) const throw () [inline]

Return a new array which is a subarray of this one.

Returns:
An array from startIndex (inclusive) to the end of the array.
template<class ObjectType>
template<class WeightType >
const ObjectType& ObjectArray< ObjectType >::wchoose ( ObjectArray< WeightType > const &  weights) const throw () [inline]

Returns an item from the array using a weighted random choice.

This chooses an item in the array at random using another array as weights. For example, if an array has 4 items and the weight array is IntArray(40, 30, 20, 10) The item at index 0 has a 40% chance, index 1 a 30% chance and so on. The scale of the weights is arbitrary (i.e., they do not need to sum to any particular value, 100 was chosen in the example above to make explanation easier).

Parameters:
weightsThe weights array which can be any numerical type of array. If the array is empty it returns a "null" ersion of the object.
template<class ObjectType>
template<class WeightType >
ObjectType& ObjectArray< ObjectType >::wchoose ( ObjectArray< WeightType > const &  weights) throw () [inline]

Returns an item from the array using a weighted random choice.

This chooses an item in the array at random using another array as weights. For example, if an array has 4 items and the weight array is IntArray(40, 30, 20, 10) The item at index 0 has a 40% chance, index 1 a 30% chance and so on. The scale of the weights is arbitrary (i.e., they do not need to sum to any particular value, 100 was chosen in the example above to make explanation easier).

Parameters:
weightsThe weights array which can be any numerical type of array. If the array is empty it returns a "null" ersion of the object.
template<class ObjectType>
static ObjectArray<ObjectType> ObjectArray< ObjectType >::withSize ( const int  size) throw () [inline, static]

Returns an array with a given size.

The array will NOT be a null terminated type.

template<class ObjectType>
const ObjectType& ObjectArray< ObjectType >::wrapAt ( const int  index) const throw () [inline]

Returns a reference to an item at the specified index.

If the index is out of range it will be wrapped in-range. For example, if the array size is 10 and the index requested is 12, wrapAt() will return the item at index 2, if the index is -1 the item returned will be at index 9 and so on.

template<class ObjectType>
ObjectType& ObjectArray< ObjectType >::wrapAt ( const int  index) throw () [inline]

Returns a reference to an item at the specified index.

If the index is out of range it will be wrapped in-range. For example, if the array size is 10 and the index requested is 12, wrapAt() will return the item at index 2, if the index is -1 the item returned will be at index 9 and so on.


The documentation for this class was generated from the following file:
 All Classes Functions Typedefs Enumerations Enumerator Properties