.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEDataFlow

.. attention::

   |TWOLANGUAGE|

.. meta::
   :keywords: OEFieldMeta datarecord


.. _OEDataFlow_OEFieldMeta:

.. oe:class:: OEFieldMeta

   .. oe:language:: c++ 

      .. oe:api::
   
         class OEFieldMeta
   
      The :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class is used to
      associate metadata with data to be stored on :ref:`OERecord <OEDataFlow_OERecord>`
      objects. Two types of metadata can be assigned to an OEFieldMeta object:
      *options* are simple flags, while *attributes* are key-value pairs.
      Constants defining both options and attributes are defined in the
      :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         # Constructors
         ################################################################
   
      .. oe:method:: Constructors
   
         .. oe:api::
   
            OEFieldMeta()
   
         The default constructor initializes an empty metadata object.
   
         .. oe:api::
   
            OEFieldMeta(const OEFieldMeta& rhs)
   
         Copy constructor.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: SetOption
   
         .. oe:api::
   
            OEFieldMeta& SetOption(unsigned int option)
   
         Adds the specified option to the OEFieldMeta object. Options are specified
         in the :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: SetOptions
   
         .. oe:api::
   
            OEFieldMeta& SetOptions(const std::vector<unsigned int>& options)
   
         Sets all the option values for the OEFieldMeta object at once. Options 
         are specified in the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: GetOptions
   
         .. oe:api::
   
            const std::vector<unsigned int>& GetOptions() const
   
         Returns all the option values for the OEFieldMeta object at once.
         Options are specified in the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: HasOption
   
         .. oe:api::
   
            bool HasOption(unsigned int option) const
   
         Returns true if this OEFieldMeta object contains the specified
         option.
   

      .. ################################################################
         #
         ################################################################

      .. oe:method:: RemoveOption

         .. oe:api::

            OEMeta& RemoveOption(unsigned int option)

         Removes the specified option from the OEFieldMeta object.

      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: AddRelation
   
         .. oe:api::
   
            OEFieldMeta& AddRelation(unsigned int relationship,
                                     const OEFieldBase& otherField)
   
         Specifies a relationship to another field on the same record. For
         example, this could be used to specify that one field contains
         error bars for another field. The relationships are specified in the Relations
         section of the :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: GetRelatedFields
   
         .. oe:api::
   
            std::vector<std::string> GetRelatedFields() const
   
         Returns the names of fields that this OEFieldMeta object refers to.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: GetFieldRelations
   
         .. oe:api::
   
            std::vector<unsigned int> GetFieldRelations(const std::string& fieldName) const
   
         Returns the relationships that this OEFieldMeta object has to the
         named field. The relationships are specified in the
         Relations section of the :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: Clear
   
         .. oe:api::
   
            void Clear()
   
         Clears all attributes and options from the OEFieldMeta object.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: SetAttribute
   
         .. oe:api::
   
            OEFieldMeta& SetAttribute(unsigned int key,
                                      const std::string& value)
            OEFieldMeta& SetAttribute(unsigned int key, const double& value)
            OEFieldMeta& SetAttribute(unsigned int key, const int& value)
   
         Sets a metadata key-value pair on the OEFieldMeta object. Any attribute(s)
         with the same key are replaced. The key values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: AddAttribute
   
         .. oe:api::
   
            OEFieldMeta& AddAttribute(unsigned int key,
                                      const std::string& value)
            OEFieldMeta& AddAttribute(unsigned int key, const double& value)
            OEFieldMeta& AddAttribute(unsigned int key, const int& value)
   
         Sets a metadata key-value pair on the OEFieldMeta object. Multiple
         attributes for the same key are allowed, and this method adds additional
         values for the specified key. The key values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: GetAttribute
   
         .. oe:api::
   
            template<typename T> T GetAttribute(unsigned int key,
                                                unsigned int idx = 0) const
   
         Returns the attribute value for the provided key and index. If the OEFieldMeta
         object doesn't have a corresponding value, a default-constructed T object
         is returned. Because an attribute key can have multiple values, the *idx*
         argument specifies which value to return.  The key values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: HasAttribute
   
         .. oe:api::
   
            bool HasAttribute(unsigned int key) const
            bool HasAttribute(unsigned int key, const std::string& value) const
            bool HasAttribute(unsigned int key, const double& value) const
            bool HasAttribute(unsigned int key, const int& value) const
   
         Returns true if this OEFieldMeta object contains the specified attribute.
         If the *value* argument is specified, the method will return true if
         that specific key-value pair is present. Otherwise, it will return true
         if any value is present for the provided key.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: RemoveAttribute
   
         .. oe:api::
   
            OEFieldMeta& RemoveAttribute(unsigned int key)
            OEFieldMeta& RemoveAttribute(unsigned int key,
                                         const std::string& value)
            OEFieldMeta& RemoveAttribute(unsigned int key, const double& value)
            OEFieldMeta& RemoveAttribute(unsigned int key, const int& value)
   
         Removes a metadata key-value pair from the OEFieldMeta object. If
         the *value* is specified, that specific key-value pair is removed
         from the OEFieldMeta object. Otherwise, all values with the provided
         key are removed.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: GetName
   
         .. oe:api::
   
            static std::string GetName(unsigned int optionOrAttributeKey)
   
         Returns a name for the specified option or attribute key.
   
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: GetValue
   
         .. oe:api::
   
            static unsigned int GetValue(const std::string& name)
   
         Returns an integer value for the specified option name.
         The returned values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: IsOption
   
         .. oe:api::
   
            bool IsOption(unsigned int key)
   
         Returns true if the provided metadata key is an option, rather than
         an attribute. The key value is from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
   .. oe:language:: python

      .. oe:api::
   
         class OEFieldMeta
   
      The :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class is used to
      associate metadata with data to be stored on :ref:`OERecord <OEDataFlow_OERecord>`
      objects. Two types of metadata can be assigned to an OEFieldMeta object:
      *options* are simple flags, while *attributes* are key-value pairs.
      Constants defining both options and attributes are defined in the
      :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         # Constructors
         ################################################################
   
      .. oe:method:: Constructors
   
         .. oe:api::
   
            OEFieldMeta()
   
         The default constructor initializes an empty metadata object.
   
         .. oe:api::
   
            OEFieldMeta(rhs: OEFieldMeta)
   
         Copy constructor.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: set_option
   
         .. oe:api::
   
            set_option(option: int) -> OEFieldMeta
   
         Adds the specified option to the OEFieldMeta object. Options are specified
         in the :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: set_options
   
         .. oe:api::
   
            set_options(options: List[int]) -> OEFieldMeta
   
         Sets all the option values for the OEFieldMeta object at once. Options 
         are specified in the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.

      .. ################################################################
         #
         ################################################################

      .. oe:method:: remove_option
   
         .. oe:api::

            remove_option(option: int) -> OEFieldMeta

         Removes the specified option from the OEFieldMeta object.
         Options are specified
         in the :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.

      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: get_options
   
         .. oe:api::
   
            get_options() -> List[int]
   
         Returns all the option values for the OEFieldMeta object at once.
         Options are specified in the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: has_option
   
         .. oe:api::
   
            has_option(option: int) -> bool
   
         Returns *True* if this OEFieldMeta object contains the specified
         option.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: add_relation
   
         .. oe:api::
   
            add_relation(relationship: int, otherField: OEFieldBase) -> OEFieldMeta
   
         Specifies a relationship to another field on the same record. For
         example, this could be used to specify that one field contains
         error bars for another field. The relationships are specified in the
         ``Relations`` section of the :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: get_related_fields
   
         .. oe:api::
   
            get_related_fields() -> List[str]
   
         Returns the names of fields that this OEFieldMeta object refers to.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: get_field_relations
   
         .. oe:api::
   
            get_field_relations(fieldName: str) -> List[int]
   
         Returns the relationships that this OEFieldMeta object has to the
         named field. The relationships are specified in the ``Relations``
         section of the :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: clear
   
         .. oe:api::
   
            clear() -> None
    
         Clears all attributes and options from the OEFieldMeta object.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: set_attribute
   
         .. oe:api::
   
            set_attribute(key: int, value: str) -> OEFieldMeta
            set_attribute(key: int, value: int) -> OEFieldMeta
            set_attribute(key: int, value: float) -> OEFieldMeta
   
         Sets a metadata key-value pair on the OEFieldMeta object. Any attribute(s)
         with the same key are replaced. The key values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: add_attribute
   
         .. oe:api::
   
            add_attribute(key: int, value: str) -> OEFieldMeta
            add_attribute(key: int, value: int) -> OEFieldMeta
            add_attribute(key: int, value: float) -> OEFieldMeta
   
         Sets a metadata key-value pair on the OEFieldMeta object. Multiple
         attributes for the same key are allowed, and this method adds additional
         values for the specified key. The key values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: get_attribute
   
         .. oe:api::
   
            get_attribute(key: int, idx: int = 0) -> Union[str, int, float, None]
   
         Returns the attribute value for the provided key and index. If the OEFieldMeta
         object doesn't have a corresponding value, a *None* 
         is returned. Because an attribute key can have multiple values, the *idx*
         argument specifies which value to return.  The key values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: has_attribute
   
         .. oe:api::
   
            has_attribute(key: int) -> bool
            has_attribute(key: int, value: str) -> bool
            has_attribute(key: int, value: int) -> bool
            has_attribute(key: int, value: float) -> bool
   
         Returns *True* if this OEFieldMeta object contains the specified attribute.
         If the *value* argument is specified, the method will return true if
         that specific key-value pair is present. Otherwise, it will return true
         if any value is present for the provided key.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: remove_attribute
   
         .. oe:api::
   
            remove_attribute(unsigned int key) -> OEFieldMeta
            remove_attribute(unsigned int key, value: str) -> OEFieldMeta
            remove_attribute(unsigned int key, value: int) -> OEFieldMeta
            remove_attribute(unsigned int key, value: float) -> OEFieldMeta
   
         Removes a metadata key-value pair from the OEFieldMeta object. If
         the *value* is specified, that specific key-value pair is removed
         from the OEFieldMeta object. Otherwise, all values with the provided
         key are removed.
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: get_name
   
         .. oe:api::
   
            get_name(optionOrAttributeKey: int) -> str
   
         Returns a name for the specified option or attribute key.
   
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: get_value
   
         .. oe:api::
   
            get_value(name: str) -> int
   
         Returns an integer value for the specified option name.
         The returned values are from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
   
      .. ################################################################
         #
         ################################################################
   
      .. oe:method:: is_option
   
         .. oe:api::
   
            IsOption(key: int) -> bool
   
         Returns *True* if the provided metadata key is an option, rather than
         an attribute. The key value is from the 
         :ref:`OEMetadata <OEDataFlow_OEMetadata>` namespace.
   
