ON_SimpleArray< T > Class Template Reference

#include <opennurbs_array.h>

Public Member Functions
	ON_SimpleArray () ON_NOEXCEPT
	construction //////////////////////////////////////////////////////// More...
	ON_SimpleArray (const ON_SimpleArray< T > &)
	Copy constructor. More...
	ON_SimpleArray (size_t)
	size_t parameter = initial capacity More...
virtual	~ON_SimpleArray ()
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...
ON__UINT32	DataCRC (ON__UINT32 current_remainder) const
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...
bool	HeapSort (int(*)(const T *, const T *))
void	Insert (int, const T &)
T *	KeepArray ()
T *	Last ()
const T *	Last () const
	returns nullptr if count = 0 More...
void	MemSet (unsigned char)
int	NewCapacity () const
	operator const T * () const
	operator T* ()
	The cast operators return a pointer. More...
ON_SimpleArray< T > &	operator= (const ON_SimpleArray< T > &)
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 *)
bool	QuickSort (int(*)(const T *, const T *))
	See Also: ON_CompareIncreasing<T> and ON_CompareDeccreasing<T> More...
virtual T *	Realloc (T *, int)
	low level memory managment ////////////////////////////////////////// More...
void	Remove ()
virtual void	Remove (int)
T *	Reserve (size_t)
	memory managment //////////////////////////////////////////////////// More...
void	Reverse ()
	reverse order More...
int	Search (const T &) const
int	Search (const T *, int(*)(const T *, const T *)) const
	See Also: ON_CompareIncreasing<T> and ON_CompareDeccreasing<T> More...
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	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_SimpleArray< T >

NoKeywords

/ / Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved. / OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert / McNeel & Associates. / / THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. / ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF / MERCHANTABILITY ARE HEREBY DISCLAIMED. /

/ For complete openNURBS copyright information see http://www.opennurbs.org. / //////////////////////////////////////////////////////////////

The ON_SimpleArray<> template is more efficient than the ON_ClassArray<> template, but ON_SimpleArray<> should not be used for arrays of classes that require explicit construction, destruction, or copy operators.

Elements returned by AppendNew() are memset to zero.

By default, ON_SimpleArray<> uses onrealloc() to manage the dynamic array memory. If you want to use something besides onrealloc() to manage the array memory, then override ON_SimpleArray::Realloc().

Constructor & Destructor Documentation

ON_SimpleArray() [1/3]

template<class T >

ON_SimpleArray< T >::ON_SimpleArray

(

)

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

These constructors create an array that uses onrealloc() to manage the array memory.

~ON_SimpleArray()

template<class T >

ON_SimpleArray< T >::~ON_SimpleArray ( )

virtual

ON_SimpleArray() [2/3]

template<class T>

ON_SimpleArray< T >::ON_SimpleArray

(

const ON_SimpleArray< T > &

src

)

Copy constructor.

< operator= defined below

ON_SimpleArray() [3/3]

template<class T>

ON_SimpleArray< T >::ON_SimpleArray

(

size_t

c

)

size_t parameter = initial capacity

Member Function Documentation

Append() [1/2]

template<class T>

void ON_SimpleArray< 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_SimpleArray< T >::Append	(	int	count,
		const T *	p
	)

Append copy of an array T[count].

AppendNew()

template<class T >

T & ON_SimpleArray< T >::AppendNew

(

)

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

Most efficient way to add a new element to the array. Increases count by 1. Returned element is memset to zero.

Array() [1/2]

template<class T >

T * ON_SimpleArray< T >::Array

(

)

The Array() function return the.

Array() [2/2]

template<class T >

const T * ON_SimpleArray< T >::Array

(

)

const

m_a pointer value.

At() [1/8]

template<class T >

T * ON_SimpleArray< T >::At

(

int

i

)

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

At() [2/8]

template<class T >

T * ON_SimpleArray< T >::At

(

unsigned int

i

)

At() [3/8]

template<class T >

T * ON_SimpleArray< T >::At

(

ON__INT64

i

)

At() [4/8]

template<class T >

T * ON_SimpleArray< T >::At

(

ON__UINT64

i

)

At() [5/8]

template<class T >

const T * ON_SimpleArray< T >::At

