ON_ClassArray< T > Class Template Reference

#include <opennurbs_array.h>

Inheritance diagram for ON_ClassArray< T >:

Public Member Functions
	ON_ClassArray () ON_NOEXCEPT
	construction //////////////////////////////////////////////////////// More...
	ON_ClassArray (size_t)
	size_t parameter = initial capacity More...
	ON_ClassArray (const ON_ClassArray< T > &)
	Copy constructor. More...
virtual	~ON_ClassArray ()
	override for struct member deallocation, etc. More...
void	Append (const T &)
void	Append (int, const T *)
	Append copy of an array T[count]. More...
T &	AppendNew ()
	array operations //////////////////////////////////////////////////// More...
T *	Array ()
	The Array() function return the. More...
const T *	Array () const
	m_a pointer value. More...
T *	At (int)
	At(index) returns nullptr if index < 0 or index >= count. More...
T *	At (unsigned int)
T *	At (ON__INT64)
T *	At (ON__UINT64)
const T *	At (int) const
const T *	At (unsigned int) const
const T *	At (ON__INT64) const
const T *	At (ON__UINT64) const
int	BinarySearch (const T *, int(*)(const T *, const T *)) const
	See Also: ON_CompareIncreasing<T> and ON_CompareDeccreasing<T> More...
int	BinarySearch (const T *, int(*)(const T *, const T *), int) const
int	Capacity () const
	capacity of array More...
int	Count () const
	query /////////////////////////////////////////////////////////////// More...
void	Destroy ()
	onfree any memory and set count and capacity to zero More...
void	EmergencyDestroy (void)
	emergency bailout /////////////////////////////////////////////////// More...
void	Empty ()
	Sets count to 0, leaves capacity untouched. More...
T *	First ()
const T *	First () const
	returns nullptr if count = 0 More...
virtual bool	HeapSort (int(*)(const T *, const T *))
	QuickSort() is generally the better choice. More...
void	Insert (int, const T &)
	Insert called with a reference uses operator =. More...
T *	KeepArray ()
T *	Last ()
const T *	Last () const
	returns nullptr if count = 0 More...
int	NewCapacity () const
	operator const T * () const
	operator T* ()
	The cast operators return a pointer. More...
ON_ClassArray< T > &	operator= (const ON_ClassArray< T > &)
	Assignment operator. More...
T &	operator[] (int)
T &	operator[] (unsigned int)
T &	operator[] (ON__INT64)
T &	operator[] (ON__UINT64)
const T &	operator[] (int) const
const T &	operator[] (unsigned int) const
const T &	operator[] (ON__INT64) const
const T &	operator[] (ON__UINT64) const
bool	Permute (const int *)
virtual bool	QuickSort (int(*)(const T *, const T *))
	Sorts the array using the heap sort algorithm. More...
virtual T *	Realloc (T *, int)
	low level memory managment /////////////////////////////////////// More...
void	Remove ()
void	Remove (int)
T *	Reserve (size_t)
	memory managment ///////////////////////////////////////////////// More...
void	Reverse ()
	reverse order More...
int	Search (const T *, int(*)(const T *, const T *)) const
void	SetArray (T *)
void	SetArray (T *, int, int)
T *	SetCapacity (size_t)
void	SetCount (int)
	low level memory managment ////////////////////////////////////////// More...
void	Shrink ()
	remove unused capacity More...
unsigned int	SizeOfArray () const
	amount of memory in the m_a[] array More...
unsigned int	SizeOfElement () const
	amount of memory in an m_a[] array element More...
bool	Sort (ON::sort_algorithm sort_algorithm, int *, int(*)(const T *, const T *)) const
bool	Sort (ON::sort_algorithm sort_algorithm, int *, int(*)(const T *, const T *, void *), void *) const
void	Swap (int, int)
	swap elements i and j More...
unsigned int	UnsignedCount () const
void	Zero ()

Protected Member Functions
void	ConstructDefaultElement (T *)
void	DestroyElement (T &)
void	Move (int, int, int)
	implimentation ////////////////////////////////////////////////////// More...

Protected Attributes
T *	m_a
	pointer to array memory More...
int	m_capacity
	actual length of m_a[] More...
int	m_count
	0 <= m_count <= m_capacity More...

Detailed Description

template<class T>
class ON_ClassArray< T >

The ON_ClassArray<> template is designed to be used with classes that require non-trivial construction or destruction. Any class used with the ON_ClassArray<> template must have a robust operator=().

By default, ON_ClassArray<> uses onrealloc() to manage the dynamic array memory. If you want to use something besides onrealloc() to manage the array memory, then override ON_ClassArray::Realloc(). In practice this means that if your class has members with back-pointers, then you cannot use it in the defaule ON_ClassArray. See ON_ObjectArray for an example.

