Sheaf

Overview

The sheaf is the datastructure returned by the "SELECT (ALL|FOCUS) OBJECTS" query. See the MQL User's Guide Chapter 4 for a description of the sheaf.

Briefly, a sheaf is a list of straws. A straw is a list of matched_objects. A matched_object may have an inner sheaf, which makes the datastructure recursive.

A matched_object corresponds to an object_block(_first) or (opt_)gap_block in a topographic MQL query. A straw corresponds to a block_string. A sheaf corresponds to a blocks.

A matched_object may be one of two kinds:

• kMOKID_D : Match of object_block(_first)
• kMOKID_M : Match of (opt_)gap_block

Use the getKind() method to find out which it is, if you don't already know from the query.

A matched_object contains the following information:

• An eMOKind enumeration (either kMOKID_D or KMOKID_M)
• An id_d (valid if the eMOKind enumeration is kMOKID_D)
• An object type (valid if the eMOKind enumeration is kMOKID_D)
• A set of monads (always valid)
• A focus boolean (always valid)
• A "marks" string (always valid, but may be empty)
• An inner sheaf (always valid)
• A vector of EMdFValue values, non-empty if the object block had a GET clause.

Java-style iterators are provided.

C++ interface

#include <mql_sheaf.h>


typedef enum { 
  kMOKNIL_mo,   // Used only while building sheaf, never in finished sheaf
  kMOKEMPTY_mo, // Used only while building sheaf, never in finished sheaf
  kMOKID_D,     // Match of object_block(_first)
  kMOKID_M      // Match of (opt_)gap_block
} eMOKind;

class MatchedObject {
public:  
  MatchedObject(const MatchedObject& other);
  ~MatchedObject();
  const SetOfMonads& getMonads(void) const;
  id_d_t getID_D(void) const;
  const Sheaf* getSheaf(void) const;
  bool sheafIsEmpty(void) const;
  eMOKind getKind(void) const;
  /** Return true if this is an ID_M.
   *
   * @return \p true if this is an ID_M matched object,
   * \p false if it is an ID_D matched object.
   */
  bool isID_M(void) const;
  /** Return true if this is an ID_D.
   *
   * @return \p true if this is an ID_D matched object,
   * \p false if it is an ID_M matched object.
   */
  bool isID_D(void) const;
  /** Return true if the block from which this came had the FOCUS keyword.
   *
   * @return \p true if this matched object is in FOCUS,
   * \p false otherwise.
   */
  bool getFocus(void) const;
   /* Return the mark string (given in the query with a backping
    * ("`"), right after the object type in an object_block, or
    * right after "[gap?" or "[gap".
    *
    * Can be called for all types of MatchedObjects, but will return "" (the
    * empty string) if either there is no mark, or it is an EMPTY_MO.
    *
    * @return the mark string, including the backping.
    */
  std::string getMarkString() const;
  MatchedObject& operator=(const MatchedObject& other); // Not SWIG-wrapped
  short int getObjectTypeIndex(void) const;

  // A convenience function for getEMdFValue.
  //
  // Returns a string representation of the given EMdFValue.
  // Integers and ID_Ds are returned as their base-10 representation.
  // Strings are returned as-is.
  // Enums are returned as their string name, not their integer value.
  // Lists of integers are returned as a comma-separated list of
  // the base-10 representation of the integers involved, surrounded by
  // parentheses.
  // Lists of id_ds are returned like lists of integers.
  //
  // Always returns a string, so long as the index parameter is in range.
  //
  // Throws an EmdrosException if index out of range.
  std::string getFeatureAsString(int index) const;

  // A convenience function for getEMdFValue.
  //
  // Returns the "long" value of the given EMdFValue, if possible.
  //
  // Only features that are integers, id_ds, or enums return a value.
  // All others will throw an EmdrosException.
  //
  // Integers and id_ds are returned as is.
  // Enums are returned by their integer value, not their string name.
  //
  // Throws an EmdrosException if index out of range.
  long getFeatureAsLong(int index) const;

  // Get enum label from an index into the EMdFValue vector
  std::string getEnumLabel(int index) const;

  // Returns 0 on index out of range.
  // Is the fastest
  const EMdFValue *getEMdFValue(int index) const;

  // Returns 0 on index out of range.
  // Is slow.
  const EMdFValue *getEMdFValue(const std::string& feature_name) const; 

  // Get the index of a feature name to be used for 
  // getEMdFValue(short int index).
  // Returns -1 on not found
  int getEMdFValueIndex(const std::string& feature_name) const;


  // Get list of feature-names in the order in which they appear in
  // the value vector.  Thus this list can be used as a basis for
  // getting the indexes of the EMdFValues to be used with
  // MatchedObject::getEMdFValue().
  StringList getFeatureList(void) const;

