Reference documentation for deal.II version Git aa2075a 2017-04-21 00:33:12 +0200
deal.II and the C++11 standard

std_cxx11

## Classes

class  IteratorRange< Iterator >

class  IteratorRange< Iterator >::IteratorOverIterators

## Functions

template<typename FunctionObjectType >

template<typename FunctionObjectType >

template<typename BaseIterator , typename Predicate >
IteratorRange< FilteredIterator< BaseIterator > > filter_iterators (IteratorRange< BaseIterator > i, const Predicate &p)

template<typename BaseIterator , typename Predicate , typename... Targs>
IteratorRange< typename internal::FilteredIterator::NestFilteredIterators< BaseIterator, std::tuple< Predicate, Targs...> >::type > filter_iterators (IteratorRange< BaseIterator > i, const Predicate &p, const Targs...args)

## Cell iterator functions returning ranges of iterators

IteratorRange< cell_iterator > DoFHandler< dim, spacedim >::cell_iterators () const

IteratorRange< active_cell_iterator > DoFHandler< dim, spacedim >::active_cell_iterators () const

IteratorRange< level_cell_iterator > DoFHandler< dim, spacedim >::mg_cell_iterators () const

IteratorRange< cell_iterator > DoFHandler< dim, spacedim >::cell_iterators_on_level (const unsigned int level) const

IteratorRange< active_cell_iterator > DoFHandler< dim, spacedim >::active_cell_iterators_on_level (const unsigned int level) const

IteratorRange< level_cell_iterator > DoFHandler< dim, spacedim >::mg_cell_iterators_on_level (const unsigned int level) const

## Cell iterator functions returning ranges of iterators

IteratorRange< cell_iterator > Triangulation< dim, spacedim >::cell_iterators () const

IteratorRange< active_cell_iterator > Triangulation< dim, spacedim >::active_cell_iterators () const

IteratorRange< cell_iterator > Triangulation< dim, spacedim >::cell_iterators_on_level (const unsigned int level) const

IteratorRange< active_cell_iterator > Triangulation< dim, spacedim >::active_cell_iterators_on_level (const unsigned int level) const

## Cell iterator functions returning ranges of iterators

IteratorRange< cell_iterator > hp::DoFHandler< dim, spacedim >::cell_iterators () const

IteratorRange< active_cell_iterator > hp::DoFHandler< dim, spacedim >::active_cell_iterators () const

IteratorRange< cell_iterator > hp::DoFHandler< dim, spacedim >::cell_iterators_on_level (const unsigned int level) const

IteratorRange< active_cell_iterator > hp::DoFHandler< dim, spacedim >::active_cell_iterators_on_level (const unsigned int level) const

## Detailed Description

At present, deal.II only requires a compiler that conforms to the C++98 standard and does not rely on compilers to either provide the features introduced in C++03 or C++11

That said, deal.II interfaces with C++11 in several ways as outlined below.

### Use of C++11 classes and substitution by BOOST

deal.II makes use of many of the classes that were only added as part of C++11. This includes std::shared_ptr, std::function, std::bind, std::tuple and a number of others. Because we do not assume that the compiler actually supports C++11, there needs to be a way to ensure that these classes are available also for pre-C++11 compilers. This is done using the following approach:

• We create a namespace std_cxx11.
• If the compiler supports C++11, we import the relevant classes and functions into this namespace using statements such as
namespace std_cxx11 { using std::shared_ptr; }
• If the compiler does not support C++11, if its support for C++11 is incomplete, or if it is buggy, then we use as a fallback the corresponding classes and functions provided by the BOOST library through statements such as
namespace std_cxx11 { using boost::shared_ptr; }

Consequently, namespace std_cxx11 contains all of the symbols we require. The classes that can be used this way are obviously a subset of the intersection between C++11 and what BOOST provides.

### Support for C++11 range-based for loops

C++11 provides many new core language features, such as rvalue references and move semantics, initialized lists, tuples, variadic templates and others. For a complete list, see http://en.wikipedia.org/wiki/C++11 . We can not use most of these in deal.II itself because we cannot rely on compilers supporting them.

However, this does not preclude users from using such features in their own applications if they can be reasonably sure that the compilers on all of the systems they will work on do support C++11. An example are automatically typed variables.

deal.II does provide some features that make programming simpler when using C++11. This is true, in particular, for range-based for loops. deal.II-based codes often have many loops of the kind