Constructor & Destructor Documentation

ON_ClassArray() [1/3]

template<class T >

ON_ClassArray< T >::ON_ClassArray

(

)

construction ////////////////////////////////////////////////////////

ON_ClassArray() [2/3]

template<class T >

ON_ClassArray< T >::ON_ClassArray

(

size_t

c

)

size_t parameter = initial capacity

ON_ClassArray() [3/3]

template<class T>

ON_ClassArray< T >::ON_ClassArray

(

const ON_ClassArray< T > &

src

)

Copy constructor.

< operator= defined below

~ON_ClassArray()

template<class T >

ON_ClassArray< T >::~ON_ClassArray ( )

virtual

override for struct member deallocation, etc.

Member Function Documentation

Append() [1/2]

template<class T>

void ON_ClassArray< T >::Append

(

const T &

x

)

Append copy of element. Increments count by 1.

< (int) cast is for 64 bit pointers

26 Sep 2005 Dale Lear User passed in an element of the m_a[] that will get reallocated by the call to Reserve(newcapacity).

< ON_*Array<> templates do not require robust copy constructor.

< ON_*Array<> templates require a robust operator=.

Append() [2/2]

template<class T>

void ON_ClassArray< T >::Append	(	int	count,
		const T *	p
	)

Append copy of an array T[count].

AppendNew()

template<class T >

T & ON_ClassArray< T >::AppendNew

(

)

array operations ////////////////////////////////////////////////////

Most efficient way to add a new class to the array. Increases count by 1.

First destroy what's there ..

and then get a properly initialized element

Array() [1/2]

template<class T >

T * ON_ClassArray< T >::Array

(

)

The Array() function return the.

Array() [2/2]

template<class T >

const T * ON_ClassArray< T >::Array

(

)

const

m_a pointer value.

At() [1/8]

template<class T >

T * ON_ClassArray< T >::At

(

int

i

)

At(index) returns nullptr if index < 0 or index >= count.

At() [2/8]

template<class T >

T * ON_ClassArray< T >::At

(

unsigned int

i

)

At() [3/8]

template<class T >

T * ON_ClassArray< T >::At

(

ON__INT64

i

)

At() [4/8]

template<class T >

T * ON_ClassArray< T >::At

(

ON__UINT64

i

)

At() [5/8]

template<class T >

const T * ON_ClassArray< T >::At

(

int

i

)

const

At() [6/8]

template<class T >

const T * ON_ClassArray< T >::At

(

unsigned int

i

)

const

At() [7/8]

template<class T >

const T * ON_ClassArray< T >::At

(

ON__INT64

i

)

const

At() [8/8]

template<class T >

const T * ON_ClassArray< T >::At

(

ON__UINT64

i

)

const

BinarySearch() [1/2]

template<class T>

int ON_ClassArray< T >::BinarySearch	(	const T *	key,
		int(*)(const T *, const T *)	compar
	)		const

See Also: ON_CompareIncreasing<T> and ON_CompareDeccreasing<T>

BinarySearch( p, compare ) does a fast search of a sorted array and returns the smallest index "i" of the element that satisifies 0==compare(p,&array[i]).

BinarySearch( p, compare, count ) does a fast search of the first count element sorted array and returns the smallest index "i" of the element that satisifies 0==compare(p,&array[i]). The version that takes a "count" is useful when elements are being appended during a calculation and the appended elements are not sorted.

If the search is successful, BinarySearch() returns the index of the element (>=0). If the search is not successful, BinarySearch() returns -1. Use QuickSort( compare ) or, in rare cases and after meaningful performance testing using optimzed release builds, HeapSort( compare ) to sort the array.

BinarySearch() [2/2]

template<class T>

int ON_ClassArray< T >::BinarySearch	(	const T *	key,
		int(*)(const T *, const T *)	compar,
		int	count
	)		const

Capacity()

template<class T >

int ON_ClassArray< T >::Capacity

(

)

const

capacity of array

ConstructDefaultElement()

template<class T>

void ON_ClassArray< T >::ConstructDefaultElement ( T *  p )

protected

use placement ( new(size_t,void*) ) to construct T in supplied memory

Count()

template<class T >

int ON_ClassArray< T >::Count

(

)

const

query ///////////////////////////////////////////////////////////////

number of elements in array

Destroy()

template<class T >

void ON_ClassArray< T >::Destroy

(

)

onfree any memory and set count and capacity to zero

DestroyElement()

template<class T>

