UT/UT_Vector3Array.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
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        Utility Library (C++)
 *
 * COMMENTS:
 */

#ifndef __UT_Vector3Array_h__
#define __UT_Vector3Array_h__

#include "UT_API.h"
#include <string.h>
#include <malloc.h>
#include "UT_Assert.h"
#include "UT_Vector3.h"

class UT_API UT_Vector3Array {
public:
    /// Trivial constructor and destructor:
    explicit UT_Vector3Array(unsigned int sz = 0) 
    : arrSize(sz), nbrEntries(0)
    {
        arr = (sz) ? (UT_Vector3*)calloc(sizeof(UT_Vector3),sz) : 0;
    }
    UT_Vector3Array(unsigned int sz, unsigned int count);

    virtual ~UT_Vector3Array(void);

    /// Copy constructor that uses operator '=' to assign each of a's 
    /// UT_Vector3 to this array.
    UT_Vector3Array(const UT_Vector3Array &a);

    /// Append an element to the current entries and return its index in the
    /// array, or insert the element at a specified position; if necessary,
    /// insert() grows the array to accommodate the element. The insert
    /// methods use the assignment operator '=' to place the UT_Vector3 into 
    /// the right spot; be aware that '=' works differently on objects and 
    /// pointers.  If UT_Vector3 is an object that uses the default '=' 
    /// operator, the result of insert() will be a shallow copy of t, and 
    /// not t itself.  So, if what you really want to do is create a new 
    /// object inside the array, first grow the array to a good size, 
    /// then create your object as follows:
    ///         UT_Vector3Array<GeoPoint>  arr(3);
    ///         GeoPoint              *p = new (&arr[0]) GeoPoint(....);
    /// Use the subscript operators instead of insert() if you are appending
    /// to the array, or if  you don't mind overwriting the element already 
    /// inserted at the given index.
    unsigned int        append(void)            { return insert(nbrEntries); }
    unsigned int        append(const UT_Vector3& t);
    unsigned int        insert(unsigned int idx);
    unsigned int        insert(const UT_Vector3& t, unsigned int  idx);

    /// Takes another pointer array and concatenate it onto my end
    unsigned int        concat(const UT_Vector3Array &a);

    /// Insert an element "count" times at the given index. Return the index.
    unsigned  int       multipleInsert(unsigned int idx, unsigned int count);

    /// Two more insert() methods that check for duplicates in the array, 
    /// assuming that the array is sorted.
    unsigned int        append(const UT_Vector3& t,
                               int (*compare)(const UT_Vector3 *t1,
                                              const UT_Vector3 *t2)
                              );
    unsigned int        insert(const UT_Vector3& t,
                               unsigned int  index,
                               int (*compare)(const UT_Vector3 *t1,
                                              const UT_Vector3 *t2)
                              );
    
    /// An alias for unique element insertion at a certain index. Also used by
    /// the other insertion methods.
    unsigned int         insertAt(const UT_Vector3 &t, unsigned int idx);

    /// Remove one element from the array given the element itself or its 
    /// position in the list, and fill the gap by shifting the elements down
    /// by one position. Both methods return the index if successful, 
    /// and (int)-1 if the element is not found. The method that takes 
    /// an index argument does not return a reference to the object for safety
    /// purposes: if UT_Vector3 is an object, then when the array is shrunk the 
    /// memory previously used by UT_Vector3 will be overwritten by the next
    /// element. 
    // @{
    int         remove(const UT_Vector3& t);
    int         remove(unsigned int aindex)
                        {
                            return (aindex < nbrEntries) 
                                ? removeAt(aindex) : -1;
                        }
    // @}

    /// More remove() methods that search for the object to be removed 
    /// with a user-defined comparison function. These methods assume the
    /// array is sorted. t1 and t2 must be pointers to UT_Vector3. The methods
    /// return the last (removed) object index.
    int         remove(const UT_Vector3& t,
                       int (*compare)(const UT_Vector3 *t1,
                                      const UT_Vector3 *t2));
    /// Alias for remove (unsigned int index), to be consistent with 
    /// rest of the UT_xxxArray classes
    int         removeIndex(unsigned int aindex)
                        { return remove(aindex); }
    /// Move howMany objects starting at index srcIndex to destIndex;
    /// Method returns 0 if OK, -1 if overflow.
    int                 shift(unsigned int srcIdx,
                              unsigned int destIdx,
                              unsigned int howMany);
    /// Performs a cyclical shift of the entries by howMany
    void                cycle(int howMany);

    // Quickly set the array to a single value
    void                constant(fpreal v=0);
    void                constant(const UT_Vector3 &v);