Triangulation<dim> triangulation;
...
cell = triangulation.begin_active(),
endc = triangulation.end();
for (; cell!=endc; ++cell)
cell->set_refine_flag();

Using C++11's range-based for loops, you can now write this as follows:

Triangulation<dim> triangulation;
...
for (auto cell : triangulation.active_cell_iterators())
cell->set_refine_flag();

This relies on functions such as Triangulation::active_cell_iterators(), and equivalents in the DoF handler classes, DoFHandler::active_cell_iterators(), hp::DoFHandler::active_cell_iterators(). There are variants of these functions that provide iterator ranges for all cells (not just the active ones) and for cells on individual levels.

### Things that are only enabled if your compiler supports C++11

There is a small number of places inside deal.II where we allow ourselves the use of C++11 because it makes things so much simpler. These features are simply not available if your compiler does not support C++11, but this does not affect the usability of the remainder of deal.II.

Specifically, these places are:

## Function Documentation

template<typename FunctionObjectType >
inline

Overload of the new_thread() function for objects that can be called like a function object without arguments. In particular, this function allows calling Threads::new_thread() with either objects that result from using std::bind, or using lambda functions. For example, this function is called when writing code such as

do_this();
then_do_that();
return 42;
});

Here, we run the sequence of functions do_this() and then_do_that() on a separate thread, by making the lambda function declared here the function to execute on the thread. The lambda function then returns 42 (which is a bit pointless here, but it could of course be some computed number), and this is going to be the returned value you can later retrieve via thread.return_value() once the thread (i.e., the body of the lambda function) has completed.

Note
Every lambda function (or whatever else it is you pass to the new_thread() function here, for example the result of a std::bind() expression) has a return type and consequently returns an object of this type. This type can be inferred using the C++11 decltype statement used in the declaration of this function, and it is then used as the template argument of the Threads::Thread object returned by the current function. In the example above, because the lambda function returns 42 (which in C++ has data type int), the inferred type is int and the task object will have type Task<int>. In other words, it is not necessary to explicitly specify in user code what that return type of the lambda or std::bind expression will be, though it is possible to explicitly do so by (entirely equivalently) writing
do_this();
then_do_that();
return 42;
});
In practice, the lambda functions you will pass to new_thread() will of course typically be more complicated. In particular, they will likely capture variables from the surrounding context and use them within the lambda. See https://en.wikipedia.org/wiki/Anonymous_function#C.2B.2B_.28since_C.2B.2B11.29 for more on how lambda functions work.
If you pass a lambda function as an argument to the current function that captures a variable by reference, or if you use a std::bind that binds a function argument to a reference variable using std::ref() or std::cref(), then obviously you can only do this if the variables you reference or capture have a lifetime that extends at least until the time where the thread finishes.

Definition at line 1816 of file thread_management.h.

template<typename FunctionObjectType >
inline

Overload of the new_task function for objects that can be called like a function object without arguments. In particular, this function allows calling Threads::new_task() with either objects that result from using std::bind, or using lambda functions. For example, this function is called when writing code such as

do_this();
then_do_that();
return 42;
});

Here, we schedule the call to the sequence of functions do_this() and then_do_that() on a separate task, by making the lambda function declared here the function to execute on the task. The lambda function then returns 42 (which is a bit pointless here, but it could of course be some computed number), and this is going to be the returned value you can later retrieve via task.return_value() once the task (i.e., the body of the lambda function) has completed.

Note
Every lambda function (or whatever else it is you pass to the new_task() function here, for example the result of a std::bind() expression) has a return type and consequently returns an object of this type. This type can be inferred using the C++11 decltype statement used in the declaration of this function, and it is then used as the template argument of the Threads::Task object returned by the current function. In the example above, because the lambda function returns 42 (which in C++ has data type int), the inferred type is int and the task object will have type Task<int>. In other words, it is not necessary to explicitly specify in user code what that return type of the lambda or std::bind expression will be, though it is possible to explicitly do so by (entirely equivalently) writing
do_this();
then_do_that();
return 42;
});
In practice, the lambda functions you will pass to new_task() will of course typically be more complicated. In particular, they will likely capture variables from the surrounding context and use them within the lambda. See https://en.wikipedia.org/wiki/Anonymous_function#C.2B.2B_.28since_C.2B.2B11.29 for more on how lambda functions work.
If you pass a lambda function as an argument to the current function that captures a variable by reference, or if you use a std::bind that binds a function argument to a reference variable using std::ref() or std::cref(), then obviously you can only do this if the variables you reference or capture have a lifetime that extends at least until the time where the task finishes.

