Template Class CatalogT

Inheritance Relationships

Derived Type

Class Documentation

template<typename RecordT>
class CatalogT

A custom container class for records, based on std::vector.

CatalogT wraps a std::vector<std::shared_ptr<RecordT>> in an interface that looks more like a std::vector<RecordT>; its iterators and accessors return references or const references, rather than pointers, making them easier to use. It also holds a table, which is used to allocate new records and determine the schema, but no checking is done to ensure that records added to the catalog use the same table or indeed have the same schema.

Because a CatalogT is holds shared_ptrs internally, many of its operations can be either shallow or deep, with new deep copies allocated by the catalog’s table object. New records can be also be inserted by pointer (shallow) or by value (deep).

The constness of records is determined by the constness of the first template parameter to CatalogT; a container instance is always either const or non-const in that respect (like smart pointers). Also like smart pointers, const member functions (and by extension, const_iterators) do not allow the underlying pointers to be changed, while non-const member functions and iterators do.

CatalogT does not permit empty (null) pointers as elements. As a result, CatalogT has no resize member function.

CatalogT has a very different interface in Python; it mimics Python’s list instead of C++’s std::vector. It is also considerably simpler, because it doesn’t need to deal with iterator ranges or the distinction between references and shared_ptrs to records. See the Python docstring for more information.

Subclassed by lsst::afw::table::SortedCatalogT< RecordT >

Unnamed Group

iterator begin()

Iterator access.

See

CatalogIterator

iterator end()
const_iterator begin() const
const_iterator end() const
const_iterator cbegin() const
const_iterator cend() const

Unnamed Group

template<typename T>
CatalogT<RecordT>::iterator find(typename Field<T>::Value const &value, Key<T> const &key)

Return an iterator to the record with the given value.

When the field being searched is not unique, which matching record will be returned is not defined. In these cases, lower_bound, upper_bound, or equal_range should be used instead.

In Python, this method returns a Record, not an iterator.

Returns end() if the Record cannot be found.

Note

The catalog must be sorted in ascending order according to the given key before calling find (i.e. isSorted(key) must be true).

template<typename T>
CatalogT<RecordT>::const_iterator find(typename Field<T>::Value const &value, Key<T> const &key) const

Unnamed Group

template<typename T>
CatalogT<RecordT>::iterator lower_bound(typename Field<T>::Value const &value, Key<T> const &key)

Performed binary searches on sorted fields.

These methods perform binary searches analogous to the STL algorithms of the same name; they simply create a comparison functor using the given value and Key.

In Python, the lower_bound and upper_bound methods return the position of the result record in the catalog, and equal_range returns a Python slice object that defines the range.

Note

The catalog must be sorted in ascending order according to the given key before calling any of the search methods (i.e. isSorted(key) must be true).

template<typename T>
CatalogT<RecordT>::const_iterator lower_bound(typename Field<T>::Value const &value, Key<T> const &key) const
template<typename T>
CatalogT<RecordT>::iterator upper_bound(typename Field<T>::Value const &value, Key<T> const &key)
template<typename T>
CatalogT<RecordT>::const_iterator upper_bound(typename Field<T>::Value const &value, Key<T> const &key) const
template<typename T>
std::pair<iterator, iterator> equal_range(typename Field<T>::Value const &value, Key<T> const &key)
template<typename T>
std::pair<const_iterator, const_iterator> equal_range(typename Field<T>::Value const &value, Key<T> const &key) const

Unnamed Group

Internal &getInternal()

Return a reference to the internal vector-of-shared_ptr

While in most cases it is more convenient to use the Catalog’s iterators, which dereference directly to Record objects (and hence allow iter->method() rather than (**iter).method()), direct access to the underlying vector-of-shared_ptr is provided here to allow complete use of the C++ STL. In particular, in order to use a mutating STL algorithm on a Catalog in such a way that Records are shallow-copied (i.e. shared_ptr::operator= is invoked instead of Record::operator=), those algorithms should be called on the iterators of these internal containers. When an algorithm should be called in such a way that records are deep-copied, the regular Catalog iterators should be used.

Internal const &getInternal() const

Public Types

typedef RecordT Record
typedef Record::Table Table
typedef Record::ColumnView ColumnView
typedef RecordT value_type
typedef RecordT &reference
typedef std::shared_ptr<RecordT> pointer
typedef Internal::size_type size_type
typedef Internal::difference_type difference_type
typedef CatalogIterator<typename Internal::iterator> iterator
typedef CatalogIterator<typename Internal::const_iterator> const_iterator

