namespace fcppt
{
namespace container
{
/// Contains fcppt::container::grid::object and helper types/functions for it.
namespace grid
{
}
}
}

/**
\defgroup fcpptcontainergrid fcppt.container.grid
\ingroup fcpptcontainer
\brief A simple n-dimensional array

<table id="toc">
<tr>
<td>

<ul>
	<li>\ref fcpptcontainergrid_introduction</li>
	<li>\ref fcpptcontainergrid_init</li>
	<li>\ref fcpptcontainergrid_ranges</li>
	<li>\ref fcpptcontainergrid_layout</li>
	<li>\ref fcpptcontainergrid_resizing</li>
</ul>

</td>
</tr>
</table>

\section fcpptcontainergrid_introduction Introduction

fcppt::container::grid::object is a simple multi-dimensional array similar to
<a href="http://www.boost.org/doc/libs/1_48_0/libs/multi_array/doc/index.html">boost::multi_array</a>.
Let's first take a look at how to use a simple three dimensional grid of ints.

\snippet container/grid.cpp grid_simple

Grid uses #fcppt::math::dim::object to specify its size and #fcppt::math::vector::object to obtain an element.

\section fcpptcontainergrid_init Initialization
There are three ways to initialize a grid:
<ul>
<li>Provide a value that will be copied into each cell.</li>
<li>Initialize each cell by calling a function with its position.</li>
<li>Leave the grid uninitialized, using #fcppt::no_init.</li>
</ul>
Here is a small example:
\snippet container/grid.cpp grid_init

\section fcpptcontainergrid_ranges Ranges

To conveniently iterate over a grid, two ranges are provided:
<ul>
<li>#fcppt::container::grid::pos_range</li> which
is a range over positions.
<li>#fcppt::container::grid::pos_ref_range which is a range over
positions paired with the elements of a grid.</li>
</ul>

Here is an example for pos ranges:

\snippet container/grid_range.cpp pos_range

Pos ref ranges can be used to iterate over a grid's positions and elements
simultaneously. Here is an example:

\snippet container/grid_range.cpp pos_ref_range

Additionally, you can iterate over sub ranges which are denoted by a pair of
#fcppt::container::grid::min and #fcppt::container::grid::sup. Here, <code>min</code> denotes the first
element in the range while <code>sup</code> is ''one past the end''. A range is
empty if at least one element of <code>min</code> is greater or equal to the
corresponding element in <code>sup</code>. It is often necessary to clamp
positions to a valid range that doesn't exceed the size of a grid.  There are
three functions for this: #fcppt::container::grid::clamped_min,
#fcppt::container::grid::clamped_sup and #fcppt::container::grid::clamped_sup_signed. An unsigned
<code>min</code> doesn't need to be clamped. Here is an example:

\snippet container/grid_range.cpp pos_ref_sub_range

\section fcpptcontainergrid_layout Layout

Internally, the grid uses a <code>std::vector</code> to linearly represent the
grid. The iterators returned by the grid are iterators over that internal
storage array, so they're not special in any way (other than begin
random-access). This also means that iteration is...
<ul>
<li>
...<em>linear</em> for <em>one-dimensional</em> grids (from left to right)
</li>
<li>
...<em>row-major</em> for <em>two-dimensional</em> grids; this means that
iteration begins at the top left with row 0, proceeds to the top right, then
goes to the right of row 2 and so on.

\image html grid_row_major.svg "Row-major iteration"
</li>
<li>
...<em>vertical-slice-major</em> for <em>three-dimensional</em> grids; this
means that iteration starts at the top left back (z=0) of the cube, then
iterates over all elements with z equal to zero, then starts at the top left
back (z=1) of the cube, and so on.
</li>
<li>...and so on in higher dimensions.</li>
</ul>

Here is an example:

\snippet container/grid_iteration.cpp grid_iteration

\section fcpptcontainergrid_resizing Resizing

To resize a grid, we can use #fcppt::container::grid::resize.
Here's an example:
\snippet container/grid.cpp grid_resize
*/