void ON_ClassArray< T >::DestroyElement ( T &  x )

protected

EmergencyDestroy()

template<class T >

void ON_ClassArray< T >::EmergencyDestroy

(

void

)

emergency bailout ///////////////////////////////////////////////////

emergency destroy ///////////////////////////////////////////////////

call only when memory used by this array may have become invalid for reasons beyond your control. EmergencyDestroy() zeros anything that could possibly cause ~ON_ClassArray() to crash.

Empty()

template<class T >

void ON_ClassArray< T >::Empty

(

)

Sets count to 0, leaves capacity untouched.

This call to memset is ok even when T has a vtable because in-place construction is used later.

First() [1/2]

template<class T >

T * ON_ClassArray< T >::First

(

)

First() [2/2]

template<class T >

const T * ON_ClassArray< T >::First

(

)

const

returns nullptr if count = 0

HeapSort()

template<class T>

bool ON_ClassArray< T >::HeapSort ( int(*)(const T *, const T *)  compar )

virtual

QuickSort() is generally the better choice.

Sorts the array using the heap sort algorithm. See Also: ON_CompareIncreasing<T> and ON_CompareDeccreasing<T>

Reimplemented in ON_ObjectArray< T >, ON_ObjectArray< ON_Texture >, ON_ObjectArray< ON_BrepTrim >, ON_ObjectArray< ON_BrepFaceSide >, ON_ObjectArray< ON_BrepEdge >, ON_ObjectArray< ON_BrepLoop >, ON_ObjectArray< ON_BrepRegion >, ON_ObjectArray< ON_BrepFace >, and ON_ObjectArray< ON_BrepVertex >.

Insert()

template<class T>

void ON_ClassArray< T >::Insert	(	int	i,
		const T &	x
	)

Insert called with a reference uses operator =.

Insert copy of element. Uses memmove() to perform any necessary moving. Increases count by 1.

This call to memset is ok even when T has a vtable because in-place construction is used later.
< uses T::operator=() to copy x to array

KeepArray()

template<class T >

T * ON_ClassArray< T >::KeepArray

(

)

returns pointer to array and zeros out this class. Caller is responsible for calling destructor on each element and then using onfree() to release array memory. E.g.,

for (int i=capacity;i>=0;i–) { array[i].~T(); } onfree(array);

Last() [1/2]

template<class T >

T * ON_ClassArray< T >::Last

(

)

Last() [2/2]

template<class T >

const T * ON_ClassArray< T >::Last

(

)

const

returns nullptr if count = 0

Move()

template<class T >

void ON_ClassArray< T >::Move ( int  dest_i, int  src_i, int  ele_cnt  )

protected

implimentation //////////////////////////////////////////////////////

array operations ////////////////////////////////////////////////////

private function for moving blocks of array memory caller is responsible for updating m_count and managing destruction/creation.
This call to memmove is ok, even when T is a class with a vtable because the it doesn't change the vtable for the class. Classes that have back pointers, like ON_UserData, are handled elsewhere and cannot be in ON_ClassArray<>s.

NewCapacity()

template<class T >

int ON_ClassArray< T >::NewCapacity

(

)

const

is < current Count(), then count is reduced to value. When the dynamic array needs to grow, this calculates the new value for m_capacity.

Note: This code appears in ON_SimpleArray<T>::NewCapacity() and ON_ClassArray<T>::NewCapacity(). Changes made to either function should be made to both functions. Because this code is template code that has to support dynamic linking and the code is defined in a header, I'm using copy-and-paste rather than a static.


This function returns 2*m_count unless that will result in an additional allocation of more than cap_size bytes. The cap_size concept was added in January 2010 because some calculations on enormous models were slightly underestimating the initial Reserve() size and then wasting gigabytes of memory.

cap_size = 128 MB on 32-bit os, 256 MB on 64 bit os

Growing the array will increase the memory use by more than cap_size.

operator const T *()

template<class T >

ON_ClassArray< T >::operator const T *

(

)

const

to the array. If Count() is zero, this pointer is nullptr.

operator T*()

template<class T >

ON_ClassArray< T >::operator T*

(

)

The cast operators return a pointer.

operator=()

template<class T>

ON_ClassArray< T > & ON_ClassArray< T >::operator=

(

const ON_ClassArray< T > &

src

)

Assignment operator.

operator[]() [1/8]

template<class T >

T & ON_ClassArray< T >::operator[]

(

int

i

)

The operator[] does to not check for valid indices. The caller is responsibile for insuring that 0 <= i < Capacity()

operator[]() [2/8]

template<class T >

T & ON_ClassArray< T >::operator[]

(

unsigned int

i

)

