LSSTApplications  19.0.0-10-g920eed2,19.0.0-11-g48a0200+2,19.0.0-18-gfc4e62b+11,19.0.0-2-g3b2f90d+2,19.0.0-2-gd671419+5,19.0.0-20-g5a5a17ab+9,19.0.0-21-g2644856+11,19.0.0-22-gc5dc5b1+6,19.0.0-23-gdc29a50+3,19.0.0-24-g923e380+11,19.0.0-25-g6c8df7140,19.0.0-28-g9b887e2,19.0.0-3-g2b32d65+5,19.0.0-3-g8227491+10,19.0.0-3-g9c54d0d+10,19.0.0-3-gca68e65+6,19.0.0-3-gcfc5f51+5,19.0.0-3-ge110943+9,19.0.0-3-ge74d124,19.0.0-3-gfe04aa6+11,19.0.0-4-g06f5963+5,19.0.0-4-g3d16501+11,19.0.0-4-g4a9c019+5,19.0.0-4-g5a8b323,19.0.0-4-g66397f0+1,19.0.0-4-g8278b9b+1,19.0.0-4-g8557e14,19.0.0-4-g8964aba+11,19.0.0-4-ge404a01+10,19.0.0-5-g40f3a5a,19.0.0-5-g4db63b3,19.0.0-5-gfb03ce7+11,19.0.0-6-gbaebbfb+10,19.0.0-60-gafafd468+11,19.0.0-67-g3ab1e6e,19.0.0-7-g039c0b5+9,19.0.0-7-gbea9075+4,19.0.0-7-gc567de5+11,19.0.0-8-g3a3ce09+6,19.0.0-9-g463f923+10,w.2020.21
LSSTDataManagementBasePackage
Classes | Public Member Functions | Static Public Member Functions | List of all members
lsst::afw::table::SchemaMapper Class Referencefinal

A mapping between the keys of two Schemas, used to copy data between them. More...

#include <SchemaMapper.h>

Public Member Functions

Schema const getInputSchema () const
 Return the input schema (copy-on-write). More...
 
Schema const getOutputSchema () const
 Return the output schema (copy-on-write). More...
 
SchemaeditOutputSchema ()
 Return a reference to the output schema that allows it to be modified in place. More...
 
template<typename T >
Key< T > addOutputField (Field< T > const &newField, bool doReplace=false)
 Add a new field to the output Schema that is not connected to the input Schema. More...
 
template<typename T >
Key< T > addMapping (Key< T > const &inputKey, bool doReplace=false)
 Add a new field to the output Schema that is a copy of a field in the input Schema. More...
 
template<typename T >
Key< T > addMapping (Key< T > const &inputKey, Field< T > const &outputField, bool doReplace=false)
 Add a new mapped field to the output Schema with new descriptions. More...
 
template<typename T >
Key< T > addMapping (Key< T > const &inputKey, std::string const &outputName, bool doReplace=true)
 Add a new mapped field to the output Schema with a new name. More...
 
template<typename T >
Key< T > addMapping (Key< T > const &inputKey, char const *outputName, bool doReplace=true)=delete
 This deliberately deleted overload ensures we don't accidentally cast string literals to bool. More...
 
template<typename Predicate >
void addMappingsWhere (Predicate predicate, bool doReplace=true)
 Add mappings for all fields that match criteria defined by a predicate. More...
 
void addMinimalSchema (Schema const &minimal, bool doMap=true)
 Add the given minimal schema to the output schema. More...
 
void invert ()
 Swap the input and output schemas in-place. More...
 
template<typename T >
bool isMapped (Key< T > const &inputKey) const
 Return true if the given input Key is mapped to an output Key. More...
 
template<typename T >
Key< T > getMapping (Key< T > const &inputKey) const
 Return the output Key corresponding to the given input Key, or raise NotFoundError. More...
 
template<typename F >
void forEach (F &&func) const
 Call the given functor for each key pair in the mapper. More...
 
 SchemaMapper ()
 Construct an empty mapper; useless unless you assign a fully-constructed one to it. More...
 
 SchemaMapper (Schema const &input, Schema const &output)
 Construct a mapper from the given input Schema and initial output Schema. More...
 
 SchemaMapper (Schema const &input, bool shareAliasMap=false)
 Construct a mapper from the given input Schema. More...
 
 SchemaMapper (SchemaMapper const &other)
 Copy construct (copy-on-write). More...
 
 SchemaMapper (SchemaMapper &&other)
 
SchemaMapperoperator= (SchemaMapper const &other)
 Assignment (copy-on-write). More...
 