Public Functions

std::shared_ptr<Table> getTable() const

Return the table associated with the catalog.

Schema getSchema() const

Return the schema associated with the catalog’s table.

CatalogT(std::shared_ptr<Table> const &table = std::shared_ptr<Table>())

Construct a catalog from a table (or nothing).

A catalog with no table is considered invalid; a valid table must be assigned to it before it can be used.

CatalogT(Schema const &schema)

Construct a catalog from a schema, creating a table with Table::make(schema).

template<typename InputIterator>
CatalogT(std::shared_ptr<Table> const &table, InputIterator first, InputIterator last, bool deep = false)

Construct a catalog from a table and an iterator range.

If deep is true, new records will be created using table->copyRecord before being inserted. If deep is false, records will be not be copied, but they must already be associated with the given table. The table itself is never deep-copied.

The iterator must dereference to a record reference or const reference rather than a pointer, but should be implicitly convertible to a record pointer as well (see CatalogIterator).

CatalogT(CatalogT const &other)

Shallow copy constructor.

CatalogT(CatalogT &&other)
~CatalogT()
template<typename OtherRecordT>
CatalogT(CatalogT<OtherRecordT> const &other)

Shallow copy constructor from a container containing a related record type.

This conversion only succeeds if OtherRecordT is convertible to RecordT and OtherTable is convertible to Table.

CatalogT &operator=(CatalogT const &other)

Shallow assigment.

CatalogT &operator=(CatalogT &&other)
CatalogT<RecordT> subset(ndarray::Array<bool const, 1> const &mask) const

Return the subset of a catalog corresponding to the True values of the given mask array.

The returned array’s records are shallow copies, and hence will not in general be contiguous.

CatalogT<RecordT> subset(std::ptrdiff_t startd, std::ptrdiff_t stopd, std::ptrdiff_t step) const

Returns a shallow copy of a subset of this Catalog. The arguments correspond to python’s slice() syntax.

void writeFits(std::string const &filename, std::string const &mode = "w", int flags = 0) const

Write a FITS binary table to a regular file.

Parameters

  • [in] filename: Name of the file to write.

  • [in] mode: “a” to append a new HDU, “w” to overwrite any existing file.

  • [in] flags: Table-subclass-dependent bitflags that control the details of how to read the catalogs. See e.g. SourceFitsFlags.

void writeFits(fits::MemFileManager &manager, std::string const &mode = "w", int flags = 0) const

Write a FITS binary table to a RAM file.

Parameters

  • [inout] manager: Object that manages the memory to write to.

  • [in] mode: “a” to append a new HDU, “w” to overwrite any existing file.

  • [in] flags: Table-subclass-dependent bitflags that control the details of how to read the catalogs. See e.g. SourceFitsFlags.

void writeFits(fits::Fits &fitsfile, int flags = 0) const

Write a FITS binary table to an open file object.

Parameters

  • [inout] fitsfile: Fits file object to write to.

  • [in] flags: Table-subclass-dependent bitflags that control the details of how to read the catalogs. See e.g. SourceFitsFlags.

ColumnView getColumnView() const

Return a ColumnView of this catalog’s records.

Will throw RuntimeError if records are not contiguous.

bool isContiguous() const

Return true if all records are contiguous.

bool empty() const

Return true if the catalog has no records.

size_type size() const

Return the number of elements in the catalog.

size_type max_size() const

Return the maximum number of elements allowed in a catalog.

size_type capacity() const

Return the capacity of the catalog.

This is computed as the sum of the current size and the unallocated space in the table. It does not reflect the size of the internal vector, and hence cannot be used to judge when iterators may be invalidated.

void reserve(size_type n)

Increase the capacity of the catalog to the given size.

This can be used to guarantee that the catalog will be contiguous, but it only affects records constructed after reserve().

void resize(size_type n)

Change the size of the catalog, removing or adding empty records as needed.

reference operator[](size_type i) const

Return the record at index i.

reference at(size_type i) const

Return the record at index i (throws std::out_of_range).

reference front() const

Return the first record.

reference back() const

Return the last record.

std::shared_ptr<RecordT> const get(size_type i) const

Return a pointer to the record at index i.

void set(size_type i, std::shared_ptr<RecordT> const &p)

Set the record at index i to a pointer.

