UT/UT_PtrMatrixRaw.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Cristin Barghiel
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        Utility Library (C++)
 *
 * COMMENTS:
 *      This is a class template that implements a resizable matrix of 
 *      arbitrary objects. The template parameter represents the type
 *      of object, and is called Thing. You can instantiate this class
 *      with any object or pointer, such as:
 *              UT_PtrMatrixRaw<int>            iObj;
 *              UT_PtrMatrixRaw<GeoPrimMesh>    mObj;
 *              UT_PtrMatrixRaw<GeoPoint*>      pObj; ... etc
 *      The "Val" in the class name stands for "passed by value", which 
 *      is the argument passing strategy used by this class. Use this class
 *      if you want to construct matrices of pointers or primitive types,
 *      for which it is more efficient to pass in the value directly rather
 *      than via refererences. To build matrices of arbitrary objects, use
 *      UT_RefMatrix instead.
 *
 * Revision 1.6  1996/03/04  02:49:59  cb
 * Changed to NCC.
 *
 * Revision 1.5  1995/12/28  00:05:46  cb
 * Made some "unsigned" fixes and slightly changed the "friend" declarations in *Raw.h
 *
 * Revision 1.4  1995/12/20  21:27:21  cb
 * After compiling with NCC/KCC.
 *
 * Revision 1.3  1995/09/29  12:30:43  phb
 * Changed local includes of UT files from <UT/UT*.h> to "UT*.h"
 *
 * Revision 1.2  1995/09/28  21:17:44  adubey
 * Fixed #include directive calls.
 *
 * Revision 1.1.1.1  1995/09/17  18:10:25  mark
 * initial source release
 *
 * Revision 1.2  1995/05/11  23:11:59  mark
 * Fixed some bugs with allocation
 *
 * Revision 1.1  1995/03/17  03:33:53  mark
 * Initial revision
 *
 */

#ifndef __UT_PtrMatrixRaw_h__
#define __UT_PtrMatrixRaw_h__

#include "UT_API.h"
#include "UT_PtrArrayRaw.h"

class UT_API UT_PtrMatrixRaw {
public:
    // Trivial constructor and destructor. WARNING: this is really meant to
    // be a private class. You should normally instantiate it through its
    // friend(s). We made these 2 methods public to avoid compiler warnings.
    UT_PtrMatrixRaw(unsigned int mSz = 0, unsigned int nSz = 0) : rowArr(mSz)
    {
        nbrCols = nSz;
    }
    ~UT_PtrMatrixRaw(void);

    // Copy constructor that copies each Thing from the source matrix to 
    // this matrix using the '=' operator.
    UT_PtrMatrixRaw(const UT_PtrMatrixRaw &m);

    // Append a row or insert it at a given index. The matrix is grown to 
    // accommodate it. If dupliCheck is 1, we first search for duplicates; the
    // search method uses the (*compare) function on pairs of Things when
    // specified, and the '==' operator on UT_PtrArray pairs otherwise. The
    // fast insertion methods assign the address of the UT_PtrArray to the 
    // pointer in the row matrix rather than copying each element piece by 
    // piece. All methods return the index of the found or inserted row.
    // t1 and t2 must be pointers to Thing.
    unsigned int        insertRow(unsigned int index); 
    unsigned int        insertRow(const UT_PtrArrayRaw &r, unsigned int index);
    unsigned int        appendRow(const UT_PtrArrayRaw &r);

    // Fast insertion: as mentioned above, we just assign the address of r to
    // the a row array pointer. The UT_PtrMatrix destructor will delete &r
    // when called. Use these methods with care.
    unsigned int        insertRowFast(const UT_PtrArrayRaw &r, unsigned index);
    unsigned int        appendRowFast(const UT_PtrArrayRaw &r);

