lsst::afw::table::Schema Class Reference

Defines the fields and offsets for a table. More...

#include <Schema.h>

Public Types
enum	ComparisonFlags {   EQUAL_KEYS = 0x01, EQUAL_NAMES = 0x02, EQUAL_DOCS = 0x04, EQUAL_UNITS = 0x08,   EQUAL_FIELDS = 0x0F, EQUAL_ALIASES = 0x10, IDENTICAL = 0x1F }
	Bit flags used when comparing schemas. More...

Public Member Functions
template<typename T >
SchemaItem< T >	find (std::string const &name) const
	Find a SchemaItem in the Schema by name. More...
template<typename T >
SchemaItem< T >	find (Key< T > const &key) const
	Find a SchemaItem in the Schema by key. More...
template<typename F >
void	findAndApply (std::string const &name, F &&func) const
	Find a SchemaItem by name and run a functor on it. More...
SubSchema	operator[] (std::string const &name) const
	Look up a (possibly incomplete) name in the Schema. More...
std::set< std::string >	getNames (bool topOnly=false) const
	Return a set of field names in the schema. More...
int	getRecordSize () const
	Return the raw size of a record in bytes. More...
int	getFieldCount () const
	The total number of fields. More...
int	getFlagFieldCount () const
	The number of Flag fields. More...
int	getNonFlagFieldCount () const
	The number of non-Flag fields. More...
template<typename T >
Key< T >	addField (Field< T > const &field, bool doReplace=false)
	Add a new field to the Schema, and return the associated Key. More...
template<typename T >
Key< T >	addField (std::string const &name, std::string const &doc, std::string const &units="", FieldBase< T > const &base=FieldBase< T >(), bool doReplace=false)
	Add a new field to the Schema, and return the associated Key. More...
template<typename T >
Key< T >	addField (std::string const &name, std::string const &doc, FieldBase< T > const &base, bool doReplace=false)
	Add a new field to the Schema, and return the associated Key. More...
template<typename T >
void	replaceField (Key< T > const &key, Field< T > const &field)
	Replace the Field (name/description) for an existing Key. More...
template<typename F >
void	forEach (F &&func) const
	Apply a functor to each SchemaItem in the Schema. More...
std::size_t	hash_value () const noexcept
	Return a hash of this object. More...
int	compare (Schema const &other, int flags=EQUAL_KEYS) const
	Do a detailed equality comparison of two schemas. More...
int	contains (Schema const &other, int flags=EQUAL_KEYS) const
	Test whether the given schema is a subset of this. More...
template<typename T >
int	contains (SchemaItem< T > const &item, int flags=EQUAL_KEYS) const
	Return true if the given item is in this schema. More...
std::shared_ptr< AliasMap >	getAliasMap () const
	Return the map of aliases. More...
void	setAliasMap (std::shared_ptr< AliasMap > aliases)
	Set the alias map. More...
void	disconnectAliases ()
	Sever the connection between this schema and any others with which it shares aliases. More...
	Schema ()
	Construct an empty Schema. More...
	Schema (Schema const &other)
	Copy constructor. More...
	Schema (Schema &&other)
Schema &	operator= (Schema const &other)
Schema &	operator= (Schema &&other)
	~Schema ()
std::string	join (std::string const &a, std::string const &b) const
	Join strings using the field delimiter appropriate for this Schema. More...
std::string	join (std::string const &a, std::string const &b, std::string const &c) const
	Join strings using the field delimiter appropriate for this Schema. More...
std::string	join (std::string const &a, std::string const &b, std::string const &c, std::string const &d) const
	Join strings using the field delimiter appropriate for this Schema. More...
bool	operator== (Schema const &other) const
	Equality comparison. More...
bool	operator!= (Schema const &other) const
	Equality comparison. More...

Static Public Member Functions
static Schema	readFits (std::string const &filename, int hdu=fits::DEFAULT_HDU)
	Construct from reading a FITS file. More...
static Schema	readFits (fits::MemFileManager &manager, int hdu=fits::DEFAULT_HDU)
static Schema	readFits (fits::Fits &fitsfile)
static Schema	fromFitsMetadata (daf::base::PropertyList &header, bool stripMetadata=true)
	Construct from reading a FITS header. More...

Static Public Attributes
static int const	VERSION = detail::SchemaImpl::VERSION

Friends
class	detail::Access
class	SubSchema
std::ostream &	operator<< (std::ostream &os, Schema const &schema)
	Stringification. More...