SchemaMapperoperator= (SchemaMapper &&other)
 
 ~SchemaMapper ()
 

Static Public Member Functions

static SchemaMapper removeMinimalSchema (Schema const &input, Schema const &minimal)
 Create a mapper by removing fields from the front of a schema. More...
 
static std::vector< SchemaMapperjoin (std::vector< Schema > const &inputs, std::vector< std::string > const &prefixes=std::vector< std::string >())
 Combine a sequence of schemas into one, creating a SchemaMapper for each. More...
 

Detailed Description

A mapping between the keys of two Schemas, used to copy data between them.

SchemaMapper is initialized with its input Schema, and contains member functions to add mapped or unmapped fields to the output Schema.

Definition at line 21 of file SchemaMapper.h.

Constructor & Destructor Documentation

◆ SchemaMapper() [1/5]

lsst::afw::table::SchemaMapper::SchemaMapper ( )
explicit

Construct an empty mapper; useless unless you assign a fully-constructed one to it.

Definition at line 112 of file SchemaMapper.cc.

112 : _impl(new Impl(Schema(), Schema())) {}

◆ SchemaMapper() [2/5]

lsst::afw::table::SchemaMapper::SchemaMapper ( Schema const &  input,
Schema const &  output 
)
explicit

Construct a mapper from the given input Schema and initial output Schema.

Parameters
[in]inputThe Schema that fields will be mapped from.
[in]outputThe starting point for the Schema that fields will be mapped to (no mappings will be created automaticaly). Use addMapping() with doReplace=true to connect input fields to preexisting fields in the output schema.

Note that the addMapping() methods will not connect input schema fields to existing output schema fields unless doReplace=true; instead, these will by default append new fields to the output schema. So most often you'll want to start with an empty output schema and construct it as fields are mapped from the input schema, or be sure to always pass doReplace=true to addMapping.

Definition at line 118 of file SchemaMapper.cc.

118 : _impl(new Impl(input, output)) {}

◆ SchemaMapper() [3/5]

lsst::afw::table::SchemaMapper::SchemaMapper ( Schema const &  input,
bool  shareAliasMap = false 
)
explicit

Construct a mapper from the given input Schema.

Parameters
[in]inputThe Schema that fields will be mapped from.
[in]shareAliasMapIf true, install the input Schema's AliasMap in the output Schema.

Note that the addMapping() methods will not connect input schema fields to existing output schema fields unless doReplace=true; instead, these will by default append new fields to the output schema. So most often you'll want to start with an empty output schema and construct it as fields are mapped from the input schema, or be sure to always pass doReplace=true to addMapping.

The initial (empty) output schema will have the same version as the input schema, and they will share the same AliasMap (use editOutputSchema().disconnectAliases() to use a copy of the AliasMap).

Definition at line 120 of file SchemaMapper.cc.

120  : _impl(new Impl(input, Schema())) {
121  if (shareAliasMap) {
122  editOutputSchema().setAliasMap(input.getAliasMap());
123  }
124 }

◆ SchemaMapper() [4/5]

lsst::afw::table::SchemaMapper::SchemaMapper ( SchemaMapper const &  other)

Copy construct (copy-on-write).

Definition at line 114 of file SchemaMapper.cc.

114 : _impl(new Impl(*other._impl)) {}

◆ SchemaMapper() [5/5]

lsst::afw::table::SchemaMapper::SchemaMapper ( SchemaMapper &&  other)

Definition at line 116 of file SchemaMapper.cc.

116 : SchemaMapper(other) {}

◆ ~SchemaMapper()

lsst::afw::table::SchemaMapper::~SchemaMapper ( )
default

Member Function Documentation

◆ addMapping() [1/4]

template<typename T >
Key< T > lsst::afw::table::SchemaMapper::addMapping ( Key< T > const &  inputKey,
bool  doReplace = false 
)

Add a new field to the output Schema that is a copy of a field in the input Schema.

If the input Key has already been mapped, the existing output Key will be reused but the associated Field in the output Schema will be reset to a copy of the input Field.

If doReplace=True and a field with same name already exists in the output schema, that field will be mapped instead of adding a new field to the output schema. If doReplace=false and a name conflict occurs, an exception will be thrown.

Definition at line 137 of file SchemaMapper.cc.