  // Get number of values in list of EMdFValue's.
  unsigned int getNoOfEMdFValues(void) const;

  // Get name of object type for this MatchedObject (may be pow_m).
  std::string getObjectTypeName() const;

  void printConsole(EMdFOutput *pOut) const;
  void printXML(EMdFOutput* pOut) const;

  // See Sheaf::getSOM() for an explanation
  void getSOM(SetOfMonads& som, bool bUseOnlyFocusObjects) const;

  // See Sheaf::countObjects() for an explanation.
  long countObjects(bool bUseOnlyFocusObjects) const;

  // See Sheaf::countObjectsFromObjectType() for an explanation.
  long countObjectsFromObjectType(const std::string& object_type_name, bool bUseOnlyFocusObjects) const;

  // See Sheaf::countStraws() for an explanation.
  long countStraws() const;
  

};

class StrawConstIterator {
public:
  StrawConstIterator(const Straw *pMotherStraw);
  StrawConstIterator();
  StrawConstIterator(const StrawConstIterator& other);
  ~StrawConstIterator();
  bool hasNext() const; // Is the iterator == end iterator?  Doesn't alter iterator
  const MatchedObject* next(); // Gets current and advances iterator afterwards
  const MatchedObject* previous(); // Regresses iterator and then gets current
  const MatchedObject* current(); // Gets current without altering iterator
};

class Straw {
private:
  friend class StrawConstIterator;
  monad_m m_last;
  MOList m_list;
public:
  ~Straw();
  Straw(const Straw& other);
  StrawConstIterator const_iterator() const;
  Straw& operator=(const Straw& other); // Not SWIG-wrapped
  monad_m getLast(void) const { return m_last; };
  void printConsole(EMdFOutput *pOut) const;
  void printXML(EMdFOutput* pOut) const;

  // See Sheaf::countObjects() for an explanation.
  long countObjects(bool bUseOnlyFocusObjects) const;

  // See Sheaf::countObjectsFromObjectType() for an explanation.
  long countObjectsFromObjectType(const std::string& object_type_name, bool bUseOnlyFocusObjects) const;

  // See Sheaf::countStraws() for an explanation.
  long countStraws() const;

  // See Sheaf::getSOM() for an explanation
  void getSOM(SetOfMonads& som, bool bUseOnlyFocusObjects) const;
};

class SheafIterator {
public:
  SheafIterator(ListOfStraws *pMotherList);
  SheafIterator();
  SheafIterator(const SheafIterator& other);
  ~SheafIterator();
  bool hasNext() const; // Is the iterator == end iterator?  Doesn't alter iterator
  Straw* next(); // Gets current and advances iterator afterwards
  Straw* previous(); // Regresses iterator and then gets current
  Straw* current(); // Gets current without altering iterator
};



class SheafConstIterator {
public:
  SheafConstIterator(const ListOfStraws *pMotherList);
  SheafConstIterator();
  SheafConstIterator(const SheafConstIterator& other);
  ~SheafConstIterator();
  bool hasNext() const; // Is the iterator == end iterator?  Doesn't alter iterator
  const Straw* next(); // Gets current and advances iterator afterwards
  const Straw* previous(); // Regresses iterator and then gets current
  const Straw* current(); // Gets current without altering iterator
};



class ListOfStraws {
public:
  ~ListOfStraws();
  ListOfStraws(const ListOfStraws& other);
  SheafIterator iterator();
  SheafConstIterator const_iterator() const;
  bool isEmpty() const;
  void printConsole(EMdFOutput *pOut) const;
  void printXML(EMdFOutput* pOut) const;
};

class Sheaf {
public:
  Sheaf(const Sheaf& other);
  ~Sheaf();
  bool isFail(void) const;
  SheafIterator iterator();
  SheafConstIterator const_iterator() const;
  const ListOfStraws* get_plist(void) const { return m_plist; };
  Sheaf& operator=(const Sheaf& other); // Not SWIG-wrapped
  void printConsole(EMdFOutput *pOut) const;
  void printXML(EMdFOutput* pOut) const;
  // out sheaf's contribution to DTD
  static void printDTD(EMdFOutput* pOut);

  // Count the objects inside the sheaf.  If bUseOnlyFocusObjects is true,
  // only those MatchedObjects whose FOCUS boolean is true are added to the
  // count.
  //
  // The algorithm counts recursively throughout the sheaf, into the innermost
  // sheaves.
  long countObjects(bool bUseOnlyFocusObjects) const;