    // Append a column or insert it at a given index. The matrix is grown to 
    // accommodate it. If dupliCheck is 1, we first search for duplicates; the
    // search method uses the (*compare) function on pairs of Things when
    // specified, and the '==' operator otherwise. t1 and t2 must be pointers
    // to Thing. All methods return the index of the found or inserted column,
    // or -1 if the matrix has no rows. It is OK to insert a column into a 
    // matrix with zero row entries but with space already allocated for at 
    // least one row.
    int         insertCol(unsigned int index); 
    int         insertCol(const UT_PtrArrayRaw &c, unsigned int index);
    int         appendCol(const UT_PtrArrayRaw &c);

    // Remove a row and possibly all its duplicates given a row object or its
    // index in the row array. The methods that take a (*compare)() function
    // use it to compare two Things; the other methods use the '==' operator.
    // to compare two UT_PtrArrays.
    // If dupliCheck is 1, all duplicates found will be removed too. All
    // methods return the row index (index of first row removed). Do not
    // try to access the row after removal, because its contets are undefined.
    // t1 and t2 must be pointers to Thing.
    // For increased efficiency, try to use the 'index' methods whenever 
    // possible.
    int         removeRow(const UT_PtrArrayRaw &r); 
    int         removeRow(unsigned int index);

    // Remove a column and possibly all its duplicates given a column object or
    // its index. The methods that take a (*compare)() function
    // use it to compare two Things; the other methods use the '==' operator.
    // If dupliCheck is 1, all duplicates found will be removed too. All
    // methods return the column index (index of last column removed).
    // t1 and t2 must be pointers to Thing.
    // For increased efficiency, try to use the 'index' methods whenever 
    // possible.
    int         removeCol(const UT_PtrArrayRaw &c); 
    int         removeCol(unsigned int index);

    // Compare the two matrices: to return 1, they should have the same 
    // number or entries, and their Things should all match when compared
    // with '==' or compare() respectively.
    // t1 and t2 must be pointers to Thing.
    int                 operator==(const UT_PtrMatrixRaw &m) const;
    int                 isEqual(const UT_PtrMatrixRaw &m,
                                int (*compare)(const void *t1,const void *t2)
                               ) const;

    // Assignment operator that copies the array piece by piece using the
    // '=' operator defined in UT_PtrArrayRaw. The row and column size of this
    // matrix must be greater or equal to the "used" row and column count of
    // matrix m.
    UT_PtrMatrixRaw     &operator=(const UT_PtrMatrixRaw &m);

    // Subscript operators to return rows. operator() does not check if the
    // matrix needs to be resized. operator[] grows the array of rows to 
    // accommodate the index if necessary; .
    const UT_PtrArrayRaw        &operator()(unsigned int i) const
                                {
                                    return *(const UT_PtrArrayRaw *)rowArr(i);
                                }
    const UT_PtrArrayRaw        &operator[](unsigned int i) const
                                { 
                                    return *(const UT_PtrArrayRaw *)rowArr[i]; 
                                }
    UT_PtrArrayRaw              &operator()(unsigned int i)
                                {
                                    return *(UT_PtrArrayRaw *)rowArr(i);
                                }
    UT_PtrArrayRaw              &operator[](unsigned int i);

    // Return an element of the matrix, WITHOUT any BOUND CHECKING. Use 
    // safeGet() if you don't know whether you are within range or not.
    void                        *operator()(unsigned i, unsigned j) const
                                {
                                    return (*(UT_PtrArrayRaw*)rowArr(i)).arr[j];
                                }
    void                        *&operator()(unsigned int i, unsigned int j) 
                                {
                                    return (*(UT_PtrArrayRaw*)rowArr(i)).arr[j];
                                }

    // Return an element of the matrix, growing the matrix if necessary in
    // the non-const case.
    void                        *safeGet(unsigned i, unsigned j) const
                                {
                                    UT_PtrArrayRaw *r;
                                    r = (UT_PtrArrayRaw *)rowArr[i];
                                    return (r) ? (*r)[j] : (void *)0;
                                }
    void                        *&safeGet(unsigned int i, unsigned int j) 
                                {
                                    if (!rowArr.nbrEntries) insertRow(i);
                                    if (j >= ((UT_PtrArrayRaw *)rowArr(0))->nbrEntries)
                                        insertCol(j);
                                    return ((*this)[i])(j); // yes, operator[]
                                }