137  {
138  typename Impl::KeyPairMap::iterator i =
139  std::find_if(_impl->_map.begin(), _impl->_map.end(), KeyPairCompareEqual<T>(inputKey));
140  Field<T> inputField = _impl->_input.find(inputKey).field;
141  if (i != _impl->_map.end()) {
142  Key<T> const &outputKey = boost::get<std::pair<Key<T>, Key<T> > >(*i).second;
143  _impl->_output.replaceField(outputKey, inputField);
144  return outputKey;
145  } else {
146  Key<T> outputKey = _impl->_output.addField(inputField, doReplace);
147  _impl->_map.insert(i, std::make_pair(inputKey, outputKey));
148  return outputKey;
149  }
150 }

◆ addMapping() [2/4]

template<typename T >
Key<T> lsst::afw::table::SchemaMapper::addMapping ( Key< T > const &  inputKey,
char const *  outputName,
bool  doReplace = true 
)
delete

This deliberately deleted overload ensures we don't accidentally cast string literals to bool.

See DM-13787 for more information.

◆ addMapping() [3/4]

template<typename T >
Key< T > lsst::afw::table::SchemaMapper::addMapping ( Key< T > const &  inputKey,
Field< T > const &  outputField,
bool  doReplace = false 
)

Add a new mapped field to the output Schema with new descriptions.

If the input Key has already been mapped, the existing output Key will be reused but the associated Field will be replaced with the given one.

If doReplace=True and a field with same name already exists in the output schema, that field will be mapped instead of adding a new field to the output schema. If doReplace=false and a name conflict occurs, an exception will be thrown.

Definition at line 153 of file SchemaMapper.cc.

153  {
154  typename Impl::KeyPairMap::iterator i =
155  std::find_if(_impl->_map.begin(), _impl->_map.end(), KeyPairCompareEqual<T>(inputKey));
156  if (i != _impl->_map.end()) {
157  Key<T> const &outputKey = boost::get<std::pair<Key<T>, Key<T> > >(*i).second;
158  _impl->_output.replaceField(outputKey, field);
159  return outputKey;
160  } else {
161  Key<T> outputKey = _impl->_output.addField(field, doReplace);
162  _impl->_map.insert(i, std::make_pair(inputKey, outputKey));
163  return outputKey;
164  }
165 }

◆ addMapping() [4/4]

template<typename T >
Key< T > lsst::afw::table::SchemaMapper::addMapping ( Key< T > const &  inputKey,
std::string const &  outputName,
bool  doReplace = true 
)

Add a new mapped field to the output Schema with a new name.

If the input Key has already been mapped, the existing output Key will be reused but the associated Field will be replaced with one with the given name.

If doReplace=True and a field with same name already exists in the output schema, that field will be mapped instead of adding a new field to the output schema. If doReplace=false and a name conflict occurs, an exception will be thrown.

Definition at line 168 of file SchemaMapper.cc.

168  {
169  typename Impl::KeyPairMap::iterator i =
170  std::find_if(_impl->_map.begin(), _impl->_map.end(), KeyPairCompareEqual<T>(inputKey));
171  if (i != _impl->_map.end()) {
172  Key<T> const &outputKey = boost::get<std::pair<Key<T>, Key<T> > >(*i).second;
173  Field<T> field = _impl->_output.find(outputKey).field;
174  field = field.copyRenamed(outputName);
175  _impl->_output.replaceField(outputKey, field);
176  return outputKey;
177  } else {
178  Field<T> inputField = _impl->_input.find(inputKey).field;
179  Field<T> outputField = inputField.copyRenamed(outputName);
180  Key<T> outputKey = _impl->_output.addField(outputField, doReplace);
181  _impl->_map.insert(i, std::make_pair(inputKey, outputKey));
182  return outputKey;
183  }
184 }

◆ addMappingsWhere()

template<typename Predicate >
void lsst::afw::table::SchemaMapper::addMappingsWhere ( Predicate  predicate,
bool  doReplace = true 
)

Add mappings for all fields that match criteria defined by a predicate.

A mapping in the output Schema will be created for each SchemaItem 'i' in the input Schema such that 'predicate(i)' is true. Note that the predicate must have a templated and/or sufficiently overloaded operator() to match all supported field types, not just those present in the input Schema.

If doReplace=True and a field with same name already exists in the output schema, that field will be mapped instead of adding a new field to the output schema. If doReplace=false and a name conflict occurs, an exception will be thrown.

Definition at line 238 of file SchemaMapper.h.

238  {
239  _impl->_input.forEach(AddMappingsWhere<Predicate>(this, predicate, doReplace));
240 }

◆ addMinimalSchema()

void lsst::afw::table::SchemaMapper::addMinimalSchema ( Schema const &  minimal,
bool  doMap = true 
)

