HDU selectors and iterators

Detailed Description

Tools to 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) {
    processHdu(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)) {
    processPrimary(hdu);
  } else if (hdu.matches(HduCategory::Image)) {
    processImageExt(hdu.as<ImageHdu>());
  } else if (hdu.matches(HduCategory::Bintable)) {
    processBintableExt(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::select():

for (const auto& hdu : f.select<ImageHdu>(HduCategory::Image & HduCategory::Created)) {
  processNewImage(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.select<ImageHdu>() is strictly equivalent to f.select<ImageHdu>(HduCategory::Image), and the above example can be rewritten more straightforwardly:

for (const auto& hdu : f.select<ImageHdu>(HduCategory::Created)) { // Don't repeat Image
  processNewImage(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.select<ImageHdu>()) { // Scans all HDUs
  processImage(hdu);
}
for (const auto& hdu : f.select<BintableHdu>()) { // Scans all HDUs again
  processBintable(hdu);
}

write:

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

See also

Optimization and good practices

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

Functions
virtual HduCategory	Euclid::Fits::Hdu::readCategory () const
	Read the category of the HDU. More...
bool	Euclid::Fits::Hdu::matches (HduFilter filter) const
	Check whether the HDU matches a given filter. More...
HduIterator	Euclid::Fits::begin (MefFile &f)
	Beginning of an iterator to loop over all HDUs as Hdus.
HduIterator	Euclid::Fits::end (MefFile &f)
	End of an iterator to loop over all HDUs as Hdus.
template<typename THdu = Hdu>
HduIterator< THdu >	Euclid::Fits::begin (HduSelector< THdu > &selector)
	Beginning of an iterator to loop over selected HDUs. More...
template<typename THdu = Hdu>
HduIterator< THdu >	Euclid::Fits::end (HduSelector< THdu > &selector)
	End of an iterator to loop over selected HDUs.
template<typename THdu = Hdu>
HduSelector< THdu >	Euclid::Fits::MefFile::select (const HduFilter &filter=HduCategory::Any)
	Select a filtered set of HDUs. More...