component_mask.h

// ---------------------------------------------------------------------
//
// Copyright (C) 2009 - 2018 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii_fe_component_mask_h
#define dealii_fe_component_mask_h

#include <deal.II/base/config.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/memory_consumption.h>

#include <vector>
#include <iosfwd>

DEAL_II_NAMESPACE_OPEN



class ComponentMask
{
public:
  ComponentMask () = default;

  ComponentMask (const std::vector<bool> &component_mask);

  ComponentMask (const unsigned int n_components,
                 const bool         initializer);

  void set (const unsigned int index, const bool value);

  unsigned int size () const;

  bool operator[] (const unsigned int component_index) const;

  bool
  represents_n_components (const unsigned int n) const;

  unsigned int
  n_selected_components (const unsigned int overall_number_of_components = numbers::invalid_unsigned_int) const;

  unsigned int
  first_selected_component (const unsigned int overall_number_of_components = numbers::invalid_unsigned_int) const;

  bool
  represents_the_all_selected_mask () const;

  ComponentMask operator | (const ComponentMask &mask) const;

  ComponentMask operator & (const ComponentMask &mask) const;

  bool operator== (const ComponentMask &mask) const;

  bool operator!= (const ComponentMask &mask) const;

  std::size_t
  memory_consumption () const;

  DeclExceptionMsg (ExcNoComponentSelected,
                    "The number of selected components in a mask "
                    "must be greater than zero.");

private:
  std::vector<bool> component_mask;

  // make the output operator a friend so it can access
  // the component_mask array
  friend
  std::ostream &operator << (std::ostream &out,
                             const ComponentMask &mask);
};


std::ostream &operator << (std::ostream &out,
                           const ComponentMask &mask);


// -------------------- inline functions ---------------------

inline
ComponentMask::ComponentMask(const std::vector<bool> &component_mask)
  :
  component_mask (component_mask)
{}


inline
ComponentMask::ComponentMask(const unsigned int n_components,
                             const bool         initializer)
  :
  component_mask (n_components, initializer)
{}


inline
unsigned int
ComponentMask::size () const
{
  return component_mask.size();
}


inline
void
ComponentMask::set(const unsigned int index, const bool value)
{
  AssertIndexRange(index, component_mask.size());
  component_mask[index] = value;
}


inline
bool
ComponentMask::operator [](const unsigned int component_index) const
{
  // if the mask represents the all-component mask
  // then always return true
  if (component_mask.size() == 0)
    return true;
  else
    {
      // otherwise check the validity of the index and
      // return whatever is appropriate
      AssertIndexRange (component_index, component_mask.size());
      return component_mask[component_index];
    }
}


inline
bool
ComponentMask::represents_n_components(const unsigned int n) const
{
  return ((component_mask.size() == 0)
          ||
          (component_mask.size() == n));
}


inline
unsigned int
ComponentMask::n_selected_components(const unsigned int n) const
{
  if ((n != numbers::invalid_unsigned_int) && (size() > 0))
    AssertDimension (n, size());

  const unsigned int real_n = (n != numbers::invalid_unsigned_int
                               ?
                               n
                               :
                               size());
  if (component_mask.size() == 0)
    return real_n;
  else
    {
      AssertDimension (real_n, component_mask.size());
      unsigned int c = 0;
      for (unsigned int i=0; i<component_mask.size(); ++i)
        if (component_mask[i] == true)
          ++c;
      return c;
    }
}


inline
unsigned int
ComponentMask::first_selected_component(const unsigned int n) const
{
  if ((n != numbers::invalid_unsigned_int) && (size() > 0))
    AssertDimension (n, size());

  if (component_mask.size() == 0)
    return 0;
  else
    {
      for (unsigned int c=0; c<component_mask.size(); ++c)
        if (component_mask[c] == true)
          return c;

      Assert (false, ExcMessage ("No component is selected at all!"));
      return numbers::invalid_unsigned_int;
    }
}



inline
bool
ComponentMask::represents_the_all_selected_mask () const
{
  return (component_mask.size() == 0);
}



inline
ComponentMask
ComponentMask::operator | (const ComponentMask &mask) const
{
  // if one of the two masks denotes the all-component mask,
  // then return the other one
  if (component_mask.size() == 0)
    return mask;
  else if (mask.component_mask.size() == 0)
    return *this;
  else
    {
      // if both masks have individual entries set, form
      // the combination of the two
      AssertDimension(component_mask.size(), mask.component_mask.size());
      std::vector<bool> new_mask (component_mask.size());
      for (unsigned int i=0; i<component_mask.size(); ++i)
        new_mask[i] = (component_mask[i] || mask.component_mask[i]);

      return new_mask;
    }
}


inline
ComponentMask
ComponentMask::operator & (const ComponentMask &mask) const
{
  // if one of the two masks denotes the all-component mask,
  // then return the other one
  if (component_mask.size() == 0)
    return mask;
  else if (mask.component_mask.size() == 0)
    return *this;
  else
    {
      // if both masks have individual entries set, form
      // the combination of the two
      AssertDimension(component_mask.size(), mask.component_mask.size());
      std::vector<bool> new_mask (component_mask.size());
      for (unsigned int i=0; i<component_mask.size(); ++i)
        new_mask[i] = (component_mask[i] && mask.component_mask[i]);

      return new_mask;
    }
}


inline
bool
ComponentMask::operator== (const ComponentMask &mask) const
{
  return component_mask == mask.component_mask;
}


inline
bool
ComponentMask::operator!= (const ComponentMask &mask) const
{
  return component_mask != mask.component_mask;
}



DEAL_II_NAMESPACE_CLOSE

#endif