HDU selectors and iterators

Detailed Description

Iterate over HDUs with selected categories and/or states.

Iterate over all HDUs of a MefFile

An iterator class and begin/end functions are defined to enable looping over all the HDUs of a MefFile. Usage is straightforward:

MefFile f(filename, FileMode::Edit);
// ...
for (const auto& hdu : f) {
    process_hdu(hdu); // Do something with each HDU
}

HDU categories and filters

HDUs can be selected using one of two dedicated classes: HduCategory or HduFilter.

An HduCategory object positions flags like: Primary or extension HDU, image or binary table HDU... HDU categories can be composed with binary operators & (and), | (or) and ~ (not). For example, to get the list of image extensions with integer values:

const auto category = HduCategory::IntImage & HduCategory::Ext;

An HduFilter is a list of acceptable HDU categories and unacceptable HDU categories. They are buit with operators + (accept) and - (reject). For example, to accept the Primary HDU and all the real-valued image HDUs, excluding the HDUs which were just created:

const auto filter = HduCategory::Primary + HduCategory::IntImage - HduCategory::Created;

It is possible to check if an HDU is of given category or matches a given filter with method Hdu::matches, as follows:

for (const auto& hdu : f) {
  if (hdu.matches(HduCategory::Primary)) {
    process_primary(hdu);
  } else if (hdu.matches(HduCategory::Image)) {
    process_image_ext(hdu.as<ImageHdu>());
  } else if (hdu.matches(HduCategory::Bintable)) {
    process_bintable_ext(hdu.as<BintableHdu>());
  }
}

Iterate over selected HDUs of a MefFile

Similarly to the range loop presented at the beginning of this page, it is possible to loop over a subset of HDUs. This is done by creating the adequate iterator using method MefFile::filter():

for (const auto& hdu : f.filter<ImageHdu>(HduCategory::Image & HduCategory::Created)) {
  process_new_image(hdu);
}

The template parameter specifies the class to be returned: Hdu, ImageHdu, or BintableHdu. It is used to constrain the given filter: for ImageHdu (resp. BintableHdu), HduCategory::Image (resp. HduCategory::Bintable) is added to the filter. Therefore, f.filter<ImageHdu>() is strictly equivalent to f.filter<ImageHdu>(HduCategory::Image), and the above example can be rewritten more straightforwardly:

for (const auto& hdu : f.filter<ImageHdu>(HduCategory::Created)) { // Don't repeat Image
  process_new_image(hdu);
}

Warning

Even when using filters, the whole file is scanned. It is therefore very inefficient to write several loops when one would be enough. For example, instead of:

for (const auto& hdu : f.filter<ImageHdu>()) { // Scans all HDUs
  process_image(hdu);
}
for (const auto& hdu : f.filter<BintableHdu>()) { // Scans all HDUs again
  process_bintable(hdu);
}

write:

for (const auto& hdu : f) {
  if (hdu.matches(HduCategory::Image)) {
    process_image(hdu.as<ImageHdu>());
  } else {
    process_bintable(hdu.as<BintableHdu>());
  }
}

See also

Optimization and good practices

Classes
class	HduCategory
	An HDU categorization for filtering and iteration. More...
class	HduFilter
	HDU filter built from HDU categories. More...
class	HduIterator< THdu >
	Iterator for MefFile's HDUs. More...
struct	HduSelector< THdu >
	Helper class to provide filtered iterators. More...
class	KeywordCategory
	Keyword categories and related tools. More...

Properties
virtual HduCategory	category () const
	Read the category of the HDU. More...
bool	matches (HduFilter filter) const
	Check whether the HDU matches a given filter. More...

Element access
template<typename T = Hdu>
HduSelector< T >	filter (const HduFilter &categories=HduCategory::Any)
	Get an iterable object which represents a filtered set of HDUs. More...