Add the given minimal schema to the output schema.

This is intended to be used to ensure the output schema starts with some minimal schema. It must be called before any other fields are added to the output schema.

Parameters
[in]minimalMinimal schema to be added to the beginning of the output schema.
[in]doMapWhether to map minimal schema fields that are also present in the input schema.

Definition at line 186 of file SchemaMapper.cc.

186  {
187  if (getOutputSchema().getFieldCount() > 0) {
188  throw LSST_EXCEPT(pex::exceptions::LogicError,
189  "Must add minimal schema to mapper before adding any other fields");
190  }
191  MapMinimalSchema f(this, doMap);
192  minimal.forEach(f);
193 }

◆ addOutputField()

template<typename T >
Key<T> lsst::afw::table::SchemaMapper::addOutputField ( Field< T > const &  newField,
bool  doReplace = false 
)
inline

Add a new field to the output Schema that is not connected to the input Schema.

Definition at line 34 of file SchemaMapper.h.

34  {
35  return _impl->_output.addField(newField, doReplace);
36  }

◆ editOutputSchema()

Schema& lsst::afw::table::SchemaMapper::editOutputSchema ( )
inline

Return a reference to the output schema that allows it to be modified in place.

Definition at line 30 of file SchemaMapper.h.

30 { return _impl->_output; }

◆ forEach()

template<typename F >
void lsst::afw::table::SchemaMapper::forEach ( F &&  func) const
inline

Call the given functor for each key pair in the mapper.

Function objects should have a template and/or overloaded operator() that takes two Key objects with the same type:

struct Functor {
    template <typename T>
    void operator()(Key<T> const & input, Key<T> const & output) const;
};

The order of iteration is the same as the order in which mappings were added.

Definition at line 149 of file SchemaMapper.h.

149  {
150  Impl::VisitorWrapper<F> visitor(std::forward<F>(func));
151  std::for_each(_impl->_map.begin(), _impl->_map.end(), visitor);
152  }

◆ getInputSchema()

Schema const lsst::afw::table::SchemaMapper::getInputSchema ( ) const
inline

Return the input schema (copy-on-write).

Definition at line 24 of file SchemaMapper.h.

24 { return _impl->_input; }

◆ getMapping()

template<typename T >
Key< T > lsst::afw::table::SchemaMapper::getMapping ( Key< T > const &  inputKey) const

Return the output Key corresponding to the given input Key, or raise NotFoundError.

Definition at line 213 of file SchemaMapper.cc.

213  {
214  typename Impl::KeyPairMap::iterator i =
215  std::find_if(_impl->_map.begin(), _impl->_map.end(), KeyPairCompareEqual<T>(inputKey));
216  if (i == _impl->_map.end()) {
217  throw LSST_EXCEPT(lsst::pex::exceptions::NotFoundError, "Input Key is not mapped.");
218  }
219  return boost::get<std::pair<Key<T>, Key<T> > >(*i).second;
220 }

◆ getOutputSchema()

Schema const lsst::afw::table::SchemaMapper::getOutputSchema ( ) const
inline

Return the output schema (copy-on-write).

Definition at line 27 of file SchemaMapper.h.

27 { return _impl->_output; }

◆ invert()

void lsst::afw::table::SchemaMapper::invert ( )

Swap the input and output schemas in-place.

Definition at line 202 of file SchemaMapper.cc.

202  {
203  std::swap(_impl->_input, _impl->_output);
204  std::for_each(_impl->_map.begin(), _impl->_map.end(), SwapKeyPair());
205 }

◆ isMapped()

template<typename T >
bool lsst::afw::table::SchemaMapper::isMapped ( Key< T > const &  inputKey) const

Return true if the given input Key is mapped to an output Key.

Definition at line 208 of file SchemaMapper.cc.

208  {
209  return std::count_if(_impl->_map.begin(), _impl->_map.end(), KeyPairCompareEqual<T>(inputKey));
210 }

◆ join()

std::vector< SchemaMapper > lsst::afw::table::SchemaMapper::join ( std::vector< Schema > const &  inputs,
std::vector< std::string > const &  prefixes = std::vector<std::string>() 
)
static

Combine a sequence of schemas into one, creating a SchemaMapper for each.

Parameters
[in]inputsA vector of input schemas to merge.
[in]prefixesAn optional vector of prefixes for the output field names, either empty or of the same size as the inputs vector.

Each of the returned SchemaMappers has the same output schema.

Definition at line 222 of file SchemaMapper.cc.