(

int

i

)

const

At() [6/8]

template<class T >

const T * ON_SimpleArray< T >::At

(

unsigned int

i

)

const

At() [7/8]

template<class T >

const T * ON_SimpleArray< T >::At

(

ON__INT64

i

)

const

At() [8/8]

template<class T >

const T * ON_SimpleArray< T >::At

(

ON__UINT64

i

)

const

BinarySearch() [1/2]

template<class T>

int ON_SimpleArray< 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.

This worked on a wide range of 32 bit compilers.

Convert "found" pointer to array index.

In an ideal world, return ((int)(found - m_a)) would work everywhere. In practice, this should work any 32 bit compiler and we can hope the optimzer generates efficient code.
"key" not found

BinarySearch() [2/2]

template<class T>

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

This worked on a wide range of 32 bit compilers.

Convert "found" pointer to array index.

In an ideal world, return ((int)(found - m_a)) would work everywhere. In practice, this should work any 32 bit compiler and we can hope the optimzer generates efficient code.
"key" not found

Capacity()

template<class T >

int ON_SimpleArray< T >::Capacity

(

)

const

capacity of array

Count()

template<class T >

int ON_SimpleArray< T >::Count

(

)

const

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

number of elements in array

DataCRC()

template<class T >

ON__UINT32 ON_SimpleArray< T >::DataCRC

(

ON__UINT32

current_remainder

)

const

Destroy()

template<class T >

void ON_SimpleArray< T >::Destroy

(

)

onfree any memory and set count and capacity to zero

EmergencyDestroy()

template<class T >

void ON_SimpleArray< 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_SimpleArray() to crash.

Empty()

template<class T >

void ON_SimpleArray< T >::Empty

(

)

Sets count to 0, leaves capacity untouched.

First() [1/2]

template<class T >

T * ON_SimpleArray< T >::First

(

)

First() [2/2]

template<class T >

const T * ON_SimpleArray< T >::First

(

)

const

returns nullptr if count = 0

HeapSort()

template<class T>

bool ON_SimpleArray< T >::HeapSort

(

int(*)(const T *, const T *)

compar

)

Sorts the array using the heap sort algorithm. QuickSort() is generally the better choice.

Insert()

template<class T>

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

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

KeepArray()

template<class T >

T * ON_SimpleArray< T >::KeepArray

(

)

Description: Expert user tool to take charge of the memory used by the dyanmic array. Returns: A pointer to the array and zeros out this class. The returned pointer is on the heap and must be deallocated by calling onfree().

Last() [1/2]

template<class T >

T * ON_SimpleArray< T >::Last

(

)

Last() [2/2]

template<class T >

const T * ON_SimpleArray< T >::Last

(

)

const

returns nullptr if count = 0

MemSet()

template<class T >

void ON_SimpleArray< T >::MemSet

(

unsigned char

value

)

Sets all bytes in array memory to value. Count and capacity are not changed.

Move()

template<class T >

void ON_SimpleArray< 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.

NewCapacity()

template<class T >

int ON_SimpleArray< 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_SimpleArray< T >::operator const T *

(

)

const

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

operator T*()

template<class T >

ON_SimpleArray< T >::operator T*

(

)

The cast operators return a pointer.

operator=()

template<class T>

ON_SimpleArray< T > & ON_SimpleArray< T >::operator=

(

const ON_SimpleArray< T > &

src

)

operator[]() [1/8]

template<class T >

T & ON_SimpleArray< 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_SimpleArray< T >::operator[]

(

unsigned int

i

)

operator[]() [3/8]

template<class T >

T & ON_SimpleArray< T >::operator[]

(

ON__INT64

i

)

operator[]() [4/8]

template<class T >

T & ON_SimpleArray< T >::operator[]

(

ON__UINT64

i

)

operator[]() [5/8]

template<class T >

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

(

int

i

)

const

operator[]() [6/8]

template<class T >

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

(

unsigned int

i

)

const

operator[]() [7/8]

template<class T >

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

(

ON__INT64

i

)

const

operator[]() [8/8]

template<class T >

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

(

ON__UINT64

i

)

const

Permute()

template<class T >

bool ON_SimpleArray< 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_SimpleArray< T >::QuickSort