Definition at line 3280 of file thread_management.h.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::cell_iterator > DoFHandler< dim, spacedim >::cell_iterators ( ) const

Return an iterator range that contains all cells (active or not) that make up this DoFHandler. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Returns
The half open range [this->begin(), this->end())

Definition at line 825 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::active_cell_iterator > DoFHandler< dim, spacedim >::active_cell_iterators ( ) const

Return an iterator range that contains all active cells that make up this DoFHandler. Such a range is useful to initialize range-based for loops as supported by C++11, see also C++11 standard.

Range-based for loops are useful in that they require much less code than traditional loops (see here for a discussion of how they work). An example is that without range-based for loops, one often writes code such as the following:

DoFHandler<dim> dof_handler;
...
cell = dof_handler.begin_active(),
endc = dof_handler.end();
for (; cell!=endc; ++cell)
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}

Using C++11's range-based for loops, this is now entirely equivalent to the following:

DoFHandler<dim> dof_handler;
...
for (auto cell : dof_handler.active_cell_iterators())
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}

To use this feature, you need a compiler that supports C++11.

Returns
The half open range [this->begin_active(), this->end())

Definition at line 835 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::level_cell_iterator > DoFHandler< dim, spacedim >::mg_cell_iterators ( ) const

Return an iterator range that contains all cells (active or not) that make up this DoFHandler in their level-cell form. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Returns
The half open range [this->begin_mg(), this->end_mg())

Definition at line 846 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::cell_iterator > DoFHandler< dim, spacedim >::cell_iterators_on_level ( const unsigned int level ) const

Return an iterator range that contains all cells (active or not) that make up the given level of this DoFHandler. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Parameters
 [in] level A given level in the refinement hierarchy of this triangulation.
Returns
The half open range [this->begin(level), this->end(level))
Precondition
level must be less than this->n_levels().

Definition at line 858 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::active_cell_iterator > DoFHandler< dim, spacedim >::active_cell_iterators_on_level ( const unsigned int level ) const

Return an iterator range that contains all active cells that make up the given level of this DoFHandler. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Parameters
 [in] level A given level in the refinement hierarchy of this triangulation.
Returns
The half open range [this->begin_active(level), this->end(level))
Precondition
level must be less than this->n_levels().

Definition at line 869 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::level_cell_iterator > DoFHandler< dim, spacedim >::mg_cell_iterators_on_level ( const unsigned int level ) const

Return an iterator range that contains all cells (active or not) that make up the given level of this DoFHandler in their level-cell form. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Parameters
 [in] level A given level in the refinement hierarchy of this triangulation.
Returns
The half open range [this->begin_mg(level), this->end_mg(level))
Precondition
level must be less than this->n_levels().

Definition at line 880 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename Triangulation< dim, spacedim >::cell_iterator > Triangulation< dim, spacedim >::cell_iterators ( ) const

Return an iterator range that contains all cells (active or not) that make up this triangulation. Such a range is useful to initialize range- based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Returns
The half open range [this->begin(), this->end())

Definition at line 10764 of file tria.cc.

template<int dim, int spacedim>
 IteratorRange< typename Triangulation< dim, spacedim >::active_cell_iterator > Triangulation< dim, spacedim >::active_cell_iterators ( ) const

Return an iterator range that contains all active cells that make up this triangulation. Such a range is useful to initialize range-based for loops as supported by C++11, see also C++11 standard.

Range-based for loops are useful in that they require much less code than traditional loops (see here for a discussion of how they work). An example is that without range-based for loops, one often writes code such as the following (assuming for a moment that our goal is setting the user flag on every active cell):

Triangulation<dim> triangulation;
...
cell = triangulation.begin_active(),
endc = triangulation.end();
for (; cell!=endc; ++cell)
cell->set_user_flag();

Using C++11's range-based for loops, this is now entirely equivalent to the following:

Triangulation<dim> triangulation;
...
for (auto cell : triangulation.active_cell_iterators())
cell->set_user_flag();

To use this feature, you need a compiler that supports C++11.

Returns
The half open range [this->begin_active(), this->end())

Definition at line 10774 of file tria.cc.

template<int dim, int spacedim>
 IteratorRange< typename Triangulation< dim, spacedim >::cell_iterator > Triangulation< dim, spacedim >::cell_iterators_on_level ( const unsigned int level ) const