Detailed Description

Defines the fields and offsets for a table.

Schema behaves like a container of SchemaItem objects, mapping a descriptive Field object with the Key object used to access record and ColumnView values. A Schema is the most important ingredient in creating a table.

Because offsets for fields are assigned when the field is added to the Schema, Schemas do not support removing fields, though they do allow renaming.

Field names in Schemas are expected to be underscore-separated names (e.g. 'a_b_c', but see Field Names for the full conventions, including when to use underscores vs. CamelCase). The SubSchema class and Schema::operator[] provide a heirarchical interface to these names, but are implemented entirely as string splitting/joining operations that ultimately forward to member functions that operate on the fully-qualified field name, so there is no requirement that names be separated by underscores, and no performance advantage to using a SubSchema.

A SchemaMapper object can be used to define a relationship between two Schemas to be used when copying values from one table to another or loading/saving selected fields to disk.

Schema uses copy-on-write, and hence should always be held by value rather than smart pointer. When creating a Python interface, functions that return Schema by const reference should be converted to return by value (returnCopy) to ensure proper memory management and encapsulation.

Definition at line 50 of file Schema.h.

Member Enumeration Documentation

ComparisonFlags

enum lsst::afw::table::Schema::ComparisonFlags

Bit flags used when comparing schemas.

All quantities are compared in insertion order, so if two schemas have the same fields added in opposite order, they will not be considered equal.

Enumerator
EQUAL_KEYS	Keys have the same types offsets, and sizes.
EQUAL_NAMES	Fields have the same names (ordered).
EQUAL_DOCS	Fields have the same documentation (ordered).
EQUAL_UNITS	Fields have the same units (ordered).
EQUAL_FIELDS	Fields are identical (but aliases may not be).
EQUAL_ALIASES	Schemas have identical AliasMaps.
IDENTICAL	Everything is the same.

Definition at line 64 of file Schema.h.

                         {
        EQUAL_KEYS = 0x01,     
        EQUAL_NAMES = 0x02,    
        EQUAL_DOCS = 0x04,     
        EQUAL_UNITS = 0x08,    
        EQUAL_FIELDS = 0x0F,   
        EQUAL_ALIASES = 0x10,  
        IDENTICAL = 0x1F       
    };

Constructor & Destructor Documentation

Schema() [1/3]

lsst::afw::table::Schema::Schema

(

)

Construct an empty Schema.

Definition at line 609 of file Schema.cc.

: _impl(std::make_shared<Impl>()), _aliases(std::make_shared<AliasMap>()) {}

Schema() [2/3]

lsst::afw::table::Schema::Schema

(

Schema const &

other

)

Copy constructor.

Definition at line 611 of file Schema.cc.

: _impl(other._impl), _aliases(other._aliases) {}

Schema() [3/3]

lsst::afw::table::Schema::Schema

(

Schema &&

other

)

Definition at line 613 of file Schema.cc.

: Schema(other) {}

~Schema()

lsst::afw::table::Schema::~Schema ( )

default

Member Function Documentation

addField() [1/3]

template<typename T >

Key< T > lsst::afw::table::Schema::addField	(	Field< T > const &	field,
		bool	doReplace = false
	)

Add a new field to the Schema, and return the associated Key.

The offsets of fields are determined by the order they are added, but may be not contiguous (the Schema may add padding to align fields, and how much padding is considered an implementation detail).

If doReplace is true and the field exists, it will be replaced instead of throwing an exception.

Definition at line 668 of file Schema.cc.

                                                             {
    _edit();
    return _impl->addField(field, doReplace);
}

addField() [2/3]

template<typename T >

Key<T> lsst::afw::table::Schema::addField ( std::string const &  name, std::string const &  doc, std::string const &  units = "", FieldBase< T > const &  base = FieldBase<T>(), bool  doReplace = false  )

inline

Add a new field to the Schema, and return the associated Key.

This is simply a convenience wrapper, equivalent to:

addField(Field<T>(name, doc, units, base), doReplace)

Definition at line 180 of file Schema.h.

                                                                                       {
        return addField(Field<T>(name, doc, units, base), doReplace);
    }

addField() [3/3]

template<typename T >

Key<T> lsst::afw::table::Schema::addField ( std::string const &  name, std::string const &  doc, FieldBase< T > const &  base, bool  doReplace = false  )

inline

Add a new field to the Schema, and return the associated Key.

This is simply a convenience wrapper, equivalent to:

addField(Field<T>(name, doc, base), doReplace)

Definition at line 193 of file Schema.h.

                                            {
        return addField(Field<T>(name, doc, base), doReplace);
    }

compare()

int lsst::afw::table::Schema::compare	(	Schema const &	other,
		int	flags = EQUAL_KEYS
	)		const

Do a detailed equality comparison of two schemas.

See ComparisonFlags for a description of the possible return values

Parameters

[in]	other	The other schema to compare to.
[in]	flags	Which types of comparisions to perform. Flag bits not present here will never be returned.

Definition at line 698 of file Schema.cc.

                                                        {
    int result = contains(other, flags);
    if (_impl->getItems().size() != other._impl->getItems().size()) {
        result &= ~EQUAL_FIELDS;
    }
    if (getAliasMap()->size() != other.getAliasMap()->size()) {
        result &= ~EQUAL_ALIASES;
    }
    return result;
}

contains() [1/2]

int lsst::afw::table::Schema::contains	(	Schema const &	other,
		int	flags = EQUAL_KEYS
	)		const

Test whether the given schema is a subset of this.

This function behaves very similarly to compare(), but ignores fields that are present in this but absent in other.

Definition at line 679 of file Schema.cc.

                                                         {
    if (_impl == other._impl) return flags;
    if (_impl->getItems().size() < other._impl->getItems().size()) return 0;
    int result = flags;
    if (result & EQUAL_FIELDS) {
        for (Impl::ItemContainer::const_iterator i1 = _impl->getItems().begin(),
                                                 i2 = other._impl->getItems().begin();
             i2 != other._impl->getItems().end(); ++i1, ++i2) {
            if ((result & EQUAL_KEYS) && !ItemFunctors::compareKeys(*i1, *i2)) result &= ~EQUAL_KEYS;
            if ((result & EQUAL_NAMES) && !ItemFunctors::compareNames(*i1, *i2)) result &= ~EQUAL_NAMES;
            if ((result & EQUAL_DOCS) && !ItemFunctors::compareDocs(*i1, *i2)) result &= ~EQUAL_DOCS;
            if ((result & EQUAL_UNITS) && !ItemFunctors::compareUnits(*i1, *i2)) result &= ~EQUAL_UNITS;
            if (!result) break;
        }
    }
    if ((result & EQUAL_ALIASES) && !getAliasMap()->contains(*other.getAliasMap())) result &= ~EQUAL_ALIASES;
    return result;
}

contains() [2/2]

template<typename T >

int lsst::afw::table::Schema::contains	(	SchemaItem< T > const &	item,
		int	flags = EQUAL_KEYS
	)		const

Return true if the given item is in this schema.

The flags must include the EQUAL_KEYS bit, and if the item cannot be found by key no bits will be set on return.

Definition at line 718 of file Schema.cc.

                                                               {
    return _impl->contains(item, flags);
}

disconnectAliases()

void lsst::afw::table::Schema::disconnectAliases

(

)

Sever the connection between this schema and any others with which it shares aliases.

Definition at line 729 of file Schema.cc.

{ _aliases = std::make_shared<AliasMap>(*_aliases); }

find() [1/2]

template<typename T >

SchemaItem< T > lsst::afw::table::Schema::find

(

std::string const &

name

)

const

Find a SchemaItem in the Schema by name.

Names corresponding to named subfields are accepted, and will return a SchemaItem whose field is copied from the parent field with only the name changed.

Definition at line 656 of file Schema.cc.

                                                      {
    std::string tmp(name);
    _aliases->_apply(tmp);
    return _impl->find<T>(tmp);
}

find() [2/2]

template<typename T >

SchemaItem< T > lsst::afw::table::Schema::find

(

Key< T > const &

key

)

const

Find a SchemaItem in the Schema by key.

Keys corresponding to named subfields are accepted, and will return a SchemaItem whose field is copied from the parent field with only the name changed. Keys corresponding to unnamed subfields (such as array elements) are not accepted.

Definition at line 663 of file Schema.cc.

                                                  {
    return _impl->find(key);
}

findAndApply()

template<typename F >

void lsst::afw::table::Schema::findAndApply ( std::string const &  name, F &&  func  ) const

inline

Find a SchemaItem by name and run a functor on it.

Names corresponding to named subfields are not accepted. The given functor must have an overloaded function call operator that accepts any SchemaItem type (the same as a functor provided to forEach).