223  {
224  std::size_t const size = inputs.size();
225  if (!prefixes.empty() && prefixes.size() != inputs.size()) {
226  throw LSST_EXCEPT(
227  pex::exceptions::LengthError,
228  (boost::format("prefix vector size (%d) must be the same as input vector size (%d)") %
229  prefixes.size() % inputs.size())
230  .str());
231  }
233  for (std::size_t i = 0; i < size; ++i) {
234  result.push_back(SchemaMapper(inputs[i]));
235  }
236  for (std::size_t i = 0; i < size; ++i) {
237  for (std::size_t j = 0; j < size; ++j) {
238  if (i == j) {
239  AddMapped functor(&result[j]);
240  if (!prefixes.empty()) functor.prefix = prefixes[i];
241  inputs[i].forEach(functor);
242  } else {
243  AddUnmapped functor(&result[j]);
244  if (!prefixes.empty()) functor.prefix = prefixes[i];
245  inputs[i].forEach(functor);
246  }
247  }
248  }
249  return result;
250 }

◆ operator=() [1/2]

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

Definition at line 132 of file SchemaMapper.cc.

132 { return *this = other; }

◆ operator=() [2/2]

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

Assignment (copy-on-write).

Definition at line 126 of file SchemaMapper.cc.

126  {
127  std::unique_ptr<Impl> tmp(new Impl(*other._impl));
128  _impl.swap(tmp);
129  return *this;
130 }

◆ removeMinimalSchema()

SchemaMapper lsst::afw::table::SchemaMapper::removeMinimalSchema ( Schema const &  input,
Schema const &  minimal 
)
static

Create a mapper by removing fields from the front of a schema.

The returned mapper maps all fields in the input schema to all fields that are not in the minimal schema (compared by keys, so the overlap must appear at the beginning of the input schema).

Parameters
[in]inputInput schema for the mapper.
[in]minimalThe minimal schema the input schema starts with.

Definition at line 195 of file SchemaMapper.cc.

195  {
196  SchemaMapper mapper(input);
197  RemoveMinimalSchema f(&mapper, minimal);
198  input.forEach(f);
199  return mapper;
200 }

The documentation for this class was generated from the following files:
std::for_each
T for_each(T... args)
lsst::afw::table::Schema::addField
Key< T > addField(Field< T > const &field, bool doReplace=false)
Add a new field to the Schema, and return the associated Key.
Definition: Schema.cc:668
std::vector
STL class.
std::find_if
T find_if(T... args)
std::vector::size
T size(T... args)
lsst::pex::exceptions::NotFoundError
Reports attempts to access elements using an invalid key.
Definition: Runtime.h:151
pex.config.history.format
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174
lsst::afw::table::SchemaMapper::editOutputSchema
Schema & editOutputSchema()
Return a reference to the output schema that allows it to be modified in place.
Definition: SchemaMapper.h:30
lsst::afw::table::Schema::forEach
void forEach(F &&func) const
Apply a functor to each SchemaItem in the Schema.
Definition: Schema.h:212
minimal
Schema minimal
Definition: SchemaMapper.cc:107
lsst::afw::table::Schema::find
SchemaItem< T > find(std::string const &name) const
Find a SchemaItem in the Schema by name.
Definition: Schema.cc:656
other
ItemVariant const * other
Definition: Schema.cc:56
field
table::Key< int > field
Definition: ApCorrMap.cc:77
lsst::afw::table::Schema::setAliasMap
void setAliasMap(std::shared_ptr< AliasMap > aliases)
Set the alias map.
Definition: Schema.cc:722
lsst::afw::table::SchemaMapper::SchemaMapper
SchemaMapper()
Construct an empty mapper; useless unless you assign a fully-constructed one to it.
Definition: SchemaMapper.cc:112
result
py::object result
Definition: _schema.cc:429
LSST_EXCEPT
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
std::swap
T swap(T... args)
std::vector::begin
T begin(T... args)
std::vector::insert
T insert(T... args)
lsst::afw::table::SchemaMapper::getOutputSchema
Schema const getOutputSchema() const
Return the output schema (copy-on-write).
Definition: SchemaMapper.h:27
std::count_if
T count_if(T... args)
mapper
SchemaMapper * mapper
Definition: SchemaMapper.cc:78
std::vector::empty
T empty(T... args)
std::size_t
std::make_pair
T make_pair(T... args)
std::vector::end
T end(T... args)
std::unique_ptr< Impl >
lsst::afw::table::Schema::replaceField
void replaceField(Key< T > const &key, Field< T > const &field)
Replace the Field (name/description) for an existing Key.
Definition: Schema.cc:674