    // Return a specified row or column. row() returns an actual reference to
    // the row entry in the matrix WITHOUT growing the array of rows if
    // needed.
    // col() builds a UT_PtrArray from scratch by allocating heap space for it
    // and copying each element into it with the '=' operator. The col() 
    // array must be freed by YOU.
    const UT_PtrArrayRaw        &row(unsigned int i) const {return *(UT_PtrArrayRaw *)rowArr(i);}
    UT_PtrArrayRaw              &row(unsigned int i)       {return *(UT_PtrArrayRaw *)rowArr(i);}
    UT_PtrArrayRaw              &col(unsigned int j) const;

    // Search for t in each row in one of two ways: linearly using the '==' 
    // operator, or binary using the function specified in the parameter list 
    // respectively. find() returns 0 and the indices of the matching element,
    // or -1 if not found. t1 and t2 must be pointers to Thing.
    int         find(const void *t, unsigned int *m, unsigned int *n) const;

    // Search for a row or a column in one of two ways: binary, using a user
    // defined function (*compare) to compare two Things, or linearly using
    // the '==' operator between UT_PtrArrays in findRow() and between Things
    // in findCol(). Note that the arrays to be compared must have an equal
    // number of entries, and not necessarily the same size.
    // Parameter s indicates what index to start searching at.
    // All methods return the row/col index if found, and -1 otherwise.
    // t1 and t2 must be pointers to Thing.
    int findRow(const UT_PtrArrayRaw &r, unsigned int s = 0) const;
    int findCol(const UT_PtrArrayRaw &c, unsigned int s = 0) const;

    // Return the number of rows and column space has been allocated for, and
    // the number of entries used in the rows and columns.
    unsigned int        rowSize(void) const     { return rowArr.capacity();   }
    unsigned int        colSize(void) const     { return nbrCols; }
    unsigned int        rows(void) const        { return rowArr.nbrEntries;}
    unsigned int        cols(void) const        
                        {
                            return (rowArr.nbrEntries) ?
                                ((UT_PtrArrayRaw *)rowArr(0))->nbrEntries : 0;
                        }
    unsigned short      isEmpty(void) const
                        { 
                            return rowArr.nbrEntries == 0 || 
                               (rowArr.nbrEntries == 1 &&
                               ((UT_PtrArrayRaw *)rowArr(0))->nbrEntries == 0);
                        }

    // Resize the array, ie. grow it or shrink it. If copyFlag is 1, the 
    // function copies the data after reallocating space for the array.
    void                resize(unsigned int mSz, unsigned int nSz,
                               unsigned short copyFlag=1);

    // Apply a user-defined function to each element of the matrix 
    // as int as the function returns zero. If applyFct returns
    // 1, apply() stops traversing the list and returns 1; otherwise, apply()
    // returns 0;
    int                 apply(int (*applyFct)(void *t, void *d), void *d);

    // Array of rows, where each row is a reference array of type Thing:
    UT_PtrArrayRaw              rowArr;

    // Number of allocated columns in each row.
    unsigned int        nbrCols;

    // Guts if the insert(...) methods.
    unsigned int        assignRow(const UT_PtrArrayRaw &r, unsigned int index)
                        {
                            rowArr(index) = new UT_PtrArrayRaw(nbrCols);
                            ((UT_PtrArrayRaw *)rowArr(index))->assignSubset(r);
                            return index;
                        }
    unsigned int        insertFastFill(const UT_PtrArrayRaw &r, unsigned idx);
    unsigned int        insertSlowFill(unsigned idx,
                                unsigned uRows, unsigned uCols);

    // Guts of removeCol().
    void                removeOneCol(unsigned int index);

    // Guts of removeRow().
    void                removeOneRow(unsigned int index)
                        {
                            UT_PtrArrayRaw *rdel=(UT_PtrArrayRaw*)rowArr(index);
                            rowArr.remove(index);
                            delete rdel;
                        }
};

#endif

---