operator[]() [3/8]

template<class T >

T & ON_ClassArray< T >::operator[]

(

ON__INT64

i

)

operator[]() [4/8]

template<class T >

T & ON_ClassArray< T >::operator[]

(

ON__UINT64

i

)

operator[]() [5/8]

template<class T >

const T & ON_ClassArray< T >::operator[]

(

int

i

)

const

operator[]() [6/8]

template<class T >

const T & ON_ClassArray< T >::operator[]

(

unsigned int

i

)

const

operator[]() [7/8]

template<class T >

const T & ON_ClassArray< T >::operator[]

(

ON__INT64

i

)

const

operator[]() [8/8]

template<class T >

const T & ON_ClassArray< T >::operator[]

(

ON__UINT64

i

)

const

Permute()

template<class T >

bool ON_ClassArray< T >::Permute

(

const int *

index

)

Permutes the array so that output[i] = input[index[i]]. The index[] array should be a permutation of (0,...,Count()-1).

< must use memcopy and not operator=

QuickSort()

template<class T>

bool ON_ClassArray< T >::QuickSort ( int(*)(const T *, const T *)  compar )

virtual

Sorts the array using the heap sort algorithm.

Reimplemented in ON_ObjectArray< T >, ON_ObjectArray< ON_Texture >, ON_ObjectArray< ON_BrepTrim >, ON_ObjectArray< ON_BrepFaceSide >, ON_ObjectArray< ON_BrepEdge >, ON_ObjectArray< ON_BrepLoop >, ON_ObjectArray< ON_BrepRegion >, ON_ObjectArray< ON_BrepFace >, and ON_ObjectArray< ON_BrepVertex >.

Realloc()

template<class T>

T * ON_ClassArray< T >::Realloc ( T *  ptr, int  capacity  )

virtual

low level memory managment ///////////////////////////////////////

Class ON_ClassArray<>

By default, ON_ClassArray<> uses onrealloc() to manage the dynamic array memory. If you want to use something besides onrealloc() to manage the array memory, then override Realloc(). The T* Realloc(ptr, capacity) should do the following:

1) If ptr and capacity are zero, return nullptr. 2) If ptr is nullptr, an capacity > 0, allocate a memory block of capacity*sizeof(T) bytes and return a pointer to this block. If the allocation request fails, return nullptr. 3) If ptr is not nullptr and capacity is 0, free the memory block pointed to by ptr and return nullptr. 4) If ptr is not nullptr and capacity > 0, then reallocate the memory block and return a pointer to the reallocated block. If the reallocation request fails, return nullptr.

NOTE WELL: Microsoft's VC 6.0 realloc() contains a bug that can cause crashes and should be avoided. See MSDN Knowledge Base article ID Q225099 for more information. (re)allocated capacity*sizeof(T) bytes

construction ////////////////////////////////////////////////////////

Reimplemented in ON_ObjectArray< T >, ON_ObjectArray< ON_Texture >, ON_ObjectArray< ON_BrepTrim >, ON_ObjectArray< ON_BrepFaceSide >, ON_ObjectArray< ON_BrepEdge >, ON_ObjectArray< ON_BrepLoop >, ON_ObjectArray< ON_BrepRegion >, ON_ObjectArray< ON_BrepFace >, and ON_ObjectArray< ON_BrepVertex >.

Remove() [1/2]

template<class T >

void ON_ClassArray< T >::Remove

(

)

Removes last element. Decrements count by 1. Does not change capacity.

Remove() [2/2]

template<class T >

void ON_ClassArray< T >::Remove

(

int

i

)

Removes element. Uses memmove() to perform any necessary shifting. Decrements count by 1. Does not change capacity

This call to memset is ok even when T has a vtable because in-place construction is used later.
This call to memset is ok even when T has a vtable because in-place construction is used later.

Reserve()

template<class T >

T * ON_ClassArray< T >::Reserve

(

size_t

newcap

)

memory managment /////////////////////////////////////////////////

memory managment ////////////////////////////////////////////////////

increase capacity to at least the requested value

Reverse()

template<class T >

void ON_ClassArray< T >::Reverse

(

)

reverse order

NOTE: If anything in "T" depends on the value of this's address, then don't call Reverse().

Search()

template<class T>

int ON_ClassArray< T >::Search	(	const T *	key,
		int(*)(const T *, const T *)	compar
	)		const

Search( p, compare ) does a SLOW search of the array starting at array[0] and returns the index "i" of the first element that satisfies compare(p,&array[i])==0. If the search is not successful, then Search() returns -1. Search() is only suitable for performing infrequent searches of small arrays. Sort the array and use BinarySearch() for performing efficient searches.