Definition at line 116 of file Schema.h.

                                                             {
        _impl->findAndApply(_aliases->apply(name), std::forward<F>(func));
    }

forEach()

template<typename F >

void lsst::afw::table::Schema::forEach ( F &&  func ) const

inline

Apply a functor to each SchemaItem in the Schema.

The functor must have a templated or sufficiently overloaded operator() that supports SchemaItems of all supported field types - even those that are not present in this particular Schema.

Fields will be processed in the order they were added to the schema.

Definition at line 212 of file Schema.h.

                                 {
        Impl::VisitorWrapper<F> visitor(std::forward<F>(func));
        std::for_each(_impl->getItems().begin(), _impl->getItems().end(), visitor);
    }

fromFitsMetadata()

Schema lsst::afw::table::Schema::fromFitsMetadata ( daf::base::PropertyList &  header, bool  stripMetadata = true  )

static

Construct from reading a FITS header.

If 'stripMetadata', then the header will be modified, removing the relevant keywords.

Definition at line 637 of file Schema.cc.

                                                                               {
    return io::FitsSchemaInputMapper(header, stripMetadata).finalize();
}

getAliasMap()

std::shared_ptr<AliasMap> lsst::afw::table::Schema::getAliasMap ( ) const

inline

Return the map of aliases.

Note that while this is a const method, it does allow the Schema's aliases to be edited - this allows the aliases to be modified even after a Table has been constructed from the Schema.

See AliasMap for more information on schema aliases.

Definition at line 269 of file Schema.h.

{ return _aliases; }

getFieldCount()

int lsst::afw::table::Schema::getFieldCount ( ) const

inline

The total number of fields.

Definition at line 151 of file Schema.h.

{ return _impl->getFieldCount(); }

getFlagFieldCount()

int lsst::afw::table::Schema::getFlagFieldCount ( ) const

inline

The number of Flag fields.

Definition at line 154 of file Schema.h.

{ return _impl->getFlagFieldCount(); }

getNames()

std::set< std::string > lsst::afw::table::Schema::getNames

(

bool

topOnly = false

)

const

Return a set of field names in the schema.

If topOnly==true, return a unique list of only the part of the names before the first underscore. For example, if the full list of field names is ['a_b_c', 'a_d', 'e_f'], topOnly==true will return ['a', 'e'].

Returns an instance of Python's builtin set in Python.

Aliases are not returned.

Definition at line 653 of file Schema.cc.

{ return _impl->getNames(topOnly); }

getNonFlagFieldCount()

int lsst::afw::table::Schema::getNonFlagFieldCount ( ) const

inline

The number of non-Flag fields.

Definition at line 157 of file Schema.h.

{ return _impl->getNonFlagFieldCount(); }

getRecordSize()

int lsst::afw::table::Schema::getRecordSize ( ) const

inline

Return the raw size of a record in bytes.

Definition at line 148 of file Schema.h.

{ return _impl->getRecordSize(); }

hash_value()

std::size_t lsst::afw::table::Schema::hash_value ( ) const

noexcept

Return a hash of this object.

Definition at line 709 of file Schema.cc.

                                            {
    // Completely arbitrary seed
    std::size_t result = 17;
    auto hasher = [&result](auto const &item) { result = utils::hashCombine(result, item.key); };
    forEach(hasher);
    return result;
}

join() [1/3]

std::string lsst::afw::table::Schema::join	(	std::string const &	a,
		std::string const &	b
	)		const

Join strings using the field delimiter appropriate for this Schema.

Definition at line 641 of file Schema.cc.

                                                                   {
    // delegate to utility funcs at top of this file
    return afw::table::join(a, b, getDelimiter());
}

join() [2/3]

std::string lsst::afw::table::Schema::join ( std::string const &  a, std::string const &  b, std::string const &  c  ) const

inline

Join strings using the field delimiter appropriate for this Schema.

Definition at line 77 of file Schema.h.

                                                                                     {
        return join(join(a, b), c);
    }

join() [3/3]

std::string lsst::afw::table::Schema::join ( std::string const &  a, std::string const &  b, std::string const &  c, std::string const &  d  ) const

inline

Join strings using the field delimiter appropriate for this Schema.

Definition at line 80 of file Schema.h.

                                               {
        return join(join(a, b), join(c, d));
    }

operator!=()

bool lsst::afw::table::Schema::operator!= ( Schema const &  other ) const

inline

Equality comparison.

