AnotherFoxGuy/polyvox
1
0
Fork 0
Code Issues Pull Requests Activity

Added documentation for Array class.

Browse Source
This commit is contained in:
David Williams
2010-04-13 21:36:07 +00:00
parent 9e2f78a2f4
commit e1dde122a7
2 changed files with 108 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
library/PolyVoxCore/include/Array.h
View File

@@ -35,26 +35,71 @@ freely, subject to the following restrictions:
namespace PolyVox
{
///Provides an efficient implementation of a multidimensional array.
////////////////////////////////////////////////////////////////////////////////
/// While C++ provides one-dimensional arrays as a language feature, it does not
/// provide a simple and intuitive way of working with multidimensional arrays
/// whose sizes are specified at runtime. Such a construct is very useful within
/// the context of PolyVox, and this Array class provides such functionality
/// implemented via templates and partial specialisation.
///
/// The following code snippet illustrates the basic usage of the class by writing
/// a different value into each element:
///
/// \code
/// int width = 5;
/// int height = 10;
/// int depth = 20;
///
/// Array<3, int> myArray(ArraySizes(width)(height)(depth));
///
/// int ct = 1;
/// for(int z = 0; z < depth; z++)
/// {
/// for(int y = 0; y < height; y++)
/// {
/// for(int x = 0; x < width; x++)
/// {
/// myArray[x][y][z] = ct;
/// ct++;
/// }
/// }
/// }
/// \endcode
///
/// Although the constructor and resize() function both take the required dimensions
/// as an array of ints, note that the ArraySizes class can be used to build this
/// inline. This is a more convienient way of specifying these dimensions.
///
/// Note also that this class has a private assignment operator and copy constructor
/// in order to prevent copying. This is because a deep copy is a potentially slow
/// operation and can often be performed inadvertantly by functions such as std::swap,
/// while a shallow copy introduces confusion over memory ownership.
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
class Array
{
public:
///Constructor
Array<noOfDims, ElementType>();
///Constructor
Array<noOfDims, ElementType>(const uint32_t (&pDimensions)[noOfDims]);
///Destructor
~Array<noOfDims, ElementType>();
///Subarray access
SubArray<noOfDims-1, ElementType> operator[](uint32_t uIndex);
///Subarray access
const SubArray<noOfDims-1, ElementType> operator[](uint32_t uIndex) const;
///Gets the total number of elements in this array
uint32_t getNoOfElements(void) const;
///Gets a pointer to the first element of the array
ElementType* getRawData(void) const;
///Resize the array to the specified dimensions
void resize(const uint32_t (&pDimensions)[noOfDims]);
///Swaps the contents of this array with the one specified
void swap(Array<noOfDims, ElementType>& rhs);
private:

59
library/PolyVoxCore/include/Array.inl
View File

@@ -23,6 +23,10 @@ distribution.
namespace PolyVox
{
////////////////////////////////////////////////////////////////////////////////
/// Creates an empty array with no elements. You will have to call resize() on this
/// array befire it can be used.
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
Array<noOfDims, ElementType>::Array()
:m_pElements(0)
@@ -32,6 +36,12 @@ namespace PolyVox
{
}
////////////////////////////////////////////////////////////////////////////////
/// Creates an array with the specified dimensions.
/// \param pDimensions The dimensions of the array. You can also use the ArraySizes
/// class to construct this more easily.
/// \sa ArraySizes
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
Array<noOfDims, ElementType>::Array(const uint32_t (&pDimensions)[noOfDims])
:m_pElements(0)
@@ -42,12 +52,24 @@ namespace PolyVox
resize(pDimensions);
}
////////////////////////////////////////////////////////////////////////////////
/// Destroys the array and releases all owned memory.
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
Array<noOfDims, ElementType>::~Array()
{
deallocate();
}
////////////////////////////////////////////////////////////////////////////////
/// An N-dimensional array can be conceptually consists of N subarrays each of which
/// has N-1 dimensions. For example, a 3D array conceptually consists of three 2D
/// arrays. This operator is used to access the subarray at the specified index.
/// Crucially, the subarray defines a similar operator allowing them to be chained
/// together to convieniently access a particular element.
/// \param uIndex The zero-based index of the subarray to retrieve.
/// \return The requested SubArray
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
SubArray<noOfDims-1, ElementType> Array<noOfDims, ElementType>::operator[](uint32_t uIndex)
{
@@ -57,6 +79,15 @@ namespace PolyVox
m_pDimensions+1, m_pOffsets+1);
}
////////////////////////////////////////////////////////////////////////////////
/// An N-dimensional array can be conceptually consists of N subarrays each of which
/// has N-1 dimensions. For example, a 3D array conceptually consists of three 2D
/// arrays. This operator is used to access the subarray at the specified index.
/// Crucially, the subarray defines a similar operator allowing them to be chained
/// together to convieniently access a particular element.
/// \param uIndex The zero-based index of the subarray to retrieve.
/// \return The requested SubArray
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
const SubArray<noOfDims-1, ElementType> Array<noOfDims, ElementType>::operator[](uint32_t uIndex) const
{
@@ -66,18 +97,36 @@ namespace PolyVox
m_pDimensions+1, m_pOffsets+1);
}
////////////////////////////////////////////////////////////////////////////////
/// \return The number of elements in the array.
/// \sa getRawData()
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
uint32_t Array<noOfDims, ElementType>::getNoOfElements(void) const
{
return m_uNoOfElements;
}
////////////////////////////////////////////////////////////////////////////////
/// Sometimes it is useful to directly manipulate the underlying array without
/// going through this classes interface. Although this does not honour the principle
/// of encapsulation it can be done safely if you are careful and can sometimes be
/// useful. Use getNoOfElements() to determine how far you can safely write.
/// \return A pointer to the first element of the array
/// \sa getNoOfElements()
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
ElementType* Array<noOfDims, ElementType>::getRawData(void) const
{
return m_pElements;
}
////////////////////////////////////////////////////////////////////////////////
/// Please note that the existing contents of the array will be lost.
/// \param pDimensions The new dimensions of the array. You can also use the
/// ArraySizes class to specify this more easily.
/// \sa ArraySizes
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
void Array<noOfDims, ElementType>::resize(const uint32_t (&pDimensions)[noOfDims])
{
@@ -104,6 +153,12 @@ namespace PolyVox
m_pElements = new ElementType[m_uNoOfElements];
}
////////////////////////////////////////////////////////////////////////////////
/// Because this class does not have a public assignment operator or copy constructor
/// it cnnot be used with the STL swap() function. This function provides an efficient
/// implementation of that feature.
/// \param rhs The array to swap this object with.
////////////////////////////////////////////////////////////////////////////////
template <uint32_t noOfDims, typename ElementType>
void Array<noOfDims, ElementType>::swap(Array<noOfDims, ElementType>& rhs)
{
@@ -158,7 +213,9 @@ namespace PolyVox
m_uNoOfElements = 0;
}
////////////////////////////////////////////////////////////////////////////////
//****************************************************************************//
// One dimensional specialisation begins here //
//****************************************************************************//
template <typename ElementType>
Array<1, ElementType>::Array()