This reference page is linked to from the following overview topics: Containers.

Detailed Description

template<class T>
class MaxSDK::Array< T >

A generic array container, with proper support for non-POD types.

This template class is a generaic, dynamic array container, similar to the STL class "vector". Whereas the classical 3ds Max SDK class Tab supports only POD types, this class supports non-POD types as well.

Note:: POD stands for "plain old data", and basically denotes any data type which does not need to be constructed, destructed, and which can be copied with memcpy() rather than requiring a copy operator to be called.

#include <Array.h>

Inheritance diagram for Array< T >:

[legend]

List of all members.

Public Types
typedef const void *	elem2
Public Member Functions
typedef	int (__cdecl CompareFnc)(const void elem1
	Type of function to pass to sort().
	Array ()
	Initializes an empty array.
	Array (size_t initUsedLength, const T &defaultVal=T(), size_t initGrowLength=kDefaultGrowthLength)
	Initializes an array with an initial size.
	Array (const Array< T > &src)
	Copy constructor.
	~Array ()
	Destructor. Destroys every element stored in the array, and frees the allocated storage.
Array< T > &	operator= (const Array< T > &src)
	Copy operator.
bool	operator== (const Array< T > &op) const
	Equality operator.
Array< T > &	setAt (size_t index, const T &value)
	Sets a copy of value at the given index.
Array< T > &	setAll (const T &value)
	Sets all the elements of the array to the given value.
size_t	append (const T &value)
	Appends a copy of value to the array.
Array< T > &	append (const T *values, size_t count)
	Appends one or more element(s) to the array.
Array< T > &	append (const Array< T > &array)
	Appends the contents of another array to this array.
Array< T > &	insertAt (size_t index, const T &value)
	Inserts a single value, at a given location, into this array.
Array< T > &	insertAt (size_t index, const T *values, size_t count)
	Inserts a one or more value(s), at a given location, into this array.
Array< T > &	removeAt (size_t index)
	Removes a single element from the array.
bool	remove (const T &value, size_t start=0)
	Searches for a value in the array and, if it is found, removes it from the array.
Array< T > &	removeFirst ()
	Removes the first element of the array.
Array< T > &	removeLast ()
	Removes the last element of the array.
Array< T > &	removeAll ()
	Removes all the elements from the array.
Array< T > &	removeSubArray (size_t startIndex, size_t endIndex)
	Removes a subset of the array.
bool	contains (const T &value, size_t start=0) const
	Determines if a value is stored in the array.
bool	find (const T &value, size_t &foundAt, size_t start=0) const
	Searches for a value in the array.
size_t	find (const T &value) const
	Searches for a value in the array.
size_t	findFrom (const T &value, size_t start) const
	Searches for a value in the array, starting at a given index.
size_t	length () const
	Returns the number of elements used (as opposed to simply allocated/reserved) in the array.
bool	isEmpty () const
	Returns true if the number of used elements in the array is 0; returns false otherwise.
size_t	lengthUsed () const
	Returns the number of elements used (as opposed to simply allocated/reserved) in the array.
Array< T > &	setLengthUsed (size_t length, const T &defaultVal=T())
	Sets the number of elements used (as opposed to simply allocated/reserved) in the array.
size_t	lengthReserved () const
	Returns the number of elements allocated/reserved (as opposed to actually used) in the array.
Array< T > &	setLengthReserved (size_t length)
	Sets the number of elements allocated/reserved (as opposed to actually used) in the array.
size_t	growLength () const
	Returns the growth length of the array.
Array< T > &	setGrowLength (size_t)
	Sets the growth length of the array.
Array< T > &	reverse ()
	Reverses the sequence of elements in the array.
Array< T > &	swap (size_t i1, size_t i2)
	Swaps two elements in this array.
void	sort (CompareFnc cmp)
	Sorts the elements of the array using a custom comparison function.
bool	isValidIndex (size_t) const
	Returns whether the given array index is valid for this array.

T &	operator[] (size_t i)
	Subscript operator.
const T &	operator[] (size_t i) const

const T &	at (size_t index) const
	Same as subscript operator.
T &	at (size_t index)

T &	first ()
	Accesses the first element in the array.
const T &	first () const

T &	last ()
	Accesses the last element in the array.
const T &	last () const

const T *	asArrayPtr () const
	Returns the array storage as a C-style array pointer.
T *	asArrayPtr ()
Protected Types
enum	{ kArrayGrowthThreshold = 0x10000, kDefaultGrowthLength = 8 }
Static Protected Member Functions
static size_t	quickSortPartition (T *data, size_t first, size_t last, CompareFnc cmp)
	The partition portion of the QuickSort algorithm.
static void	quickSortRecursive (T *data, size_t first, size_t last, CompareFnc cmp)
	Recursive QuickSort function used to sort the elements of the array.
static void	handleOutOfMemory ()
	Utility function, called when the array fails to allocate memory.
static T *	ArrayAllocate (size_t len)
	Allocates an array of elements without constructing them.
static void	ArrayConstruct (T *arrayBegin, size_t len, const T &defaultVal)
	Constructs an array of elements.
static void	ArrayDeAllocate (T *arrayBegin)
	De-allocates an array of elements without destructing them.
static void	ArrayDestruct (T *arrayBegin, size_t len)
	Destructs an array of elements.
static void	ArrayCopy (T pCopy, const T pSource, size_t nCount)
	Copies an array of elements to an already-constructed buffer.
static void	ArrayCopyOverlap (T pCopy, const T pSource, size_t nCount)
	Copies an array of elements when the target and destination memory buffers may overlap.
static void	ArrayCopyConstruct (T pCopy, const T pSource, size_t nCount)
	Copies and array of elements to a non-constructed.
Protected Attributes
T *	mpArray
	Pointer to the storage buffer.
size_t	mReservedLen
	The reserved length (in number of elements, not bytes).
size_t	mUsedLen
	The used length (in number of elements, not bytes).
size_t	mGrowLen
	The growth length. See setGrowLength().

Member Typedef Documentation

typedef const void* elem2

Search for all occurrences

Member Enumeration Documentation

anonymous enum [protected]

Search for all occurrences

Enumerator:

kArrayGrowthThreshold

The maximum extra space (in bytes) that may be reserved when the buffer is enlarged.

The array will usually enlarge the buffer by half its size whenever it runs out of space, unless that enlargement would exceed this value.

Search for all occurrences

kDefaultGrowthLength

The default growth length. See setGrowLength().

Search for all occurrences

         {
        kArrayGrowthThreshold = 0x10000,
        kDefaultGrowthLength = 8
    };

Constructor & Destructor Documentation

Array ( )

Initializes an empty array.

Array	(	size_t	initUsedLength,
		const T &	defaultVal = `T()`,
		size_t	initGrowLength = `kDefaultGrowthLength`
	)

Initializes an array with an initial size.

Parameters:

[in]	initUsedLength	- Number of elements initially allocated in the array.
[in]	defaultVal	- The default value for the elements initially allocated.
[in]	initGrowLength	- The initial growth length of the array. For more information on the growth length, see setGrowLength().

                 {

//==============================================================================
// class MaxSDK::Array
//

template <class T> class Array
: public MaxHeapOperators {
public:


    typedef int( __cdecl *CompareFnc) ( const void *elem1, const void *elem2 );

Array ( const Array< T > & src )

Copy constructor.

Copies the contents of another array.

Parameters:

[in] src - Array from which the elements are copied.

~Array ( )

Destructor. Destroys every element stored in the array, and frees the allocated storage.

Member Function Documentation

typedef int ( __cdecl * CompareFnc ) const

Search for all occurrences

Type of function to pass to sort().

Must return:

< 0 if elem1 is smaller than elem2,
> 0 if elem 1 is greater,
or 0 if they're equal.

Array< T > & operator= ( const Array< T > & src )

Copy operator.

Copies the contents of another array.

Parameters:

[in] src - Array from which the elements are copied.

Returns:: A reference to 'this'.

bool operator== ( const Array< T > & op ) const

Equality operator.

Parameters:

[in] op - Array to be compared to 'this'.

Returns:: true if and only if both arrays contain the same number of elements and each of these elements if equal to the corresponding element from the other Array.

T & operator[] ( size_t i ) [inline]

Subscript operator.

Parameters:

[in] i - Index of array element to access. This index must be within the array bounds.

Returns:: A reference to the array element at the specified index.

Remarks:: Does not implement bounds checking.

const T & operator[] ( size_t i ) const [inline]

const T & at ( size_t index ) const [inline]

Search for all occurrences

Same as subscript operator.

Parameters:

[in] index - Index of array element to access. This index must be within the array bounds.

Returns:: A reference to the array element at the specified index.

Remarks:: Does not implement bounds checking.

T & at ( size_t index ) [inline]

Search for all occurrences

Array< T > & setAt	(	size_t	index,
		const T &	value
	)		`[inline]`

Search for all occurrences

Sets a copy of value at the given index.

Parameters:

[in]	index	- The position in the array where a copy of value is placed. This index must be within the array bounds.
[in]	value	- a reference to the original object.

Returns:: A reference to 'this'.

Remarks:: Does not implement bounds checking.

Array< T > & setAll ( const T & value )

Search for all occurrences

Sets all the elements of the array to the given value.

Parameters:

[in] value - The value to which the elements of the array are set.

Returns:: A reference to 'this'.

T & first ( ) [inline]

Search for all occurrences

Accesses the first element in the array.

Returns:: A reference to the first element of the array.

Remarks:: It is invalid to call this on an empty array.

const T & first ( ) const [inline]

Search for all occurrences

T & last ( ) [inline]

Search for all occurrences

Accesses the last element in the array.

Returns:: A reference to the last element of the array.

Remarks:: It is invalid to call this on an empty array.

const T & last ( ) const [inline]

Search for all occurrences

size_t append ( const T & value ) [inline]

Search for all occurrences

Appends a copy of value to the array.

Parameters:

[in] value - A reference to the original value.

Returns:: The number of elements in the array prior to the append operation.

Array< T > & append	(	const T *	values,
		size_t	count
	)

Search for all occurrences

Appends one or more element(s) to the array.

Parameters:

[in]	values	- A pointer to a C-style array of elements, from which the appended elements will be copied.
[in]	count	- The number of elements to be appended.

Returns:: A reference to 'this'.

Array< T > & append ( const Array< T > & array )

Search for all occurrences

Appends the contents of another array to this array.

Parameters:

[in] array - The array from which elements are to be appended.

Returns:: A reference to 'this'.

Array< T > & insertAt	(	size_t	index,
		const T &	value
	)

Search for all occurrences

Inserts a single value, at a given location, into this array.

Parameters:

[in]	index	- The index at which the element is to be inserted. This index must be smaller or equal to the used length of the array.
[in]	value	- The value to be inserted.

Returns:: A reference to 'this'.

Array< T > & insertAt	(	size_t	index,
		const T *	values,
		size_t	count
	)

Search for all occurrences

Inserts a one or more value(s), at a given location, into this array.

Parameters:

[in]	index	- The index at which the element is to be inserted. This index must be smaller or equal to the used length of the array.
[in]	values	- A pointer to a C-style array of elements, from which the inserted elements will be copied.
[in]	count	- The number of elements to be inserted.

Returns:: A reference to 'this'.

         :

    enum {

Array< T > & removeAt ( size_t index )

Search for all occurrences

Removes a single element from the array.

Parameters:

[in] index - The index of the element to be removed. This index must be valid (within bounds).

Returns:: A reference to 'this'.

bool remove	(	const T &	value,
		size_t	start = `0`
	)

Search for all occurrences

Searches for a value in the array and, if it is found, removes it from the array.

Parameters:

[in]	value	- The value to search for.
[in]	start	- The index at which to start searching. Preceding elements are not searched.

Returns:: true if a value was found & removed; false otherwise.

Remarks:: If multiple copies of the same value are stored in the array, only the first instance will be removed.

Array< T > & removeFirst ( ) [inline]

Search for all occurrences

Removes the first element of the array.

Returns:: A reference to 'this'.

Remarks:: Must not be called on an empty array.

Array< T > & removeLast ( ) [inline]

Search for all occurrences

Removes the last element of the array.

Returns:: A reference to 'this'.

Remarks:: Must not be called on an empty array.

Array< T > & removeAll ( ) [inline]

Search for all occurrences

Removes all the elements from the array.

Returns:: A reference to 'this'.

Array< T > & removeSubArray	(	size_t	startIndex,
		size_t	endIndex
	)

Search for all occurrences

Removes a subset of the array.

Parameters:

[in]	startIndex	- The index of the first element to be removed.
[in]	endIndex	- The index of the last element to be removed.

Returns:: A reference to 'this'.

Remarks:

Both the start and end indices must be within bounds.
The end index must be greater or equal to the start index.

bool contains	(	const T &	value,
		size_t	start = `0`
	)		const `[inline]`

Search for all occurrences

Determines if a value is stored in the array.

Parameters:

[in]	value	- The value for which to search for.
[in]	start	- The index at which to start searching. Preceding elements are not searched.

Returns:: true if the value was found in the array; false otherwise.

bool find	(	const T &	value,
		size_t &	foundAt,
		size_t	start = `0`
	)		const

Search for all occurrences

Searches for a value in the array.

Parameters:

[in]	value	- The value to search for.
[out]	foundAt	- The index at which the value was found. Indeterminate if the value was not found.
[in]	start	- The index at which to start searching. Preceding elements are not searched.

Returns:: true if the value was found in the array; false otherwise.

size_t find ( const T & value ) const

Search for all occurrences

Searches for a value in the array.

Parameters:

[in] value - The value to search for.

Returns:: The index at which the value was found, or -1 if the value was not found. (Since this returns an unsigned value, -1 is converted to the the largest positive value).

size_t findFrom	(	const T &	value,
		size_t	start
	)		const

Search for all occurrences

Searches for a value in the array, starting at a given index.

Parameters:

[in]	value	- The value to search for.
[in]	start	- The index at which to start searching.

Returns:: The index at which the value was found, or -1 if the value was not found. (Since this returns an unsigned value, -1 is converted to the the largest positive value).

size_t length ( ) const [inline]

Search for all occurrences

Returns the number of elements used (as opposed to simply allocated/reserved) in the array.

bool isEmpty ( ) const [inline]

Search for all occurrences

Returns true if the number of used elements in the array is 0; returns false otherwise.

size_t lengthUsed ( ) const [inline]

Search for all occurrences

Returns the number of elements used (as opposed to simply allocated/reserved) in the array.

Array< T > & setLengthUsed	(	size_t	length,
		const T &	defaultVal = `T()`
	)

Search for all occurrences

Sets the number of elements used (as opposed to simply allocated/reserved) in the array.

Parameters:

[in]	length	- The new "used length" of the array.
[in]	defaultVal	- The default value for new elements, used only if the length of the array is increased.

Returns:: A reference to 'this'.

size_t lengthReserved ( ) const [inline]

Search for all occurrences

Returns the number of elements allocated/reserved (as opposed to actually used) in the array.

Array< T > & setLengthReserved ( size_t length )

Search for all occurrences

Sets the number of elements allocated/reserved (as opposed to actually used) in the array.

Parameters:

[in] length - The new "reserved length" of the array.

Returns:: A reference to 'this'.

size_t growLength ( ) const [inline]

Search for all occurrences

Returns the growth length of the array.

For more information on the growth length, see setGrowLength().

Array< T > & setGrowLength ( size_t glen ) [inline]

Search for all occurrences

Sets the growth length of the array.

The growth length is the minimum number elements by which the reserved space is grown whenever the array runs out of reserved space.

Array< T > & reverse ( )

Search for all occurrences

Reverses the sequence of elements in the array.

Reverses the sequence of elements in the array such that the last element becomes the first.

Returns:: A reference to 'this'.

Array< T > & swap	(	size_t	i1,
		size_t	i2
	)

Search for all occurrences

Swaps two elements in this array.

Parameters:

[in]	i1	- The index of the first element to swap. This index must be within bounds.
[in]	i2	- The index of the second element to swap. This index must be within bounds.

void sort ( CompareFnc cmp )

Search for all occurrences

Sorts the elements of the array using a custom comparison function.

The sort if performed with the QuickSort algorithm.

Parameters:

[in] cmp - The comparison function used to order the elements.

See also:: CompareFnc

const T * asArrayPtr ( ) const [inline]

Search for all occurrences

Returns the array storage as a C-style array pointer.

Remarks:: Any modification to the contents of the array, through this pointer, may be dangerous.

T * asArrayPtr ( ) [inline]

Search for all occurrences

bool isValidIndex ( size_t i ) const [inline]

Search for all occurrences

Returns whether the given array index is valid for this array.

Returns:: true if the given index is within the bounds of this array; false otherwise.

size_t quickSortPartition	(	T *	data,
		size_t	first,
		size_t	last,
		CompareFnc	cmp
	)		`[static, protected]`

Search for all occurrences

The partition portion of the QuickSort algorithm.

void quickSortRecursive	(	T *	data,
		size_t	first,
		size_t	last,
		CompareFnc	cmp
	)		`[static, protected]`

Search for all occurrences

Recursive QuickSort function used to sort the elements of the array.

void handleOutOfMemory ( ) [inline, static, protected]

Search for all occurrences

Utility function, called when the array fails to allocate memory.

T * ArrayAllocate ( size_t len ) [inline, static, protected]

Search for all occurrences

Allocates an array of elements without constructing them.

void ArrayConstruct	(	T *	arrayBegin,
		size_t	len,
		const T &	defaultVal
	)		`[inline, static, protected]`

Search for all occurrences

Constructs an array of elements.

                 {

//==============================================================================
// class MaxSDK::Array
//

void ArrayDeAllocate ( T * arrayBegin ) [inline, static, protected]

Search for all occurrences

De-allocates an array of elements without destructing them.

: public MaxHeapOperators {

void ArrayDestruct	(	T *	arrayBegin,
		size_t	len
	)		`[inline, static, protected]`

Search for all occurrences

Destructs an array of elements.

: public MaxHeapOperators {
public:


    typedef int( __cdecl *CompareFnc) ( const void *elem1, const void *elem2 );

void ArrayCopy	(	T *	pCopy,
		const T *	pSource,
		size_t	nCount
	)		`[static, protected]`

Search for all occurrences

Copies an array of elements to an already-constructed buffer.

Will use the copy operator if needed.

void ArrayCopyOverlap	(	T *	pCopy,
		const T *	pSource,
		size_t	nCount
	)		`[static, protected]`

Search for all occurrences

Copies an array of elements when the target and destination memory buffers may overlap.

void ArrayCopyConstruct	(	T *	pCopy,
		const T *	pSource,
		size_t	nCount
	)		`[static, protected]`

Search for all occurrences

Copies and array of elements to a non-constructed.

Will use the copy constructor if needed.

Member Data Documentation

T* mpArray [protected]

Search for all occurrences

Pointer to the storage buffer.

size_t mReservedLen [protected]

Search for all occurrences

The reserved length (in number of elements, not bytes).

size_t mUsedLen [protected]

Search for all occurrences

The used length (in number of elements, not bytes).

size_t mGrowLen [protected]

Search for all occurrences

The growth length. See setGrowLength().

Array< T > Class Template Reference

Detailed Description

template<class T> class MaxSDK::Array< T >

Public Types

Public Member Functions

Protected Types

Static Protected Member Functions

Protected Attributes

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class T>
class MaxSDK::Array< T >