(

int(*)(const T *, const T *)

compar

)

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

Sorts the array using the quick sort algorithm.

Realloc()

template<class T>

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

virtual

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

Class ON_SimpleArray<>

By default, ON_SimpleArray<> 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

NoKeywords

/ / Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved. / OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert / McNeel & Associates. / / THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. / ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF / MERCHANTABILITY ARE HEREBY DISCLAIMED. /






/ For complete openNURBS copyright information see http://www.opennurbs.org. / //////////////////////////////////////////////////////////////When this file is parsed with /W4 warnings, two bogus warnings are generated. The ON_ClassArray<T>::DestroyElement template function generates a C4100: 'x' : unreferenced formal parameter warning. This appears to be caused by a bug in the compiler warning code or the way templates are expanded. This pragma is needed squelch the bogus warning. The ON_CompareIncreasing and ON_CompareDecreasing templates generate a C4211: nonstandard extension used : redefined extern to static warning. Microsoft's compiler appears to have a little trouble when static functions are declared before they are defined in a single .cpp file. This pragma is needed squelch the bogus warning. The main reason the definitions of the functions for the ON_SimpleArray and ON_ClassArray templates are in this separate file is so that the Microsoft developer studio autocomplete functions will work on these classes.

This file is included by opennurbs_array.h in the appropriate spot. If you need the definitions in the file, then you should include opennurbs_array.h and let it take care of including this file.construction ////////////////////////////////////////////////////////

Remove() [1/2]

template<class T >

void ON_SimpleArray< T >::Remove

(

)

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

Remove() [2/2]

template<class T >

void ON_SimpleArray< T >::Remove ( int  i )

virtual

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

Reserve()

template<class T >

T * ON_SimpleArray< T >::Reserve

(

size_t

newcap

)

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

increase capacity to at least the requested value

Reverse()

template<class T >

void ON_SimpleArray< T >::Reverse

(

)

reverse order

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

Search() [1/2]

template<class T>

int ON_SimpleArray< T >::Search

(

const T &

key

)

const

Search( e ) does a SLOW search of the array starting at array[0] and returns the index "i" of the first element that satisfies e == array[i]. (== is really memcmp()). If the search is not successful, then Search() returns -1. For Search(T) to work correctly, T must be a simple type. Use Search(p,compare()) for Ts that are structs/classes that contain pointers. Search() is only suitable for performing infrequent searchs of small arrays. Sort the array and use BinarySearch() for performing efficient searches.

Search() [2/2]

template<class T>

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

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

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_SimpleArray< T >::SetArray

(

T *

p

)

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

SetArray() [2/2]

template<class T>

void ON_SimpleArray< 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] 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]).

SetCapacity()

template<class T >

T * ON_SimpleArray< 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.



sets capacity to input value

NOTE: Realloc() does an allocation if the first argument is nullptr.

zero new memory

out of memory

SetCount()

template<class T >

void ON_SimpleArray< T >::SetCount

(

int

count

)

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

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

Shrink()

template<class T >

void ON_SimpleArray< T >::Shrink

(

)

remove unused capacity

SizeOfArray()

template<class T >

unsigned int ON_SimpleArray< T >::SizeOfArray

(

)

const

amount of memory in the m_a[] array

SizeOfElement()

template<class T >

unsigned int ON_SimpleArray< T >::SizeOfElement

(

)

const

amount of memory in an m_a[] array element

Sort() [1/2]

template<class T>

bool ON_SimpleArray< 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,p) 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_SimpleArray< 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_SimpleArray< T >::Swap	(	int	i,
		int	j
	)

swap elements i and j

UnsignedCount()

template<class T >

unsigned int ON_SimpleArray< T >::UnsignedCount

(

)

const

Zero()

template<class T >

void ON_SimpleArray< T >::Zero

(

)

Zeros all array memory. Count and capacity are not changed.

Member Data Documentation

m_a

template<class T>

T* ON_SimpleArray< T >::m_a

protected

pointer to array memory

m_capacity

template<class T>

int ON_SimpleArray< T >::m_capacity

protected

actual length of m_a[]

m_count

template<class T>

int ON_SimpleArray< T >::m_count

protected

0 <= m_count <= m_capacity