  // Count the objects inside the sheaf with a given object type name.
  //
  // If object_type_name is empty, all object types are counted.
  //
  // If object_type_name is "pow_m", only gap_blocks and opt_gap_blocks are
  // counted.
  //
  // If object_type_name is neither empty nor "pow_m", only objects of the
  // given object type are counted.
  //
  // The object_type_name parameter should be passed through the
  // std::string normalizeOTName(const std::string& object_type_name)
  // function before passing it as a parameter.
  //
  // If bUseOnlyFocusObjects is true, only those MatchedObjects whose
  // FOCUS boolean is true are added to the count.
  //
  // The algorithm counts recursively throughout the sheaf, into the innermost
  // sheaves.
  long countObjectsFromObjectType(const std::string& object_type_name, bool bUseOnlyFocusObjects) const;

  // See Sheaf::countStraws() for an explanation.
  long countStraws() const;


  // Gets big-union of sets of monads in sheaf's matched_objects. 
  // This is done recursively through all straws and inner sheafs.
  //
  // If  bUseOnlyFocusObjects is true, only matched_objects with their
  // focus boolean set to true will be included. Otherwise, all matched_objects
  // are considered. 

  // The method makes no distinction between matched_objects arising from 
  // (opt-)gap-blocks and object blocks.
  //
  // You should probably start with an empty set of monads unless you
  // want to include monads that are not in the sheaf.
  virtual void getSOM(SetOfMonads& som, bool bUseOnlyFocusObjects) const;

  // Here is a version which starts with an empty set and returns the result
  // rather than passing it as a parameter.
  virtual SetOfMonads getSOM(bool bUseOnlyFocusObjects) const;
};


////////////////////////////////////////////////////////////////
//
// Flat sheaf
//
////////////////////////////////////////////////////////////////

class FlatStraw {
public:
  FlatStraw(const std::string& object_type_name);
  ~FlatStraw();
  FlatStrawConstIterator const_iterator(void) const;
  void addMO(const MatchedObject *pMO);
  void printConsole(EMdFOutput *pOut) const;
  void printXML(EMdFOutput* pOut) const;
  std::string getObjectTypeName(void) const;
};

class FlatStrawConstIterator {
public:
  FlatStrawConstIterator();
  FlatStrawConstIterator(const FlatStrawConstIterator& other);
  ~FlatStrawConstIterator() {};
  bool hasNext() const; // Is the iterator == end iterator?  Doesn't alter iterator
  MatchedObject *next(); // Gets current and advances iterator afterwards
  MatchedObject *current(); // Gets current without altering iterator
};




class FlatSheafConstIterator {
public:
  FlatSheafConstIterator();
  FlatSheafConstIterator(const FlatSheafConstIterator& other);
  ~FlatSheafConstIterator();
  bool hasNext() const; // Is the iterator == end iterator?  Doesn't alter iterator
  FlatStraw* next(); // Gets current and advances iterator afterwards
  FlatStraw* current(); // Gets current without altering iterator
};

class FlatSheaf {
public:
  FlatSheaf(); // For "all" object types
  // For only a select few -- isn't SWIG-wrapped
  FlatSheaf(const std::list<std::pair<id_d_t, std::string> >& object_types); 
  ~FlatSheaf();
  bool isFail(void) const { return m_bIsFail; };
  void printConsole(EMdFOutput *pOut) const;
  void printXML(EMdFOutput* pOut) const;
  static void printDTD(EMdFOutput *pOut);
  FlatSheafConstIterator const_iterator(void) const;
};


// For all object types in the sheaf. 
// Is not SWIG-wrapped. Use the interface in 
// MQLResult instead.
extern FlatSheaf *mql_flatten_sheaf(const Sheaf *pSheaf); 

// Only for certain object types
// Is not SWIG-wrapped. Use the interface in 
// MQLResult instead.
extern FlatSheaf *mql_flatten_sheaf(StringList *pObjectTypeNames, EMdFDB *pDB, 
                                  const Sheaf *pSheaf);

// Only for certain object types
// Is not SWIG-wrapped. Use the interface in 
// MQLResult instead.
extern FlatSheaf *mql_flatten_sheaf(StringList *pObjectTypeNames, EmdrosEnv *pEnv, 
                                  const Sheaf *pSheaf);

Example

The iterators are used like this:

  Sheaf *pSheaf; // Assumed to be initialized from somewhere
  SheafConstIterator sci = pSheaf->const_iterator();
  while (sci.hasNext()) {
    const Straw *pStraw = sci.current();
   
    // Process pStraw ...

    sci.next();
  }

  // Or like this:
  SheafIterator si = pSheaf->iterator();
  while (si.hasNext()) {
    Straw *pStraw = si.next();
   
    // Process pStraw ...

    // Note how there is no si.next() again, since next() 
    // first gets current element and then advances iterator.

    // NOTE: This is also possible with the const iterators.

  }