UT/UT_PtrMatrix.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 utPtr. You can instantiate this class
 *      with any object or pointer, such as:
 *              UT_PtrMatrix<int>               iObj;
 *              UT_PtrMatrix<GeoPrimMesh>       mObj;
 *              UT_PtrMatrix<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.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:40  adubey
 * Fixed #include directive calls.
 *
 * Revision 1.1.1.1  1995/09/17  18:10:24  mark
 * initial source release
 *
 * Revision 1.2  1995/05/11  23:22:40  mark
 * Changed some method names
 * .,
 *
 * Revision 1.1  1995/03/17  03:33:11  mark
 * Initial revision
 *
 * Revision 1.6  94/02/07  11:18:28  cb
 * renamed some  of the insert() methods to append()
 *
 * Revision 1.5  94/01/28  00:47:33  cb
 * *** empty log message ***
 *
 * Revision 1.4  94/01/04  15:35:56  cb
 * long has become int
 *
 * Revision 1.3  1993/11/29  21:11:38  dale
 * Cleaning up the code
 *
 * Revision 1.2  93/11/29  19:41:32  cb
 * Bug fix re: usage of cols() vs usedCols()
 *
 * Revision 1.1  1993/10/19  18:49:59  cb
 * Initial revision
 *
 *
 */

#ifndef __UT_PtrMatrix_h__
#define __UT_PtrMatrix_h__

#include "UT_PtrMatrixRaw.h"
#include "UT_PtrArray.h"


template <class utPtr>
class UT_PtrMatrix {
public:
    // Trivial constructor and destructor:
     UT_PtrMatrix(unsigned mSz = 0, unsigned nSz = 0) : matrix(mSz, nSz) {}
    ~UT_PtrMatrix(void) {}

    // Copy constructor that copies each utPtr from the source matrix to
    // this matrix using the '=' operator.
    UT_PtrMatrix(const UT_PtrMatrix<utPtr> &m)
    {
        matrix = m.matrix;
    }

    // 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 utPtr.
    unsigned int        insertRow(unsigned int index)
                        {
                            return matrix.insertRow(index);
                        }
    unsigned int        insertRow(const UT_PtrArray<utPtr> &r, unsigned index)
                        {
                            return matrix.insertRow(r.getRawArray(), index);
                        }
    unsigned int        appendRow(const UT_PtrArray<utPtr> &r)
                        { return matrix.appendRow(r.getRawArray()); }

    // 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_PtrArray<utPtr> &r, unsigned idx)
                        {
                            return matrix.insertRowFast(r.getRawArray(), idx);
                        }
    unsigned int        appendRowFast(const UT_PtrArray<utPtr> &r)
                        {
                            return matrix.appendRowFast(r.getRawArray());
                        }

    // 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 utPtr. 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 index) { return matrix.insertCol(index); }
    int         insertCol(const UT_PtrArray<utPtr> &c, unsigned int index)
                {
                    return matrix.insertCol(c.getRawArray(), index);
                }
    int         appendCol(const UT_PtrArray<utPtr> &c)
                {
                    return matrix.appendCol(c.getRawArray());
                }

    // 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_PtrArray.
    // 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 utPtr.
    // For increased efficiency, try to use the 'index' methods whenever
    // possible.
    int         removeRow(const UT_PtrArray<utPtr> &r)
                {
                    return matrix.removeRow(r.getRawArray());
                }
    int         removeRow(unsigned index)
                {
                    return matrix.removeRow(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 utPtr.
    // For increased efficiency, try to use the 'index' methods whenever
    // possible.
    int         removeCol(const UT_PtrArray<utPtr> &c)
                {
                    return matrix.removeCol(c.getRawArray());
                }
    int         removeCol(unsigned int index)
                {
                    return matrix.removeCol(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 utPtr.
    int                 operator==(const UT_PtrMatrix<utPtr> &m) const
                        {
                            return matrix == m.matrix;
                        }
    int                 isEqual(const UT_PtrMatrix<utPtr> &m,
                                int (*compare)(const void *t1,const void *t2)
                               ) const
                        {
                            return matrix.isEqual(m.matrix, compare);
                        }

    // Assignment operator that copies the array piece by piece using the
    // '=' operator defined in UT_PtrArray. The row and column size of this
    // matrix must be greater or equal to the "used" row and column count of
    // matrix m.
    UT_PtrMatrix<utPtr> &operator=(const UT_PtrMatrix<utPtr> &m)
                        {
                            matrix = m.matrix;
                            return *this;
                        }

#if 0
// There are no operators since we can't really upclass to the template array
    // 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_PtrArray<utPtr>    &operator()(unsigned int i) const
                                {
                                    return (const UT_PtrArray<utPtr>&)matrix(i);
                                }
    const UT_PtrArray<utPtr>    &operator[](unsigned int i) const
                                {
                                    return *rowArr[i];
                                }
    UT_PtrArray<utPtr>          &operator()(unsigned int i)
                                {
                                    return *rowArr(i);
                                }
    UT_PtrArray<utPtr>          &operator[](unsigned int i);
#endif

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

    // Return an element of the matrix, growing the matrix if necessary in
    // the non-const case.
    utPtr                       safeGet(unsigned i, unsigned j) const
                                {
                                    return (utPtr)matrix.safeGet(i, j);
                                }
    utPtr                       &safeGet(unsigned int i, unsigned int j)
                                {
                                    return (utPtr &)matrix.safeGet(i, j);
                                }

#if 0
Forget these for now - if someone really needs them, we can figure something out
    // 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_PtrArray<utPtr>    &row(unsigned int i) const {return *rowArr(i);}
    UT_PtrArray<utPtr>          &row(unsigned int i)       {return *rowArr(i);}
    UT_PtrArray<utPtr>          &col(unsigned int j) const;
#endif

    // 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 utPtr.
    int         find(utPtr t, unsigned int *m, unsigned int *n) const
                {
                    return matrix.find((const void *)t, m, n);
                }

    // 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_PtrArray 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 utPtr.
    int findRow(const UT_PtrArray<utPtr> &r, unsigned int s = 0) const
        {
            return matrix.findRow(r.getRawArray(), s);
        }
    int findCol(const UT_PtrArray<utPtr> &c, unsigned int s = 0) const
        {
            return matrix.findCol(c.getRawArray(), s);
        }

    // 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 matrix.rowSize(); }
    unsigned int        colSize(void) const     { return matrix.colSize(); }
    unsigned int        rows(void) const        { return matrix.rows(); }
    unsigned int        cols(void) const        { return matrix.cols(); }
    unsigned short      isEmpty(void) const     { return matrix.isEmpty(); }

    // 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)
                        {
                            matrix.resize(mSz, nSz, copyFlag);
                        }

    // 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 (*fcn)(utPtr t, void *d), void *d)
                        {
                            return matrix.apply((int (*)(void *, void*))fcn, d);
                        }

private:
    UT_PtrMatrixRaw             matrix;
};


#endif

---