    /// Search for t in one of two ways: linearly using the '==' operator, or
    /// binary using the function specified in the parameter list respectively.
    /// find() returns the index of the matching element or (int)-1.
    /// Parameter s indicates the index to start the search at.
    int          find(const UT_Vector3 &t, unsigned int s = 0) const;
    int          find(const UT_Vector3 &t, 
                      int (*compare)(const UT_Vector3 *t1,
                                     const UT_Vector3 *t2),
                      unsigned int s = 0) const;

    /// Search for 'any' until compare() returns 0 and return the index;
    /// otherwise return -1. The array is assumed to be sorted.
    int          find(const void *any, 
                      int (*compare)(const UT_Vector3 *t1,
                                     const UT_Vector3 *t2),
                      unsigned int s = 0) const;

    /// The fastest search possible, which does pointer arithmetic to find the 
    /// index of the element. WARNING: index() does no out-of-bounds checking.
    int              index(const UT_Vector3 &t) const { return &t - arr; }
    int          safeIndex(const UT_Vector3 &t) const 
                 { 
                     return (&t >= arr && (&t - arr < (int)nbrEntries))
                             ?  &t - arr : -1;
                 }

    /// Sort the array using a comparison function that you must provide. t1
    /// and t2 are pointers to UT_Vector3.
    void                sort(int (*compare)(const UT_Vector3 *t1,
                                            const UT_Vector3 *t2));

    /// 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 sz, unsigned short copyFlag=1);
    void                resizeIfNeeded(uint sz, bool copyFlag=true)
                        {
                            if (sz > capacity())
                                resize(sz, copyFlag);
                        }

    /// Query the allocated length of the array or the number of elements
    /// in the array: capacity() >= entries().
    uint        capacity(void) const   { return arrSize;       }
    int64       getMemoryUsage() const { return capacity()*sizeof(UT_Vector3);}
    uint        entries(void) const    { return nbrEntries;    }
    bool        isEmpty(void) const    { return nbrEntries==0; }

    /// Set the number of entries. Normally, you should not have to use it.
    void         entries(unsigned int ne)       { nbrEntries = ne; }

    /// Assign array a to this array by copying each of a's UT_Vector3 with the
    /// '=' operator.
    UT_Vector3Array     &operator=(const UT_Vector3Array &a);

    /// Compare two array and return 1 if they are equal and 0 otherwise.
    /// Two UT_Vector3 are checked against each other using operator '==' or
    /// compare() respectively. Arrays of different size but equal number of
    /// entries are checked for member-wise equality.
    /// t1 and t2 must point to UT_Vector3.
    int                 operator==(const UT_Vector3Array &a) const;
    int                 isEqual(const UT_Vector3Array &a,
                                int (*compare)(const UT_Vector3 *t1,
                                               const UT_Vector3 *t2)) const;
     
    /// Subscript operators. operator() does NOT do any bound checking, while
    /// the non-const operator[] grows the array to accommodate the given index
    UT_Vector3          &operator()(unsigned int i)
                        {
                            UT_ASSERT_P(i < nbrEntries);
                            return arr[i];
                        }
    const UT_Vector3    &operator()(unsigned int i) const
                        {
                            UT_ASSERT_P(i < nbrEntries);
                            return arr[i];
                        }
    UT_Vector3          &operator[](unsigned int i);
    const UT_Vector3    &operator[](unsigned int i) const
                        {
                            UT_ASSERT_P(i < nbrEntries);
                            return arr[i];
                        }
    UT_Vector3          &last()
                        {
                            UT_ASSERT_P(nbrEntries);
                            return arr[nbrEntries-1];
                        }
    UT_Vector3          last() const
                        {
                            return nbrEntries ? arr[nbrEntries-1]
                                              : UT_Vector3();
                        }

    /// Apply a user-defined function to each element of the array 
    /// as int as the function returns zero. If applyFct returns
    /// 1, apply() stops traversing the list and returns the current
    /// index; otherwise, apply() returns the number of entries.
    unsigned int       apply(int (*applyFct)(UT_Vector3 &t, void *d), void *d);

    const UT_Vector3  *getRawArray(void) const  { return arr; }
    UT_Vector3        *array(void)              { return arr; }

private:
    /// Pointer to a list of elements of type UT_Vector3:
    UT_Vector3          *arr;

    /// The number of elements we have allocated space for versus the actual
    /// number of entries in the array:
    unsigned int         arrSize;
    unsigned int         nbrEntries;

    /// The guts of the remove() methods.
    int                 removeAt(unsigned int index);
};

#endif

---