component_mask.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 2012 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#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 <deal.II/base/types.h>
 
#include <algorithm>
#include <iosfwd>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
 
 
class ComponentMask
{
public:
  ComponentMask() = default;
 
  template <typename = void>
  DEAL_II_DEPRECATED_WITH_COMMENT(
    "Implicit conversions from std::vector<bool> to ComponentMask are deprecated!")
  ComponentMask(const std::vector<bool> &block_mask);
 
  explicit 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);
 
#ifndef DOXYGEN
// -------------------- inline functions ---------------------
 
template <typename>
inline ComponentMask::ComponentMask(const std::vector<bool> &component_mask)
  : component_mask(component_mask)
{}
 
 
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.empty())
    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.empty()) || (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.empty())
    return real_n;
  else
    {
      AssertDimension(real_n, component_mask.size());
      return std::count_if(component_mask.begin(),
                           component_mask.end(),
                           [](const bool selected) { return selected; });
    }
}
 
 
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.empty())
    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.empty());
}
 
 
 
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.empty())
    return mask;
  else if (mask.component_mask.empty())
    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 ComponentMask(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.empty())
    return mask;
  else if (mask.component_mask.empty())
    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 ComponentMask(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;
}
#endif // DOXYGEN
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif