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

#include <Catalog.h>

Inheritance diagram for lsst::afw::table::CatalogT< RecordT >:

Public Types
using	Record = RecordT

using	Table = typename Record::Table

using	ColumnView = typename Record::ColumnView

using	value_type = RecordT

using	reference = RecordT &

using	pointer = std::shared_ptr< RecordT >

using	size_type = typename Internal::size_type

using	difference_type = typename Internal::difference_type

using	iterator = CatalogIterator< typename Internal::iterator >

using	const_iterator = CatalogIterator< typename Internal::const_iterator >

Public Member Functions
std::shared_ptr< Table >	getTable () const
	Return the table associated with the catalog. More...

Schema	getSchema () const
	Return the schema associated with the catalog's table. More...

	CatalogT (std::shared_ptr< Table > const &table=std::shared_ptr< Table >())
	Construct a catalog from a table (or nothing). More...

	CatalogT (Schema const &schema)
	Construct a catalog from a schema, creating a table with Table::make(schema). More...

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. More...

	CatalogT (CatalogT const &other)
	Shallow copy constructor. More...

	CatalogT (CatalogT &&other)

	~CatalogT ()=default

template<typename OtherRecordT >
	CatalogT (CatalogT< OtherRecordT > const &other)
	Shallow copy constructor from a container containing a related record type. More...

CatalogT &	operator= (CatalogT const &other)
	Shallow assigment. More...

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. More...

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. More...

void	writeFits (std::string const &filename, std::string const &mode="w", int flags=0) const
	Write a FITS binary table to a regular file. More...

void	writeFits (fits::MemFileManager &manager, std::string const &mode="w", int flags=0) const
	Write a FITS binary table to a RAM file. More...

void	writeFits (fits::Fits &fitsfile, int flags=0) const
	Write a FITS binary table to an open file object. More...

ColumnView	getColumnView () const
	Return a ColumnView of this catalog's records. More...

bool	isContiguous () const
	Return true if all records are contiguous. More...

iterator	begin ()
	Iterator access. More...

iterator	end ()

const_iterator	begin () const

const_iterator	end () const

const_iterator	cbegin () const

const_iterator	cend () const

bool	empty () const
	Return true if the catalog has no records. More...

size_type	size () const
	Return the number of elements in the catalog. More...

size_type	max_size () const
	Return the maximum number of elements allowed in a catalog. More...

size_type	capacity () const
	Return the capacity of the catalog. More...

void	reserve (size_type n)
	Increase the capacity of the catalog to the given size. More...

void	resize (size_type n)
	Change the size of the catalog, removing or adding empty records as needed. More...

reference	operator[] (size_type i) const
	Return the record at index i. More...

reference	at (size_type i) const
	Return the record at index i (throws std::out_of_range). More...

reference	front () const
	Return the first record. More...

reference	back () const
	Return the last record. More...

std::shared_ptr< RecordT > const	get (size_type i) const
	Return a pointer to the record at index i. More...

void	set (size_type i, std::shared_ptr< RecordT > const &p)
	Set the record at index i to a pointer. More...

template<typename InputIterator >
void	assign (InputIterator first, InputIterator last, bool deep=false)
	Replace the contents of the table with an iterator range. More...

void	push_back (Record const &r)
	Add a copy of the given record to the end of the catalog. More...

void	push_back (std::shared_ptr< RecordT > const &p)
	Add the given record to the end of the catalog without copying. More...

std::shared_ptr< RecordT >	addNew ()
	Create a new record, add it to the end of the catalog, and return a pointer to it. More...

void	pop_back ()
	Remove the last record in the catalog. More...

CatalogT	copy () const
	Deep-copy the catalog using a cloned table. More...

template<typename InputIterator >
void	insert (iterator pos, InputIterator first, InputIterator last, bool deep=false)
	Insert an iterator range into the table. More...

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. More...

iterator	insert (iterator pos, Record const &r)
	Insert a copy of the given record at the given position. More...

iterator	insert (iterator pos, std::shared_ptr< RecordT > const &p)
	Insert the given record at the given position without copying. More...

iterator	erase (iterator pos)
	Erase the record pointed to by pos, and return an iterator the next record. More...

iterator	erase (iterator first, iterator last)
	Erase the records in the range [first, last). More...

void	swap (CatalogT &other) noexcept
	Shallow swap of two catalogs. More...

void	clear ()
	Remove all records from the catalog. More...

template<typename T >
bool	isSorted (Key< T > const &key) const
	Return true if the catalog is in ascending order according to the given key. More...

template<typename Compare >
bool	isSorted (Compare cmp) const
	Return true if the catalog is in ascending order according to the given predicate. More...

template<typename T >
void	sort (Key< T > const &key)
	Sort the catalog in-place by the field with the given key. More...

template<typename Compare >
void	sort (Compare cmp)
	Sort the catalog in-place by the field with the given predicate. More...

template<typename T >
iterator	find (typename Field< T >::Value const &value, Key< T > const &key)
	Return an iterator to the record with the given value. More...

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

template<typename T >
iterator	lower_bound (typename Field< T >::Value const &value, Key< T > const &key)
	Performed binary searches on sorted fields. More...

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

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

template<typename T >
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

Internal &	getInternal ()
	Return a reference to the internal vector-of-shared_ptr. More...

Internal const &	getInternal () const

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

Static Public Member 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. More...

static CatalogT	readFits (fits::MemFileManager &manager, int hdu=fits::DEFAULT_HDU, int flags=0)
	Read a FITS binary table from a RAM file. More...

static CatalogT	readFits (fits::Fits &fitsfile, int flags=0)
	Read a FITS binary table from a file object already at the correct extension. More...

Detailed Description

template<typename RecordT>
class lsst::afw::table::CatalogT< RecordT >

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.

Definition at line 98 of file Catalog.h.

Member Typedef Documentation

◆ ColumnView

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::ColumnView = typename Record::ColumnView

Definition at line 104 of file Catalog.h.

◆ const_iterator

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::const_iterator = CatalogIterator<typename Internal::const_iterator>

Definition at line 112 of file Catalog.h.

◆ difference_type

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::difference_type = typename Internal::difference_type

Definition at line 110 of file Catalog.h.

◆ iterator

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::iterator = CatalogIterator<typename Internal::iterator>

Definition at line 111 of file Catalog.h.

◆ pointer

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::pointer = std::shared_ptr<RecordT>

Definition at line 108 of file Catalog.h.

◆ Record

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::Record = RecordT

Definition at line 102 of file Catalog.h.

◆ reference

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::reference = RecordT &

Definition at line 107 of file Catalog.h.

◆ size_type

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::size_type = typename Internal::size_type

Definition at line 109 of file Catalog.h.

◆ Table

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::Table = typename Record::Table

Definition at line 103 of file Catalog.h.

◆ value_type

template<typename RecordT >

using lsst::afw::table::CatalogT< RecordT >::value_type = RecordT

Definition at line 106 of file Catalog.h.

Constructor & Destructor Documentation

◆ CatalogT() [1/6]

template<typename RecordT >

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

inlineexplicit

Construct a catalog from a table (or nothing).

A table is always initialized with a minimal schema.

Definition at line 125 of file Catalog.h.

             : _table(table), _internal() {
         if(!_table) {
             auto schema=Table::makeMinimalSchema();
             _table=Table::make(schema);
         }
     }

◆ CatalogT() [2/6]

template<typename RecordT >

lsst::afw::table::CatalogT< RecordT >::CatalogT ( Schema const & schema )

inlineexplicit

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

Definition at line 134 of file Catalog.h.

134 : _table(Table::make(schema)), _internal() {}

◆ CatalogT() [3/6]

template<typename RecordT >

template<typename InputIterator >

lsst::afw::table::CatalogT< RecordT >::CatalogT	(	std::shared_ptr< Table > const &	table,
		InputIterator	first,
		InputIterator	last,
		bool	deep = `false`
	)

inline

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).

Definition at line 147 of file Catalog.h.

             : _table(table), _internal() {
         insert(end(), first, last, deep);
     }

◆ CatalogT() [4/6]

template<typename RecordT >

lsst::afw::table::CatalogT< RecordT >::CatalogT ( CatalogT< RecordT > const & other )

inline

Shallow copy constructor.

Definition at line 153 of file Catalog.h.

153 : _table(other._table), _internal(other._internal) {}

◆ CatalogT() [5/6]

template<typename RecordT >

lsst::afw::table::CatalogT< RecordT >::CatalogT ( CatalogT< RecordT > && other )

inline

Definition at line 155 of file Catalog.h.

155 : CatalogT(other) {}

lsst::afw::table::CatalogT::CatalogT

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

Construct a catalog from a table (or nothing).

Definition: Catalog.h:125

◆ ~CatalogT()

template<typename RecordT >

lsst::afw::table::CatalogT< RecordT >::~CatalogT ( )

default

◆ CatalogT() [6/6]

template<typename RecordT >

template<typename OtherRecordT >

lsst::afw::table::CatalogT< RecordT >::CatalogT ( CatalogT< OtherRecordT > const & other )

inline

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.

Definition at line 166 of file Catalog.h.

167 : _table(other.getTable()), _internal(other.begin().base(), other.end().base()) {}

Member Function Documentation

◆ addNew()

template<typename RecordT >

std::shared_ptr<RecordT> lsst::afw::table::CatalogT< RecordT >::addNew ( )

inline

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

Definition at line 490 of file Catalog.h.

                                     {
         std::shared_ptr<RecordT> r = _table->makeRecord();
         _internal.push_back(r);
         return r;
     }

◆ assign()

template<typename RecordT >

template<typename InputIterator >

void lsst::afw::table::CatalogT< RecordT >::assign	(	InputIterator	first,
		InputIterator	last,
		bool	deep = `false`
	)

inline

Replace the contents of the table with an iterator range.

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

Definition at line 475 of file Catalog.h.

                                                                             {
         clear();
         insert(end(), first, last, deep);
     }

◆ at()

template<typename RecordT >

reference lsst::afw::table::CatalogT< RecordT >::at ( size_type i ) const

inline

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

Definition at line 455 of file Catalog.h.

455 { return *_internal.at(i); }

std::vector::at

T at(T... args)

◆ back()

template<typename RecordT >

reference lsst::afw::table::CatalogT< RecordT >::back ( ) const

inline

Return the last record.

Definition at line 461 of file Catalog.h.

461 { return *_internal.back(); }

std::vector::back

T back(T... args)

◆ begin() [1/2]

template<typename RecordT >

iterator lsst::afw::table::CatalogT< RecordT >::begin ( )

inline

Iterator access.

See also: CatalogIterator

Definition at line 401 of file Catalog.h.

401 { return iterator(_internal.begin()); }

std::vector::begin

T begin(T... args)

lsst::afw::table::CatalogT::iterator

CatalogIterator< typename Internal::iterator > iterator

Definition: Catalog.h:111

◆ begin() [2/2]

template<typename RecordT >

const_iterator lsst::afw::table::CatalogT< RecordT >::begin ( ) const

inline

Definition at line 403 of file Catalog.h.

403 { return const_iterator(_internal.begin()); }

lsst::afw::table::CatalogT::const_iterator

CatalogIterator< typename Internal::const_iterator > const_iterator

Definition: Catalog.h:112

◆ capacity()

template<typename RecordT >

size_type lsst::afw::table::CatalogT< RecordT >::capacity ( ) const

inline

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.

Definition at line 425 of file Catalog.h.

425 { return _internal.size() + _table->getBufferSize(); }

std::vector::size

T size(T... args)

◆ cbegin()

template<typename RecordT >

const_iterator lsst::afw::table::CatalogT< RecordT >::cbegin ( ) const

inline

Definition at line 405 of file Catalog.h.

405 { return begin(); }

lsst::afw::table::CatalogT::begin

iterator begin()

Iterator access.

Definition: Catalog.h:401

◆ cend()

template<typename RecordT >

const_iterator lsst::afw::table::CatalogT< RecordT >::cend ( ) const

inline

Definition at line 406 of file Catalog.h.

406 { return end(); }

◆ clear()

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::clear ( )

inline

Remove all records from the catalog.

Definition at line 579 of file Catalog.h.

579 { _internal.clear(); }

std::vector::clear

T clear(T... args)

◆ copy()

template<typename RecordT >

CatalogT lsst::afw::table::CatalogT< RecordT >::copy ( ) const

inline

Deep-copy the catalog using a cloned table.

Definition at line 500 of file Catalog.h.

500 { return CatalogT(getTable()->clone(), begin(), end(), true); }

lsst::afw::table::CatalogT::getTable

std::shared_ptr< Table > getTable() const

Return the table associated with the catalog.

Definition: Catalog.h:115

lsst::afw::image.image._slicing.clone

clone

Definition: _slicing.py:278

◆ empty()

template<typename RecordT >

bool lsst::afw::table::CatalogT< RecordT >::empty ( ) const

inline

Return true if the catalog has no records.

Definition at line 410 of file Catalog.h.

410 { return _internal.empty(); }

std::vector::empty

T empty(T... args)

◆ end() [1/2]

template<typename RecordT >

iterator lsst::afw::table::CatalogT< RecordT >::end ( )

inline

Definition at line 402 of file Catalog.h.

402 { return iterator(_internal.end()); }

std::vector::end

T end(T... args)

◆ end() [2/2]

template<typename RecordT >

const_iterator lsst::afw::table::CatalogT< RecordT >::end ( ) const

inline

Definition at line 404 of file Catalog.h.

404 { return const_iterator(_internal.end()); }

◆ equal_range() [1/4]

template<typename RecordT >

template<typename T >

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

◆ equal_range() [2/4]

template<typename RecordT >

template<typename T >

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

Definition at line 850 of file Catalog.h.

                                                                                      {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, iterator>;
     std::pair<SearchIter, SearchIter> i =
             std::equal_range(SearchIter(begin(), f), SearchIter(end(), f), value);
     return std::make_pair(i.first.base(), i.second.base());
 }

◆ equal_range() [3/4]

template<typename RecordT >

template<typename T >

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

◆ equal_range() [4/4]

template<typename RecordT >

template<typename T >

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

Definition at line 862 of file Catalog.h.

                                                                                            {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, const_iterator>;
     std::pair<SearchIter, SearchIter> i =
             std::equal_range(SearchIter(begin(), f), SearchIter(end(), f), value);
     return std::make_pair(i.first.base(), i.second.base());
 }

◆ erase() [1/2]

template<typename RecordT >

iterator lsst::afw::table::CatalogT< RecordT >::erase	(	iterator	first,
		iterator	last
	)

inline

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

Definition at line 568 of file Catalog.h.

                                                   {
         return iterator(_internal.erase(first.base(), last.base()));
     }

◆ erase() [2/2]

template<typename RecordT >

iterator lsst::afw::table::CatalogT< RecordT >::erase ( iterator pos )

inline

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

Definition at line 565 of file Catalog.h.

565 { return iterator(_internal.erase(pos.base())); }

◆ find() [1/2]

template<typename RecordT >

template<typename T >

CatalogT< RecordT >::iterator lsst::afw::table::CatalogT< RecordT >::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.

Note: The catalog must be sorted in ascending order according to the given key before calling find (i.e. isSorted(key) must be true) for maximal efficiency. If the value searched for is not found, it assumes that the catalog is unsorted and performs a brute-force search instead of failing immediately.

Returns end() if the Record cannot be found.

Definition at line 763 of file Catalog.h.

                                                                                 {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, iterator>;
     /* Try binary search for log n search assuming the table is sorted.
      * If the search is unsuccessful, try a brute-force search before quitting.
      */
     SearchIter i = std::lower_bound(SearchIter(begin(), f), SearchIter(end(), f), value);
     if (i.base() == end() || *i != value) {
         i = std::find(SearchIter(begin(), f), SearchIter(end(), f), value);
         if (i.base() == end()) {
             return end();
         }
         LOGL_DEBUG("afw.table.Catalog", "Catalog is not sorted by the key. Finding a record may be slow.");
     }
     return i.base();
 }

◆ find() [2/2]

template<typename RecordT >

template<typename T >

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

Definition at line 784 of file Catalog.h.

                                                                                             {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, const_iterator>;
     /* Try binary search for log n search assuming the table is sorted.
      * If the search is unsuccessful, try a brute-force search before quitting.
      */
     SearchIter i = std::lower_bound(SearchIter(begin(), f), SearchIter(end(), f), value);
     if (i.base() == end() || *i != value) {
         i = std::find(SearchIter(begin(), f), SearchIter(end(), f), value);
         if (i.base() == end()) {
             return end();
         }
         LOGL_DEBUG("afw.table.Catalog", "Catalog is not sorted by the key. Finding a record may be slow.");
     }
     return i.base();
 }

◆ front()

template<typename RecordT >

reference lsst::afw::table::CatalogT< RecordT >::front ( ) const

inline

Return the first record.

Definition at line 458 of file Catalog.h.

458 { return *_internal.front(); }

std::vector::front

T front(T... args)

◆ get()

template<typename RecordT >

std::shared_ptr<RecordT> const lsst::afw::table::CatalogT< RecordT >::get ( size_type i ) const

inline

Return a pointer to the record at index i.

Definition at line 464 of file Catalog.h.

464 { return _internal[i]; }

◆ getColumnView()

template<typename RecordT >

ColumnView lsst::afw::table::CatalogT< RecordT >::getColumnView ( ) const

inline

Return a ColumnView of this catalog's records.

Will throw RuntimeError if records are not contiguous.

Definition at line 382 of file Catalog.h.

                                      {
         if (std::is_const<RecordT>::value) {
             throw LSST_EXCEPT(
                     pex::exceptions::LogicError,
                     "Cannot get a column view from a CatalogT<RecordT const> (as column views are always "
                     "non-const views).");
         }
         return ColumnView::make(_table, begin(), end());
     }

◆ getInternal() [1/2]

template<typename RecordT >

Internal& lsst::afw::table::CatalogT< RecordT >::getInternal ( )

inline

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.

Definition at line 676 of file Catalog.h.

676 { return _internal; }

◆ getInternal() [2/2]

template<typename RecordT >

Internal const& lsst::afw::table::CatalogT< RecordT >::getInternal ( ) const

inline

Definition at line 677 of file Catalog.h.

677 { return _internal; }

◆ getSchema()

template<typename RecordT >

Schema lsst::afw::table::CatalogT< RecordT >::getSchema ( ) const

inline

Return the schema associated with the catalog's table.

Definition at line 118 of file Catalog.h.

118 { return _table->getSchema(); }

◆ getTable()

template<typename RecordT >

std::shared_ptr<Table> lsst::afw::table::CatalogT< RecordT >::getTable ( ) const

inline

Return the table associated with the catalog.

Definition at line 115 of file Catalog.h.

115 { return _table; }

◆ insert() [1/4]

template<typename RecordT >

template<typename InputIterator >

void lsst::afw::table::CatalogT< RecordT >::insert	(	iterator	pos,
		InputIterator	first,
		InputIterator	last,
		bool	deep = `false`
	)

inline

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.

Definition at line 518 of file Catalog.h.

                                                                                           {
         _maybeReserve(pos, first, last, deep,
                       (typename std::iterator_traits<InputIterator>::iterator_category*)nullptr);
         if (deep) {
             while (first != last) {
                 pos = insert(pos, *first);
                 ++pos;
                 ++first;
             }
         } else {
             while (first != last) {
                 pos = insert(pos, first);
                 assert(pos != end());
                 ++pos;
                 ++first;
             }
         }
     }

◆ insert() [2/4]

template<typename RecordT >

iterator lsst::afw::table::CatalogT< RecordT >::insert	(	iterator	pos,
		Record const &	r
	)

inline

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

Definition at line 554 of file Catalog.h.

                                                    {
         std::shared_ptr<RecordT> p = _table->copyRecord(r);
         return iterator(_internal.insert(pos.base(), p));
     }

◆ insert() [3/4]

template<typename RecordT >

iterator lsst::afw::table::CatalogT< RecordT >::insert	(	iterator	pos,
		std::shared_ptr< RecordT > const &	p
	)

inline

Insert the given record at the given position without copying.

Definition at line 560 of file Catalog.h.

                                                                    {
         return iterator(_internal.insert(pos.base(), p));
     }

◆ insert() [4/4]

template<typename RecordT >

template<typename InputIterator >

void lsst::afw::table::CatalogT< RecordT >::insert	(	SchemaMapper const &	mapper,
		iterator	pos,
		InputIterator	first,
		InputIterator	last
	)

inline

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

Definition at line 539 of file Catalog.h.

                                                                                                    {
         if (!_table->getSchema().contains(mapper.getOutputSchema())) {
             throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
                               "SchemaMapper's output schema does not match catalog's schema");
         }
         _maybeReserve(pos, first, last, true,
                       (typename std::iterator_traits<InputIterator>::iterator_category*)nullptr);
         while (first != last) {
             pos = insert(pos, _table->copyRecord(*first, mapper));
             ++pos;
             ++first;
         }
     }

◆ isContiguous()

template<typename RecordT >

bool lsst::afw::table::CatalogT< RecordT >::isContiguous ( ) const

inline

Return true if all records are contiguous.

Definition at line 393 of file Catalog.h.

393 { return ColumnView::isRangeContiguous(_table, begin(), end()); }

◆ isSorted() [1/2]

template<typename RecordT >

template<typename Compare >

bool lsst::afw::table::CatalogT< RecordT >::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.

TODO: C++11 has an is_sorted function we should use when available.

Definition at line 726 of file Catalog.h.

                                                   {
     detail::ComparisonAdaptor<RecordT, Compare> f = {cmp};
     if (empty()) return true;
     const_iterator last = this->begin();
     const_iterator i = last;
     ++i;
     for (; i != this->end(); ++i) {
         if (f(i, last)) return false;
         last = i;
     }
     return true;
 }

◆ isSorted() [2/2]

template<typename RecordT >

template<typename T >

bool lsst::afw::table::CatalogT< RecordT >::isSorted ( Key< T > const & key ) const

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

Definition at line 749 of file Catalog.h.

                                                         {
     detail::KeyComparisonFunctor<RecordT, T> f = {key};
     return isSorted(f);
 }

◆ lower_bound() [1/2]

template<typename RecordT >

template<typename T >

CatalogT< RecordT >::iterator lsst::afw::table::CatalogT< RecordT >::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).

Definition at line 805 of file Catalog.h.

                                                                                        {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, iterator>;
     SearchIter i = std::lower_bound(SearchIter(begin(), f), SearchIter(end(), f), value);
     return i.base();
 }

◆ lower_bound() [2/2]

template<typename RecordT >

template<typename T >

CatalogT< RecordT >::const_iterator lsst::afw::table::CatalogT< RecordT >::lower_bound	(	typename Field< T >::Value const &	value,
		Key< T > const &	key
	)		const

Definition at line 816 of file Catalog.h.

                                                                       {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, const_iterator>;
     SearchIter i = std::lower_bound(SearchIter(begin(), f), SearchIter(end(), f), value);
     return i.base();
 }

◆ max_size()

template<typename RecordT >

size_type lsst::afw::table::CatalogT< RecordT >::max_size ( ) const

inline

Return the maximum number of elements allowed in a catalog.

Definition at line 416 of file Catalog.h.

416 { return _internal.max_size(); }

std::vector::max_size

T max_size(T... args)

◆ operator=() [1/2]

template<typename RecordT >

CatalogT& lsst::afw::table::CatalogT< RecordT >::operator= ( CatalogT< RecordT > && other )

inline

Definition at line 178 of file Catalog.h.

178 { return *this = other; }

◆ operator=() [2/2]

template<typename RecordT >

CatalogT& lsst::afw::table::CatalogT< RecordT >::operator= ( CatalogT< RecordT > const & other )

inline

Shallow assigment.

Definition at line 170 of file Catalog.h.

                                                {
         if (&other != this) {
             _table = other._table;
             _internal = other._internal;
         }
         return *this;
     }

◆ operator[]()

template<typename RecordT >

reference lsst::afw::table::CatalogT< RecordT >::operator[] ( size_type i ) const

inline

Return the record at index i.

Definition at line 452 of file Catalog.h.

452 { return *_internal[i]; }

◆ pop_back()

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::pop_back ( )

inline

Remove the last record in the catalog.

Definition at line 497 of file Catalog.h.

497 { _internal.pop_back(); }

std::vector::pop_back

T pop_back(T... args)

◆ push_back() [1/2]

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::push_back ( Record const & r )

inline

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

Definition at line 481 of file Catalog.h.

                                     {
         std::shared_ptr<RecordT> p = _table->copyRecord(r);
         _internal.push_back(p);
     }

◆ push_back() [2/2]

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::push_back ( std::shared_ptr< RecordT > const & p )

inline

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

Definition at line 487 of file Catalog.h.

487 { _internal.push_back(p); }

◆ readFits() [1/3]

template<typename RecordT >

static CatalogT lsst::afw::table::CatalogT< RecordT >::readFits	(	fits::Fits &	fitsfile,
		int	flags = `0`
	)

inlinestatic

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.

Definition at line 373 of file Catalog.h.

                                                                 {
         return io::FitsReader::apply<CatalogT>(fitsfile, flags);
     }

◆ readFits() [2/3]

template<typename RecordT >

static CatalogT lsst::afw::table::CatalogT< RecordT >::readFits	(	fits::MemFileManager &	manager,
		int	hdu = `fits::DEFAULT_HDU`,
		int	flags = `0`
	)

inlinestatic

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.

Definition at line 362 of file Catalog.h.

                                                                                                     {
         return io::FitsReader::apply<CatalogT>(manager, hdu, flags);
     }

◆ readFits() [3/3]

template<typename RecordT >

static CatalogT lsst::afw::table::CatalogT< RecordT >::readFits	(	std::string const &	filename,
		int	hdu = `fits::DEFAULT_HDU`,
		int	flags = `0`
	)

inlinestatic

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.

Definition at line 348 of file Catalog.h.

                                                                                                   {
         return io::FitsReader::apply<CatalogT>(filename, hdu, flags);
     }

◆ reserve()

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::reserve ( size_type n )

inline

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().

Definition at line 433 of file Catalog.h.

                               {
         if (n <= _internal.size()) return;
         _table->preallocate(n - _internal.size());
         _internal.reserve(n);
     }

◆ resize()

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::resize ( size_type n )

inline

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

Definition at line 440 of file Catalog.h.

                              {
         size_type old = size();
         _internal.resize(n);
         if (old < n) {
             _table->preallocate(n - old);
             for (size_type i = old; i != n; ++i) {
                 _internal[i] = _table->makeRecord();
             }
         }
     }

◆ set()

template<typename RecordT >

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

inline

Set the record at index i to a pointer.

Definition at line 467 of file Catalog.h.

467 { _internal[i] = p; }

◆ size()

template<typename RecordT >

size_type lsst::afw::table::CatalogT< RecordT >::size ( ) const

inline

Return the number of elements in the catalog.

Definition at line 413 of file Catalog.h.

413 { return _internal.size(); }

◆ sort() [1/2]

template<typename RecordT >

template<typename Compare >

void lsst::afw::table::CatalogT< RecordT >::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.

Definition at line 742 of file Catalog.h.

                                         {
     detail::ComparisonAdaptor<RecordT, Compare> f = {cmp};
     std::stable_sort(_internal.begin(), _internal.end(), f);
 }