Return an iterator range that contains all cells (active or not) that make up the given level of this triangulation. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Parameters
 [in] level A given level in the refinement hierarchy of this triangulation.
Returns
The half open range [this->begin(level), this->end(level))
Precondition
level must be less than this->n_levels().

Definition at line 10785 of file tria.cc.

template<int dim, int spacedim>
 IteratorRange< typename Triangulation< dim, spacedim >::active_cell_iterator > Triangulation< dim, spacedim >::active_cell_iterators_on_level ( const unsigned int level ) const

Return an iterator range that contains all active cells that make up the given level of this triangulation. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Parameters
 [in] level A given level in the refinement hierarchy of this triangulation.
Returns
The half open range [this->begin_active(level), this->end(level))
Precondition
level must be less than this->n_levels().

Definition at line 10796 of file tria.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::cell_iterator > DoFHandler< dim, spacedim >::cell_iterators ( ) const

Return an iterator range that contains all cells (active or not) that make up this DoFHandler. Such a range is useful to initialize range- based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Returns
The half open range [this->begin(), this->end())

Definition at line 1767 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::active_cell_iterator > DoFHandler< dim, spacedim >::active_cell_iterators ( ) const

Return an iterator range that contains all active cells that make up this DoFHandler. Such a range is useful to initialize range-based for loops as supported by C++11, see also C++11 standard.

Range-based for loops are useful in that they require much less code than traditional loops (see here for a discussion of how they work). An example is that without range-based for loops, one often writes code such as the following:

DoFHandler<dim> dof_handler;
...
cell = dof_handler.begin_active(),
endc = dof_handler.end();
for (; cell!=endc; ++cell)
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}

Using C++11's range-based for loops, this is now entirely equivalent to the following:

DoFHandler<dim> dof_handler;
...
for (auto cell : dof_handler.active_cell_iterators())
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}

To use this feature, you need a compiler that supports C++11.

Returns
The half open range [this->begin_active(), this->end())

Definition at line 1777 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::cell_iterator > DoFHandler< dim, spacedim >::cell_iterators_on_level ( const unsigned int level ) const

Return an iterator range that contains all cells (active or not) that make up the given level of this DoFHandler. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Parameters
 [in] level A given level in the refinement hierarchy of this triangulation.
Returns
The half open range [this->begin(level), this->end(level))
Precondition
level must be less than this->n_levels().

Definition at line 1788 of file dof_handler.cc.

template<int dim, int spacedim>
 IteratorRange< typename DoFHandler< dim, spacedim >::active_cell_iterator > DoFHandler< dim, spacedim >::active_cell_iterators_on_level ( const unsigned int level ) const

Return an iterator range that contains all active cells that make up the given level of this DoFHandler. Such a range is useful to initialize range-based for loops as supported by C++11. See the example in the documentation of active_cell_iterators().

Parameters
 [in] level A given level in the refinement hierarchy of this triangulation.
Returns
The half open range [this->begin_active(level), this->end(level))
Precondition
level must be less than this->n_levels().

Definition at line 1799 of file dof_handler.cc.

template<typename BaseIterator , typename Predicate >
 IteratorRange< FilteredIterator< BaseIterator > > filter_iterators ( IteratorRange< BaseIterator > i, const Predicate & p )
related

Filter the given range of iterators using a Predicate. This allows to replace:

DoFHandler<dim> dof_handler;
...
for (auto cell : dof_handler.active_cell_iterators())
{
if (cell->is_locally_owned())
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}
}

by:

DoFHandler<dim> dof_handler;
...
for (auto cell : filter_iterators(dof_handler.active_cell_iterators(),
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}

Definition at line 837 of file filtered_iterator.h.

template<typename BaseIterator , typename Predicate , typename... Targs>
 IteratorRange< typename internal::FilteredIterator::NestFilteredIterators< BaseIterator, std::tuple< Predicate, Targs...> >::type > filter_iterators ( IteratorRange< BaseIterator > i, const Predicate & p, const Targs... args )
related

Filter the given range of iterators through an arbitrary number of Predicates. This allows to replace:

DoFHandler<dim> dof_handler;
...
for (auto cell : dof_handler.active_cell_iterators())
{
if (cell->is_locally_owned())
{
if (cell->at_boundary())
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}
}
}

by:

DoFHandler<dim> dof_handler;
...
for (auto cell : filter_iterators(dof_handler.active_cell_iterators(),
{
fe_values.reinit (cell);
...do the local integration on 'cell'...;
}

Definition at line 886 of file filtered_iterator.h.