The use of CArray

CArray's usage 2007-05-23 10:01

Template<class type,class arg_type>class carray:public CObject Parameters TYPE The template parameter specifies the type of object that is stored in the array. Type is a parameter that is returned by CArray. Arg_type The template parameter specifies the parameter type used to access objects stored in the array. is usually a reference to type. Arg_type is a parameter passed to the CArray. Description The CArray class supports arrays similar to CArray, but can be compressed and extended dynamically if necessary. The array index starts at 0. You can decide whether to fix the upper bounds of an array or to extend the current bounds when an element is added. The upper bound of memory is a contiguous allocation of space, and even some elements can be empty. As with CArray, the access time for CArray index elements is invariant, regardless of the size of the array. Tips Before using an array, use SetSize to establish its size and allocate memory for it. If you do not use setsize, adding elements to an array causes frequent reallocation and copying. Frequent reallocation and copying is not only inefficient, but also leads to memory fragmentation. If you need individual data from a bunch of arrays, you must set the depth of the CDumpContext object to 1 or greater. A member function of this class calls the global help function, which must be customized for most uses of CArray. See "Class Collection Helper" in the Macros and global quantities section. The Help function destructelements is invoked when an element is removed from a CArray object. The Help function constructelements is invoked when an element is added. The derivation of an array class is similar to the derivation of a list. For more information about using CArray, see "Collection" in the online documentation, "Visual C + + Programmer's Guide." #include <afxtempl.h> Please refer to cobarray,destructelement,constructelements,collection classhelpers Members of the CArray class Constructors CArray constructs an empty array Property GetSize gets the number of elements in this array GetUpperBound returns the maximum valid index value SetSize set the number of elements contained in this array Operation FreeExtra free unused memory greater than the current upper bound RemoveAll Remove all elements from this array Element access GetAt returns the value at the given index SetAt set the value of a given index; array does not allow expansion ElementAt returns a temporary reference to the element pointer in an array GetData allows elements in an array to be accessed. can be null Extended Array Setatgrow sets the value for a given index; If necessary, extend the array Add an element at the end of the array and, if necessary, extend the array Append attach another array on the array; If necessary, extend the array Copy copies the other array to the array, and if necessary, extend the array Insert/Remove InsertAt Inserts an element (or all elements in another array) on the specified index. RemoveAt to remove an element from the specified index Operator [] Set or get elements on a specific index member functions Carray::add int Add (Arg_type newelement); throw (CMemoryException); return value The index of the added element. Parameters Arg_type The template parameter specifies the type of the parameter that applies the elements in the array. Newelement The element that is added to this array. Description Add a new element at the end of the array, and the length of the array is 1. If SetSize already uses the Ngrowby value to be larger than 1, the memory is allocated. In any case, the upper bound only increases by 1. Example Example for Carray:add Carray<cpoint.cpoint> Ptarray; CPoint pt (10.20); Ptarray.add (PT); Element 0 Ptarray.add (CPoint (30,40)); Element 1 See carray:setat,carray::setatgrow,carray::insertat,carray::operator[] Carray::append int Append (const carray& SRC); return value The index of the first additional element. Parameters SRC is the source of the element that is attached to the array. Description Call this member function to append the contents of an array to the end of another array. The array must be of the same type. If necessary, append allocates more memory to store the elements attached to the array. Please refer to Carray::copy Carray::carray CArray (); return value Constructs an empty array. Array expands one element at a time. Please refer to Cobarray::cobarray Carray::copy void Copy (const carray& SRC); Parameters SRC is copied to the source of the elements in the array. Description Use this member function to copy the elements of an array to another array. Call this member function to make a copy of the elements of an array with the elements of another array. Copy does not release memory, but if necessary, copy can allocate more memory to the elements that are copied to the array. Please refer to Carray::append Carray::element Type&elementat (int nindex); return value The reference to an array element. Parameters Type specifies the template parameter for the array element type. Nindex is an integer index larger than 0 or smaller than 0, and is less than or equal to the value returned by GetUpperBound. Description Returns a temporary reference to the specified element in an array. It is used to implement the left boundary assignment operator of an array. See carray::operator[] Carray::freeextra void FreeExtra (); Description Frees any additional memory space that is allocated when the array is expanded. This function does not affect the size and upper bounds of the array. Carray::getat TYPE GetAt (int nindex) const; return value The array element that is currently on the index. Parameters Type specifies the template parameter for the array element type. Nindex is an integer index larger than 0 or smaller than 0, and is less than or equal to the value returned by GetUpperBound. Description Returns an array element for a specific index. Note passing a negative value or one that is larger than the value returned by GetUpperBound will cause a failure. Please refer to Carray::setat,carray::operator[],constelements Carray::getdata Const type* GetData () const; type* GetData (); return value A pointer to an array element. Parameters Type specifies the template parameter of an array element type Description Use this member function to obtain direct access to elements in an array. If no element is valid, GetData returns a null value. When direct access to an array element makes work faster, use a warning when calling GetData, and any errors that are directly caused can affect the array element. Please refer to Carray::getat; Carray::setat; Carray::elementat Carray::getsizeint getsize () const; Description Returns the size of the array. Since the index is based on 0, the size of the array is 1 greater than the maximum index. Please refer to Carray::getupperbound,carray::setsize Carray::getupperbound int GetUpperBound () const; Description Returns the upper bound of an array. Because the array index is based on 0, this function returns a value of 1 smaller than getbsize. The getupperbound=-1 condition determines that no elements are included in the array. Please refer to Carray::getsize,carray::setsize Carray::insertat void InsertAt (int nindex,arg_type newelement,int ncount=1); throw (CMemoryException); void InsertAt (int nstarindex,carray*pnewarray); throw (CMemoryException); Parameters nindex integer value, which can be larger than the GetUpperBound return value. Arg_type the template parameter for the specified array element type. Newelement the element to be placed in the array. Ncount the number of times this element should be inserted (the default is 1). Nstarindex An integer index that can be larger than the GetUpperBound return value. Pnewarray an array of other containing elements to be added to this array. Description The first version of InsertAt inserts an element (or multiple copies of the element) on a specific index of the array. In this process, move (by increasing the index value) the original element on this index, and move all the elements that are behind it. The second version inserts all the elements by another CArray collection, starting at the Nstartindex location. The SetAt function replaces a specific array element without moving any elements. Example Example for Carray::insert Carray<cpoint.cpoint> Ptarray; Ptarray.add (CPoint (10,20)); Element 0 Ptarray.add (CPoint (30,40)); Element 1 (would become element 2) Ptarray.insertat (1,cpoint (50,60)); New element 1 Please refer to Getupperbound,carray::setat,carray::removeat Carray::removeall void RemoveAll (); Description Removes all elements from this array. This function also works if the array is already empty. Carray::removeat void RemoveAt (int nindex,int ncount=1); Parameters Nindex an integer index. It is greater than or equal to 0 and is less than or equal to the GetUpperBound return value. Ncount deletes the number of elements. Description Deletes one or more elements from the index specified by the array. In this process, it moves all the elements down. It reduces the upper bounds of the array, but does not free memory. If you attempt to delete multiple elements that are contained in an array above the deletion point, the debug version of the library assertion is used. Carray::setat void SetAt (int nindex,arg_type newelement); Parameters Nindex an integer index. It is greater than or equal to 0 and is less than or equal to the GetUpperBound return value. ARG_TYPE Specifies the template parameter that is used to reference the parameter type of the array element. Newelement the new element value that is stored at the specified location. Description Sets the array element at the specified index. SetAt will not cause array growth. If you want the array to grow automatically, use Setatgrow. The index value must be guaranteed to represent a valid position in an array. If it exceeds the bounds, the debug version of the library assertion is used. See carray::getat,carray::setgrow,carray::elementat,carray::opertor[] Carray::setatgrow void Setatgrow (int nindex,arg_type newelement); throw (CMemoryException); Parameters Nindex an integer index. It is greater than or equal to 0. Arg_type the template parameter for the specified array element type. Newelement is added to the element value of this array. Null values are allowed. Description Sets the array element on the specified index. If necessary, the array grows automatically (adjusts the upper bounds to accommodate the new element). Example Example for Carray::setatgrow Carray<cpoint.cpoint> Ptarray; Ptarray.add (CPoint (10,20)); Element 0 Ptarray.add (CPoint (30,40)); Element 1//element 2 deliberately skipped Ptarray.setatgrow (3,cpoint (50,60));//element 3 See carray::getat,carray::setat,carray::element,carray::oprator[] CArray::SetSize void SetSize (int nnewsize,int ngrowby=-1); throw (CMemoryException); Parameters Nnewsize the new array size (number of elements). must be greater than or equal to 0. Ngrowby This is the minimum value for the position of the element to be allocated if it is necessary to extend the array size. Description Establishes the size of an empty or existing array, and allocates memory if necessary. If the new size is larger than the previous size, the array is truncated and all unused memory is freed. Use this function to set the size of the array before you begin using the array. If SetSize is not used, adding elements to an array causes frequent redistribution and copying. Frequent redistribution and copying are not only inefficient, but also cause memory fragmentation. When an array is expanding, the Ngrowby parameter affects the internal memory allocation. As GetSize and GetUpperBound mentioned, its use does not array size. If you use a default value, MFC allocates memory using the calculation method to avoid memory fragmentation and optimization, making it more efficient for most situations. Please refer to Carray::getupperbound,carray::getsize Operator Carray::opertor[] type& operator[] (int nindex); type& operator[] (int nindex) const; Parameters Type specifies the template parameter for the type of the element in this array. Nindex the index of the element being accessed. Description These subscript operators can easily replace the SetAt and GetAt functions. The first operator, which is not an array of constants, calls it, and can be used on the right (right) or left (left) edge of the assignment statement. The second, called for a constant array, can only be used on the right side of the assignment statement. If the subscript (left or right of an assignment statement) exceeds the bounds, the debug version of the library assertion is used. Please refer to Carray::getat; Carray::setat; Carray::elementat