◆ sort() [2/2]

template<typename RecordT >

template<typename T >

void lsst::afw::table::CatalogT< RecordT >::sort ( Key< T > const & key )

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

Definition at line 756 of file Catalog.h.

                                               {
     detail::KeyComparisonFunctor<RecordT, T> f = {key};
     return sort(f);
 }

◆ subset() [1/2]

template<typename RecordT >

CatalogT<RecordT> lsst::afw::table::CatalogT< RecordT >::subset ( ndarray::Array< bool const, 1 > const & mask ) const

inline

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.

Definition at line 185 of file Catalog.h.

                                                                             {
         if (size_type(mask.size()) != size()) {
             throw LSST_EXCEPT(
                     pex::exceptions::LengthError,
                     (boost::format("Mask array with %d elements applied to catalog with %d elements") %
                      mask.size() % size())
                             .str());
         }
         CatalogT<RecordT> result(getTable());
         ndarray::Array<bool const, 1>::Iterator maskIter = mask.begin();
         const_iterator catIter = begin();
         for (; maskIter != mask.end(); ++maskIter, ++catIter) {
             if (*maskIter) result.push_back(catIter);
         }
         return result;
     }

◆ subset() [2/2]

template<typename RecordT >

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

inline

Returns a shallow copy of a subset of this Catalog.

The arguments correspond to python's slice() syntax.

Definition at line 206 of file Catalog.h.

                                                                                                {
         /* Python's slicing syntax is weird and wonderful.
  
          Both the "start" and "stop" indices can be negative, which means the
          abs() of the index less than the size; [-1] means the last item.
          Moreover, it's possible to have a negative index less than -len(); it
          will get clipped.  That is in fact one way to slice *backward* through
          the array *and* include element 0;
  
          >>> range(10)[5:-20:-1]
          [5, 4, 3, 2, 1, 0]
  
          The clipping tests in this function look more complicated than they
          need to be, but that is partly because there are some weird edge cases.
  
          Also, ptrdiff_t vs size_t introduces some annoying complexity.  Note
          that the args are "startd"/"stopd" (not "start"/"stop").
  
          There is a fairly complete set of tests in tests/ticket2026.py; if you
          try to simplify this function, be sure they continue to pass.
          */
         size_type S = size();
         size_type start, stop = 0;
         // Python doesn't allow step == 0
         if (step == 0) {
             throw LSST_EXCEPT(pex::exceptions::InvalidParameterError, "Step cannot be zero");
         }
         // Basic negative indexing rule: first add size
         if (startd < 0) {
             startd += S;
         }
         if (stopd < 0) {
             stopd += S;
         }
         // Start gets clipped to zero; stop does not (yet).
         if (startd < 0) {
             startd = 0;
         }
         // Now start is non-negative, so can cast to size_t.
         start = (size_type)startd;
         if (start > S) {
             start = S;
         }
         if (step > 0) {
             // When stepping forward, stop gets clipped at zero,
             // so is non-negative and can get cast to size_t.
             if (stopd < 0) {
                 stopd = 0;
             }
             stop = (size_type)stopd;
             if (stop > S) {
                 stop = S;
             }
         } else if (step < 0) {
             // When stepping backward, stop gets clipped at -1 so that slices
             // including 0 are possible.
             if (stopd < 0) {
                 stopd = -1;
             }
         }
  
         if (((step > 0) && (start >= stop)) || ((step < 0) && ((std::ptrdiff_t)start <= stopd))) {
             // Empty range
             return CatalogT<RecordT>(getTable(), begin(), begin());
         }
  
         if (step == 1) {
             // Use the iterator-based constructor for this simple case
             assert(start >= 0);
             assert(stop > 0);
             assert(start < S);
             assert(stop <= S);
             return CatalogT<RecordT>(getTable(), begin() + start, begin() + stop);
         }
  
         // Build a new CatalogT and copy records into it.
         CatalogT<RecordT> cat(getTable());
         size_type N = 0;
         if (step >= 0) {
             N = (stop - start) / step + (((stop - start) % step) ? 1 : 0);
         } else {
             N = (size_t)((stopd - (std::ptrdiff_t)start) / step +
                          (((stopd - (std::ptrdiff_t)start) % step) ? 1 : 0));
         }
         cat.reserve(N);
         if (step >= 0) {
             for (size_type i = start; i < stop; i += step) {
                 cat.push_back(get(i));
             }
         } else {
             for (std::ptrdiff_t i = (std::ptrdiff_t)start; i > stopd; i += step) {
                 cat.push_back(get(i));
             }
         }
         return cat;
     }