template<typename InputIterator>
void assign(InputIterator first, InputIterator last, bool deep = false)

Replace the contents of the table with an iterator range.

Delegates to insert(); look there for more information.

void push_back(Record const &r)

Add a copy of the given record to the end of the catalog.

void push_back(std::shared_ptr<RecordT> const &p)

Add the given record to the end of the catalog without copying.

std::shared_ptr<RecordT> addNew()

Create a new record, add it to the end of the catalog, and return a pointer to it.

void pop_back()

Remove the last record in the catalog.

CatalogT copy() const

Deep-copy the catalog using a cloned table.

template<typename InputIterator>
void insert(iterator pos, InputIterator first, InputIterator last, bool deep = false)

Insert an iterator range into the table.

InputIterator must dereference to a record reference that is convertible to the record type held by the catalog, and must be implicitly convertible to a shared_ptr to a record.

If deep is true, new records will be created by calling copyRecord on the catalog’s table. If deep is false, the new records will not be copied, but they must have been created with the catalog’s table (note that a table may be shared by multiple catalogs).

If InputIterator models RandomAccessIterator (according to std::iterator_traits) and deep is true, table->preallocate will be used to ensure that the resulting records are contiguous in memory and can be used with ColumnView. To ensure this is the case for other iterator types, the user must preallocate the table manually.

template<typename InputIterator>
void insert(SchemaMapper const &mapper, iterator pos, InputIterator first, InputIterator last)

Insert a range of records into the catalog by copying them with a SchemaMapper.

iterator insert(iterator pos, Record const &r)

Insert a copy of the given record at the given position.

iterator insert(iterator pos, std::shared_ptr<RecordT> const &p)

Insert the given record at the given position without copying.

iterator erase(iterator pos)

Erase the record pointed to by pos, and return an iterator the next record.

iterator erase(iterator first, iterator last)

Erase the records in the range [first, last).

void swap(CatalogT &other)

Shallow swap of two catalogs.

void clear()

Remove all records from the catalog.

template<typename T>
bool isSorted(Key<T> const &key) const

Return true if the catalog is in ascending order according to the given key.

template<typename Compare>
bool isSorted(Compare cmp) const

Return true if the catalog is in ascending order according to the given predicate.

cmp(a, b) should return true if record a is less than record b, and false otherwise.

template<typename T>
void sort(Key<T> const &key)

Sort the catalog in-place by the field with the given key.

template<typename Compare>
void sort(Compare cmp)

Sort the catalog in-place by the field with the given predicate.

cmp(a, b) should return true if record a is less than record b, and false otherwise.

template<typename T>
std::pair<typename CatalogT<RecordT>::iterator, typename CatalogT<RecordT>::iterator> equal_range(typename Field<T>::Value const &value, Key<T> const &key)
template<typename T>
std::pair<typename CatalogT<RecordT>::const_iterator, typename CatalogT<RecordT>::const_iterator> equal_range(typename Field<T>::Value const &value, Key<T> const &key) const

Public Static Functions

static CatalogT readFits(std::string const &filename, int hdu = fits::DEFAULT_HDU, int flags = 0)

Read a FITS binary table from a regular file.

Parameters

  • [in] filename: Name of the file to read.

  • [in] hdu: Number of the “header-data unit” to read (where 0 is the Primary HDU). The default value of afw::fits::DEFAULT_HDU is interpreted as “the first HDU with NAXIS != 0”.

  • [in] flags: Table-subclass-dependent bitflags that control the details of how to read the catalog. See e.g. SourceFitsFlags.

static CatalogT readFits(fits::MemFileManager &manager, int hdu = fits::DEFAULT_HDU, int flags = 0)

Read a FITS binary table from a RAM file.

Parameters

  • [in] manager: Object that manages the memory to be read.

  • [in] hdu: Number of the “header-data unit” to read (where 0 is the Primary HDU). The default value of afw::fits::DEFAULT_HDU is interpreted as “the first HDU with NAXIS != 0”.

  • [in] flags: Table-subclass-dependent bitflags that control the details of how to read the catalog. See e.g. SourceFitsFlags.

static CatalogT readFits(fits::Fits &fitsfile, int flags = 0)

Read a FITS binary table from a file object already at the correct extension.

Parameters

  • [in] fitsfile: Fits file object to read from.

  • [in] flags: Table-subclass-dependent bitflags that control the details of how to read the catalog. See e.g. SourceFitsFlags.