LSSTApplications  10.0-2-g4f67435,11.0.rc2+1,11.0.rc2+12,11.0.rc2+3,11.0.rc2+4,11.0.rc2+5,11.0.rc2+6,11.0.rc2+7,11.0.rc2+8
LSSTDataManagementBasePackage
Public Types | Public Member Functions | Static Public Attributes | Private Types | Private Member Functions | Private Attributes | Friends | List of all members
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...
 
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...
 
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...
 
boost::shared_ptr< AliasMapgetAliasMap () const
 
void setAliasMap (boost::shared_ptr< AliasMap > aliases)
 
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...
 
daf::base::CitizengetCitizen ()
 Get the Citizen corresponding to this Schema (SchemaImpl is what inherits from Citizen). More...
 
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 Attributes

static int const VERSION = detail::SchemaImpl::VERSION
 

Private Types

typedef detail::SchemaImpl Impl
 

Private Member Functions

void _edit ()
 Copy on write; should be called by all mutators (except for alias mutators). More...
 

Private Attributes

boost::shared_ptr< Impl_impl
 
boost::shared_ptr< AliasMap_aliases
 

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 dot-separated names (e.g. 'a.b.c'). 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 periods, 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 46 of file Schema.h.

Member Typedef Documentation

Definition at line 47 of file Schema.h.

Member Enumeration Documentation

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 60 of file Schema.h.

60  {
61  EQUAL_KEYS =0x01,
62  EQUAL_NAMES =0x02,
63  EQUAL_DOCS =0x04,
64  EQUAL_UNITS =0x08,
65  EQUAL_FIELDS =0x0F,
66  EQUAL_ALIASES =0x10,
67  IDENTICAL =0x1F
68  };
Keys have the same types offsets, and sizes.
Definition: Schema.h:61
Schemas have identical AliasMaps.
Definition: Schema.h:66
Fields have the same names (ordered).
Definition: Schema.h:62
Everything is the same.
Definition: Schema.h:67
Fields are identical (but aliases may not be).
Definition: Schema.h:65
Fields have the same documentation (ordered).
Definition: Schema.h:63
Fields have the same units (ordered).
Definition: Schema.h:64

Constructor & Destructor Documentation

lsst.afw.table::Schema::Schema ( )

Construct an empty Schema.

lsst.afw.table::Schema::Schema ( Schema const &  other)

Copy constructor.

Member Function Documentation

void lsst.afw.table::Schema::_edit ( )
private

Copy on write; should be called by all mutators (except for alias mutators).

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.

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 165 of file Schema.h.

168  {
169  return addField(Field<T>(name, doc, units, base), doReplace);
170  }
table::Key< std::string > name
Definition: ApCorrMap.cc:71
Key< T > addField(Field< T > const &field, bool doReplace=false)
Add a new field to the Schema, and return the associated Key.
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 181 of file Schema.h.

184  {
185  return addField(Field<T>(name, doc, base), doReplace);
186  }
table::Key< std::string > name
Definition: ApCorrMap.cc:71
Key< T > addField(Field< T > const &field, bool doReplace=false)
Add a new field to the Schema, and return the associated Key.
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]otherThe other schema to compare to.
[in]flagsWhich types of comparisions to perform. Flag bits not present here will never be returned.
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.

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.

void lsst.afw.table::Schema::disconnectAliases ( )

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

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.

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.

template<typename F >
void lsst.afw.table::Schema::forEach ( 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.

The functor will be passed by value by default; use boost::ref to pass it by reference.

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

Definition at line 204 of file Schema.h.

204  {
205  Impl::VisitorWrapper<typename boost::unwrap_reference<F>::type &> visitor(func);
206  std::for_each(_impl->getItems().begin(), _impl->getItems().end(), visitor);
207  }
boost::shared_ptr< Impl > _impl
Definition: Schema.h:293
boost::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 258 of file Schema.h.

258 { return _aliases; }
boost::shared_ptr< AliasMap > _aliases
Definition: Schema.h:294
daf::base::Citizen& lsst.afw.table::Schema::getCitizen ( )
inline

Get the Citizen corresponding to this Schema (SchemaImpl is what inherits from Citizen).

Definition at line 283 of file Schema.h.

283 { return *_impl; }
boost::shared_ptr< Impl > _impl
Definition: Schema.h:293
int lsst.afw.table::Schema::getFieldCount ( ) const
inline

The total number of fields.

Definition at line 135 of file Schema.h.

135 { return _impl->getFieldCount(); }
boost::shared_ptr< Impl > _impl
Definition: Schema.h:293
int lsst.afw.table::Schema::getFlagFieldCount ( ) const
inline

The number of Flag fields.

Definition at line 138 of file Schema.h.

138 { return _impl->getFlagFieldCount(); }
boost::shared_ptr< Impl > _impl
Definition: Schema.h:293
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 period. 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.

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

The number of non-Flag fields.

Definition at line 141 of file Schema.h.

141 { return _impl->getNonFlagFieldCount(); }
boost::shared_ptr< Impl > _impl
Definition: Schema.h:293
int lsst.afw.table::Schema::getRecordSize ( ) const
inline

Return the raw size of a record in bytes.

Definition at line 132 of file Schema.h.

132 { return _impl->getRecordSize(); }
boost::shared_ptr< Impl > _impl
Definition: Schema.h:293
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.

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 73 of file Schema.h.

73  {
74  return join(join(a, b), c);
75  }
std::string join(std::string const &a, std::string const &b) const
Join strings using the field delimiter appropriate for this Schema.
afw::table::Key< double > b
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 76 of file Schema.h.

78  {
79  return join(join(a, b), join(c, d));
80  }
std::string join(std::string const &a, std::string const &b) const
Join strings using the field delimiter appropriate for this Schema.
afw::table::Key< double > b
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 218 of file Schema.h.

218 { return !this->operator==(other); }
bool operator==(Schema const &other) const
Equality comparison.
Definition: Schema.h:217
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 217 of file Schema.h.

217 { return compare(other, EQUAL_KEYS); }
Keys have the same types offsets, and sizes.
Definition: Schema.h:61
int compare(Schema const &other, int flags=EQUAL_KEYS) const
Do a detailed equality comparison of two schemas.
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 381 of file Schema.h.

381  {
382  return SubSchema(_impl, _aliases, name);
383 }
friend class SubSchema
Definition: Schema.h:288
boost::shared_ptr< AliasMap > _aliases
Definition: Schema.h:294
table::Key< std::string > name
Definition: ApCorrMap.cc:71
boost::shared_ptr< Impl > _impl
Definition: Schema.h:293
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.

void lsst.afw.table::Schema::setAliasMap ( boost::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.

Friends And Related Function Documentation

friend class detail::Access
friend

Definition at line 287 of file Schema.h.

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

Stringification.

friend class SubSchema
friend

Definition at line 288 of file Schema.h.

Member Data Documentation

boost::shared_ptr< AliasMap > lsst.afw.table::Schema::_aliases
private

Definition at line 294 of file Schema.h.

boost::shared_ptr< Impl > lsst.afw.table::Schema::_impl
private

Definition at line 293 of file Schema.h.

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

Definition at line 52 of file Schema.h.


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