RoseReal3DArray Class

Overview

The RoseReal3DArray class is a lightweight, resizable array of floating point triples, such as lists of XYZ points and 3D direction vectors. It contains a simple array, but access and update methods work on a sequence of three numbers at a time. It also has overloads that work with RosePoint and RoseDirection. There is also a 2D version.

append()

void append(const double vec[3]);
void append(double x, double y, double z);
void append(const RosePoint& pt);
void append(const RoseDirection& dir);

The append() function increments the size of the array and adds the given value triple as the last element. The function has overloads that take an array of three values, three separate values, as well as references to point and direction objects.

RoseReal3DArray o1;

double d1[] = { 1,2,3 };
double d2[] = { 4,5,6 };
RosePoint p1 (10, 20, 30);

o1.append (d1);    
o1.append (d2);    
o1.append (p1);    
o1.append (100,101,102);

as_dir()

RoseDirection& as_dir (unsigned i);
const RoseDirection& as_dir (unsigned i) const;

The as_dir() function returns the value triple at a given index as a reference to a direction object. Constant and non-constant references are available. No copying is done, so the non-constant reference can be changed to update the value of the array. See as_point() for an example.

Because this is intended for use in tight graphics loops, no range checking is done on the index. Make sure that i is less than size() or you will get undefined behavior.

as_point()

RosePoint& as_point (unsigned i);
const RosePoint& as_point (unsigned i) const;

The as_point() function returns the value triple at a given index as a reference to a point object. Constant and non-constant references are available. No copying is done, so the non-constant reference can be changed to update the value of the array.

Because this is intended for use in tight graphics loops, no range checking is done on the index. Make sure that i is less than size() or you will get undefined behavior.

RoseReal3DArray o1;

o1.append (10, 20, 30);    
o1.append (40, 50, 60);    
o1.append (70, 80, 90);    
// array contains (10, 20, 30), (40, 50, 60), (70, 80, 90)

o1.as_point(0).x(97);
o1.as_point(0).y(98);
o1.as_point(0).z(99);
// array contains (97, 98, 99), (40, 50, 60), (70, 80, 90)


// This copies the (97, 98, 99)
RosePoint a_copy = o1.as_point(0);
a_copy.xyz(10,20,30);

// only the copy was changed
// array contains (97, 98, 99), (40, 50, 60), (70, 80, 90)

capacity()

unsigned capacity() const;
void capacity (unsigned newcap);

The capacity() function returns the number of triples that the memory buffer can hold without resizing. Functions like append() expand the capacity as needed. You can manually set the capacity to pre-allocate a buffer of a certain size. Set capacity to zero to deallocate buffer, otherwise this only expands capacity, never decreases it.

empty()

void empty();

The empty() function removes all elements by setting the size of the array to zero. The capacity of the array is not changed.

expand()

void expand (unsigned min_extra = 1);

The expand() function forces the capacity to increase by a certain number of triples.

get() / operator[]

double * operator[] (unsigned i);
const double * get (unsigned i) const;

The get() function and the index operator[] get the value triple at a given index. Both return pointer to double, which is the start of a three element array. No copying is done, the return value is a pointer into the raw data buffer. Use the get() function for read-only access because it returns a constant pointer. The index operator is not constant, so you can change the values in place.

Because this is intended for use in tight graphics loops, no range checking is done on the index. Make sure that i is less than size() or you will get undefined behavior.

The as_point() and as_dir() functions also get the value triple at a given index, but as a reference to a point or direction object.

RoseReal3DArray o1;

o1.append (10, 20, 30);    
o1.append (40, 50, 60);    
o1.append (70, 80, 90);    
// array contains (10, 20, 30), (40, 50, 60), (70, 80, 90)

// read-only access
double x, y, z;
x = o1.get(0)[0]; // is 10
y = o1.get(0)[1]; // is 20
z = o1.get(0)[2]; // is 30

const double * pt = o1.get(0);
x = pt[0]; // is 10
y = pt[1]; // is 20
z = pt[2]; // is 30


// read-write access using index operator
x = o1[0][0]; // is 10
y = o1[0][1]; // is 20
z = o1[0][2]; // is 30

// update values in place 
o1[0][0] = 97;
o1[0][1] = 98;
o1[0][2] = 99;
// array contains (97, 98, 99), (40, 50, 60), (70, 80, 90)

insert()

void insert(const double vec[3], unsigned i);
void insert(double x, double y, double z, unsigned i);
void insert(const RosePoint& pt, unsigned i);
void insert(const RoseDirection& dir, unsigned i);

The insert() function increments the size of the array and inserts the value triple at the given position. All values previously at that position and beyond are moved one index position higher. Inserting at position size() or higher is treated as an append().

The function has overloads that take an array of three values, three separate values, as well as references to point and direction objects.

put()

void put(const double vec[3], unsigned i);
void put(double x, double y, double z, unsigned i);
void put(const RosePoint& v, unsigned i);
void put(const RoseDirection& v, unsigned i);

The put() function changes a value triple at a given position. You can provide the replacement triple as an array of three values, three separate values, or as a reference to point or direction object. You can also change the value by updating through the index operator or the non-const references returned by the as_point() and as_dir() functions.

Because this is intended for use in tight graphics loops, no range checking is done on the index. Make sure that i is less than size() or you will get undefined behavior.

RoseReal3DArray o1;

o1.append (10, 20, 30);    
o1.append (40, 50, 60);    
o1.append (70, 80, 90);    
// array contains (10, 20, 30), (40, 50, 60), (70, 80, 90)

double foo[3] = { 200, 300, 400 };

o1.put(foo, 1);
// array contains (10, 20, 30), (200, 300, 400), (70, 80, 90)

o1.as_point(1).xyz(111, 222, 333);
// array contains (10, 20, 30), (111, 222, 333), (70, 80, 90)

o1[1][0] = 95;
o1[1][1] = 96;
o1[1][2] = 97;
// array contains (10, 20, 30), (95, 96, 97), (70, 80, 90)

remove()

void remove(unsigned i);

The remove() function removes the value triple at a given index, shifting all subsequent values triples and decrementing the size of the array.

size()

unsigned size() const;
void size(unsigned sz);

The size() function returns the number of value triples held by the array. Changing the size of the array will increase the capacity() if needed and set the size of the array to the new number of triples. You must initialize the values manually if you increase the size of the array.