Qhull C++ -- C++ interface to Qhull

Copyright (c) 2009-2015, C.B. Barber

This draft document records some of the design decisions for Qhull C++. Convert it to HTML by road-faq.xsl from road-faq. Please send comments and suggestions to bradb@shore.net

Help
.
Qhull's collection APIs are modeled on Qt's collection API (QList, QVector, QHash) w/o QT_STRICT_ITERATORS. They support STL and Qt programming.

Some of Qhull's collection classes derive from STL classes. If so, please avoid additional STL functions and operators added by inheritance. These collection classes may be rewritten to derive from Qt classes instead. See Road's .

Qhull's collection API (where applicable). For documentation, see Qt's QList, QMap, QListIterator, QMapIterator, QMutableListIterator, and QMutableMapIterator
  • STL types [list, qlinkedlist, qlist, qvector, vector] -- const_iterator, iterator
  • STL types describing iterators [list, qlinkedlist, qlist, qvector, vector] -- const_pointer, const_reference, difference_type, pointer, reference, size_type, value_type. Pointer and reference types not defined if unavailable (not needed for <algorithm>)
  • const_iterator, iterator types -- difference_type, iterator_category, pointer, reference, value_type
  • Qt types [qlinkedlist, qlist, qvector] -- ConstIterator, Iterator, QhullclassIterator, MutableQhullclassIterator. Qt's foreach requires const_iterator.
  • Types for sets/maps [hash_map, QHash] -- key_compare, key_type, mapped_type
  • Constructor -- default constructor, copy constructor, assignment operator, destructor
  • Conversion -- to/from/as corresponding C, STL, and Qt constructs. Include toQList and toStdVector (may be filtered, e.g., QhullFacetSet). Do not define fromStdList and fromQList if container is not reference counted (i.e., acts like a value)
  • Get/set -- configuration options for class
  • STL-style iterator - begin, constBegin, constEnd, end, key, value, =, *, [], ->, ++, --, +, -, ==, !=, <, <=, >, >=, const_iterator(iterator), iterator COMPARE const_iterator. An iterator is an abstraction of a pointer. It is not aware of its container.
  • Java-style iterator [qiterator.h] - countRemaining, findNext, findPrevious, hasNext, hasPrevious, next, peekNext, peekPrevious, previous, toBack, toFront, = Coordinates
  • Mutable Java-style iterator adds - insert, remove, setValue, value
  • Element access -- back, first, front, last
  • Element access w/ index -- [], at (const& only), constData, data, mid, value
  • Read-only - (int)count, empty, isEmpty, (size_t)size. Count() and size() may be filtered. If so, they may be zero when !empty().
  • Read-only for sets/maps - capacity, key, keys, reserve, resize, values
  • Operator - ==, !=, +, +=, <<
  • Read-write -- append, clear, erase, insert, move, prepend, pop_back, pop_front, push_back, push_front, removeAll, removeAt, removeFirst, removeLast, replace, swap, takeAt, takeFirst, takeLast
  • Read-write for sets/maps -- insertMulti, squeeze, take, unite
  • Search -- contains(const T &), count(const T &), indexOf, lastIndexOf
  • Search for sets/maps -- constFind, lowerBound, upperBound
  • Stream I/O -- stream <<
STL list and vector -- For unfiltered access to each element.
  • Apache: Creating your own containers -- requirements for STL containers. Iterators should define the types from 'iterator_traits'.
  • STL types -- allocator_type, const_iterator, const_pointer, const_reference, const_reverse_iterator, difference_type, iterator, iterator_category, pointer, reference, reverse_iterator, size_type, value_type
  • STL constructors -- MyType(), MyType(count), MyType(count, value), MyType(first, last), MyType(MyType&),
  • STL getter/setters -- at (random_access only), back, begin, capacity, end, front, rbegin, rend, size, max_size
  • STL predicates -- empty
  • STL iterator types -- const_pointer, const_reference, difference_type, iterator_category, pointer, reference, value_type
  • STL iterator operators -- *, -<, ++, --, +=, -=, +, -, [], ==, !=, <, >, >=, <=
  • STL operators -- =, [] (random_access only), ==, !=, <, >, <=, >=
  • STL modifiers -- assign, clear, erase, insert, pop_back, push_back, reserve, resize, swap
Qt Qlist -- For unfiltered access to each element
  • Additional Qt types -- ConstIterator, Iterator, QListIterator, QMutableListIterator
  • Additional Qt get/set -- constBegin, constEnd, count, first, last, value (random_access only)
  • Additional Qt predicates -- isEmpty
  • Additional Qt -- mid (random_access only)
  • Additional Qt search -- contains, count(T&), indexOf (random_access only), lastIndeOf (random_access only)
  • Additional Qt modifiers -- append, insert(index,value) (random_access only), move (random_access only), pop_front, prepend, push_front, removeAll, removeAt (random_access only), removeFirst, removeLast, replace, swap by index, takeAt, takeFirst, takeLast
  • Additional Qt operators -- +, <<, +=, stream << and >>
  • Unsupported types by Qt -- allocator_type, const_reverse_iterator, reverse_iterator
  • Unsupported accessors by Qt -- max_size, rbegin, rend
  • Unsupported constructors by Qt -- multi-value constructors
  • unsupported modifiers by Qt -- assign, muli-value inserts, STL's swaps
STL map and Qt QMap. These use nearly the same API as list and vector classes. They add the following.
  • STL types -- key_compare, key_type, mapped_type
  • STL search -- equal_range, find, lower_bound, upper_bound
  • Qt removes -- equal_range, key_compare
  • Qt renames -- lowerBound, upperBound
  • Qt adds -- constFind, insertMulti, key, keys, take, uniqueKeys, unite, values
  • Not applicable to map and QMap -- at, back, pop_back, pop_front, push_back, push_front, swap
  • Not applicable to QMap -- append, first, last, lastIndexOf, mid, move, prepend, removeAll, removeAt, removeFirst, removeLast, replace, squeeze, takeAt, takeFirst, takeLast
  • Not applicable to map -- assign
Qt QHash. STL extensions provide similar classes, e.g., Microsoft's stdext::hash_set. THey are nearly the same as QMap
  • Not applicable to Qhash -- lowerBound, unite, upperBound,
  • Qt adds -- squeeze
  • check... -- Throw error on failure
  • try... -- Return false on failure. Do not throw errors.
  • ...Temporarily -- lifetime depends on source. e.g., toByteArrayTemporarily
  • ...p -- indicates pointer-to.
  • end... -- points to one beyond the last available
  • private functions -- No syntactic indication. They may become public later on.
  • Error messages -- Preceed error messages with the name of the class throwing the error (e.g. "ClassName: ..."). If this is an internal error, use "ClassName inconsistent: ..."
  • parameter order -- qhRunId, dimension, coordinates, count.
  • toClass -- Convert into a Class object (makes a deep copy)
  • qRunId -- Requires Qh installed. Some routines allow 0 for limited info (e.g., operator<<)
  • Disable methods in derived classes -- If the default constructor, copy constructor, or copy assignment is disabled, it should be also disabled in derived classes (better error messages).
  • Constructor order -- default constructor, other constructors, copy constructor, copy assignment, destructor