◆ swap()

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::swap ( CatalogT< RecordT > & other )

inlinenoexcept

Shallow swap of two catalogs.

Definition at line 573 of file Catalog.h.

                                         {
         _table.swap(other._table);
         _internal.swap(other._internal);
     }

◆ upper_bound() [1/2]

template<typename RecordT >

template<typename T >

CatalogT< RecordT >::iterator lsst::afw::table::CatalogT< RecordT >::upper_bound	(	typename Field< T >::Value const &	value,
		Key< T > const &	key
	)

Definition at line 827 of file Catalog.h.

                                                                                        {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, iterator>;
     SearchIter i = std::upper_bound(SearchIter(begin(), f), SearchIter(end(), f), value);
     return i.base();
 }

◆ upper_bound() [2/2]

template<typename RecordT >

template<typename T >

CatalogT< RecordT >::const_iterator lsst::afw::table::CatalogT< RecordT >::upper_bound	(	typename Field< T >::Value const &	value,
		Key< T > const &	key
	)		const

Definition at line 838 of file Catalog.h.

                                                                       {
     detail::KeyExtractionFunctor<RecordT, T> f = {key};
     // Iterator adaptor that makes a CatalogT iterator work like an iterator over field values.
     using SearchIter = boost::transform_iterator<detail::KeyExtractionFunctor<RecordT, T>, const_iterator>;
     SearchIter i = std::upper_bound(SearchIter(begin(), f), SearchIter(end(), f), value);
     return i.base();
 }

◆ writeFits() [1/3]

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::writeFits	(	fits::Fits &	fitsfile,
		int	flags = `0`
	)		const

inline

Write a FITS binary table to an open file object.

Parameters

[in,out]	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.

Definition at line 334 of file Catalog.h.

                                                             {
         io::FitsWriter::apply(fitsfile, *this, flags);
     }

◆ writeFits() [2/3]

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::writeFits	(	fits::MemFileManager &	manager,
		std::string const &	mode = `"w"`,
		int	flags = `0`
	)		const

inline

Write a FITS binary table to a RAM file.

Parameters

[in,out]	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.

Definition at line 323 of file Catalog.h.

                                                                                                   {
         io::FitsWriter::apply(manager, mode, *this, flags);
     }

◆ writeFits() [3/3]

template<typename RecordT >

void lsst::afw::table::CatalogT< RecordT >::writeFits	(	std::string const &	filename,
		std::string const &	mode = `"w"`,
		int	flags = `0`
	)		const

inline

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.

Definition at line 311 of file Catalog.h.

                                                                                                 {
         io::FitsWriter::apply(filename, mode, *this, flags);
     }

The documentation for this class was generated from the following file:

/j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/afw/22.0.1-32-g5ddfab5d3+60ce4897b0/include/lsst/afw/table/Catalog.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

template<typename RecordT> class lsst::afw::table::CatalogT< RecordT >

Member Typedef Documentation

◆ ColumnView

◆ const_iterator

◆ difference_type

◆ iterator

◆ pointer

◆ Record

◆ reference

◆ size_type

◆ Table

◆ value_type

Constructor & Destructor Documentation

◆ CatalogT() [1/6]

◆ CatalogT() [2/6]

◆ CatalogT() [3/6]

◆ CatalogT() [4/6]

◆ CatalogT() [5/6]

◆ ~CatalogT()

◆ CatalogT() [6/6]

Member Function Documentation

◆ addNew()

◆ assign()

◆ at()

◆ back()

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ cbegin()

◆ cend()

◆ clear()

◆ copy()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ equal_range() [1/4]

◆ equal_range() [2/4]

◆ equal_range() [3/4]

◆ equal_range() [4/4]

◆ erase() [1/2]

◆ erase() [2/2]

◆ find() [1/2]

◆ find() [2/2]

◆ front()

◆ get()

◆ getColumnView()

◆ getInternal() [1/2]

◆ getInternal() [2/2]

◆ getSchema()

◆ getTable()

◆ insert() [1/4]

◆ insert() [2/4]

◆ insert() [3/4]

◆ insert() [4/4]

◆ isContiguous()

◆ isSorted() [1/2]

◆ isSorted() [2/2]

◆ lower_bound() [1/2]

◆ lower_bound() [2/2]

◆ max_size()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ pop_back()

◆ push_back() [1/2]

◆ push_back() [2/2]

◆ readFits() [1/3]

◆ readFits() [2/3]

◆ readFits() [3/3]

◆ reserve()

◆ resize()

◆ set()

◆ size()

◆ sort() [1/2]

◆ sort() [2/2]

◆ subset() [1/2]

template<typename RecordT>
class lsst::afw::table::CatalogT< RecordT >