Schemas are considered equal according the standard equality operator if their sequence of keys are identical (same types with the same offsets); names and descriptions of fields are not considered. For a more precise comparison, use compare() or contains().

Definition at line 226 of file Schema.h.

{ return !this->operator==(other); }

operator=() [1/2]

Schema & lsst::afw::table::Schema::operator= ( Schema const &  other )

default

operator=() [2/2]

Schema & lsst::afw::table::Schema::operator= ( Schema &&  other )

default

operator==()

bool lsst::afw::table::Schema::operator== ( Schema const &  other ) const

inline

Equality comparison.

Schemas are considered equal according the standard equality operator if their sequence of keys are identical (same types with the same offsets); names and descriptions of fields are not considered. For a more precise comparison, use compare() or contains().

Definition at line 225 of file Schema.h.

{ return compare(other, EQUAL_KEYS); }

operator[]()

SubSchema lsst::afw::table::Schema::operator[] ( std::string const &  name ) const

inline

Look up a (possibly incomplete) name in the Schema.

See SubSchema for more information.

This member function should generally only be used on "finished" Schemas; modifying a Schema after a SubSchema to it has been constructed will not allow the proxy to track the additions, and will invoke the copy-on-write mechanism of the Schema itself.

Definition at line 454 of file Schema.h.

                                                               {
    return SubSchema(_impl, _aliases, name);
}

readFits() [1/3]

Schema lsst::afw::table::Schema::readFits ( std::string const &  filename, int  hdu = fits::DEFAULT_HDU  )

static

Construct from reading a FITS file.

Reads from the nominated 'hdu' (0=PHU which cannot be a catalog, afw::fits::DEFAULT_HDU is a special value meaning read from the first HDU with NAXIS != 0).

Definition at line 619 of file Schema.cc.

                                                          {
    fits::Fits fp{filename, "r", fits::Fits::AUTO_CLOSE | fits::Fits::AUTO_CHECK};
    fp.setHdu(hdu);
    return readFits(fp);
}

readFits() [2/3]

Schema lsst::afw::table::Schema::readFits ( fits::MemFileManager &  manager, int  hdu = fits::DEFAULT_HDU  )

static

Definition at line 625 of file Schema.cc.

                                                            {
    fits::Fits fp{manager, "r", fits::Fits::AUTO_CLOSE | fits::Fits::AUTO_CHECK};
    fp.setHdu(hdu);
    return readFits(fp);
}

readFits() [3/3]

Schema lsst::afw::table::Schema::readFits ( fits::Fits &  fitsfile )

static

Definition at line 631 of file Schema.cc.

                                          {
    daf::base::PropertyList header;
    fitsfile.readMetadata(header, false);
    return fromFitsMetadata(header);
}

replaceField()

template<typename T >

void lsst::afw::table::Schema::replaceField	(	Key< T > const &	key,
		Field< T > const &	field
	)

Replace the Field (name/description) for an existing Key.

Definition at line 674 of file Schema.cc.

                                                                  {
    _edit();
    _impl->replaceField(key, field);
}

setAliasMap()

void lsst::afw::table::Schema::setAliasMap

(

std::shared_ptr< AliasMap >

aliases

)

Set the alias map.

This resets the internal pointer to the alias map, disconnecting this schema from any others it shares aliases with.

Passing a null pointer is equivalent to passing an empty map.

Definition at line 722 of file Schema.cc.

                                                        {
    if (!aliases) {
        aliases = std::make_shared<AliasMap>();
    }
    _aliases = aliases;
}

Friends And Related Function Documentation

detail::Access

friend class detail::Access

friend

Definition at line 315 of file Schema.h.

operator<<

std::ostream& operator<< ( std::ostream &  os, Schema const &  schema  )

friend

Stringification.

Definition at line 751 of file Schema.cc.

                                                             {
    os << "Schema(\n";
    schema.forEach(Stream(&os));
    for (auto iter = schema.getAliasMap()->begin(); iter != schema.getAliasMap()->end(); ++iter) {
        os << "    '" << iter->first << "'->'" << iter->second << "'\n";
    }
    return os << ")\n";
}

SubSchema

friend class SubSchema

friend

Definition at line 316 of file Schema.h.

Member Data Documentation

VERSION

int const lsst::afw::table::Schema::VERSION = detail::SchemaImpl::VERSION

static

Definition at line 56 of file Schema.h.

---

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

• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/include/lsst/afw/table/Schema.h
• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/src/table/Schema.cc