SetArray() [1/2]

template<class T>

void ON_ClassArray< T >::SetArray

(

T *

p

)

Description: Do not use this version of SetArray(). Use the one that takes a pointer, count and capacity: SetArray(pointer,count,capacity)

SetArray() [2/2]

template<class T>

void ON_ClassArray< T >::SetArray	(	T *	p,
		int	count,
		int	capacity
	)

Description: Expert user tool to set the memory used by the dyanmic array. Parameters: T* pointer - [in] int count - [in] 0 <= count <= capacity int capacity - [in] m_a is set to pointer, m_count is set to count, and m_capacity is set to capacity. It is critical that the pointer be one returned by onmalloc(sz), where sz >= capacity*sizeof(T[0]), and that the in-place operator new has been used to initialize each element of the array.

SetCapacity()

template<class T >

T * ON_ClassArray< T >::SetCapacity

(

size_t

new_capacity

)

Shrink/grows capacity. If value

Allow "expert" users of ON_SimpleArray<>.SetArray(*,*,0) to clean up after themselves and deals with the case when the forget to clean up after themselves.






uses "placement" for class construction/destruction

growing

initialize new elements with default constructor

even when m_a is an array of classes with vtable pointers, this call to memset(..., 0, ...) is what I want to do because in-place construction will be used when needed on this memory.


memory allocation failed

shrinking

memory allocation failed

SetCount()

template<class T >

void ON_ClassArray< T >::SetCount

(

int

count

)

low level memory managment //////////////////////////////////////////

If value is <= Capacity(), then sets count to specified value.

Shrink()

template<class T >

void ON_ClassArray< T >::Shrink

(

)

remove unused capacity

SizeOfArray()

template<class T >

unsigned int ON_ClassArray< T >::SizeOfArray

(

)

const

amount of memory in the m_a[] array

SizeOfElement()

template<class T >

unsigned int ON_ClassArray< T >::SizeOfElement

(

)

const

amount of memory in an m_a[] array element

Sort() [1/2]

template<class T>

bool ON_ClassArray< T >::Sort	(	ON::sort_algorithm	sort_algorithm,
		int *	index,
		int(*)(const T *, const T *)	compar
	)		const

Description: Sort() fills in the index[] array so that array[index[i]] <= array[index[i+1]].
The array is not modified.
Parameters: sort_algorithm - [in]
ON::sort_algorithm::quick_sort (best in general) or ON::sort_algorithm::heap_sort Use ON::sort_algorithm::heap_sort only if you have done extensive testing with optimized release builds and are confident heap sort is significantly faster. index - [out] an array of length Count() that is returned with some permutation of (0,1,...,Count()-1). compare - [in] compare function compare(a,b) should return <0 if a<b, 0, if a==b, and >0 if a>b.

Returns: true if successful

Sort() [2/2]

template<class T>

bool ON_ClassArray< T >::Sort	(	ON::sort_algorithm	sort_algorithm,
		int *	index,
		int(*)(const T *, const T *, void *)	compar,
		void *	p
	)		const

Description: Sort() fills in the index[] array so that array[index[i]] <= array[index[i+1]].
The array is not modified.
Parameters: sort_algorithm - [in]
ON::sort_algorithm::quick_sort (best in general) or ON::sort_algorithm::heap_sort Use ON::sort_algorithm::heap_sort only if you have done extensive testing with optimized release builds and are confident heap sort is significantly faster. index - [out] an array of length Count() that is returned with some permutation of (0,1,...,Count()-1). compare - [in] compare function compare(a,b,p) should return <0 if a<b, 0, if a==b, and >0 if a>b. p - [in] pointer passed as third argument to compare.

Returns: true if successful

Parameters

index	index[]
compar	int compare(const T*,const T*,void* p)
p	p

Swap()

template<class T >

void ON_ClassArray< T >::Swap	(	int	i,
		int	j
	)

swap elements i and j

UnsignedCount()

template<class T >

unsigned int ON_ClassArray< T >::UnsignedCount

(

)

const

Zero()

template<class T >

void ON_ClassArray< T >::Zero

(

)

Destroys all elements and fills them with values set by the defualt constructor. Count and capacity are not changed.

This call to memset is ok even when T has a vtable because in-place construction is used later.

Member Data Documentation

m_a

template<class T>

T* ON_ClassArray< T >::m_a

protected

pointer to array memory

m_capacity

template<class T>

int ON_ClassArray< T >::m_capacity

protected

actual length of m_a[]

m_count

template<class T>

int ON_ClassArray< T >::m_count

protected

0 <= m_count <= m_capacity