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

.. oe:namespace:: OEDataFlow

.. attention::

   |TWOLANGUAGE|

.. meta::
   :keywords: OERecord datarecord

.. _OEDataFlow_OERecord:

.. oe:class:: OERecord

   .. seealso::

      * :ref:`chapter_oerecord` chapter

   .. oe:language:: c++

      .. attention::

        |TWOLANGUAGE|

      .. oe:api::

         class OERecord

      The :ref:`OERecord <OEDataFlow_OERecord>` class is a data container for
      named, typed data.

      .. ################################################################
         Constructors

      .. oe:method:: Constructors

         .. oe:api::

            OERecord()

         The default constructor initializes the record object to an empty
         record with no fields or values.

         .. oe:api::

            OERecord(const OERecord& rhs)

         Copy constructor.


   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OERecord & operator=(OERecord & &)
         OERecord & operator=(const OERecord & rhs)

      Assignment operator.

         ################################################################

      .. oe:method:: AddField

         .. oe:api::

            bool AddField(const OEFieldBase& field)

         Adds an empty field to the record.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`



      .. oe:method:: Clear

         .. oe:api::

            void Clear()

         Removes all fields and data from the record, leaving it empty.


      .. oe:method:: ClearValue

         .. oe:api::

            bool ClearValue(const OEFieldBase& field)

         Removes the specified field's value from the record. The field
         will still exist, but will have no associated value. Returns false
         if no such field or value exist.


      .. oe:method:: DeleteField

         .. oe:api::

            bool DeleteField(const OEFieldBase& field)

         Removes the field and the associated data from the record.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class



      .. oe:method:: GetField

         .. oe:api::

            template<typename T> OEField<T> GetField(const std::string& name,
                                                     bool includeMeta = true) const

         Returns the field with the specified name and type from the record.
         If no such field exists on the record, an empty (and unusable)
         OEField<T> object is returned.

         name
           The name of the field to retrieve from the record.

         includeMeta
           If this is true, the returned field will include the record's
           metadata for the field.


      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::HasField` method
         * :ref:`OEField <OEDataFlow_OEField>`


      .. oe:method:: GetFieldMeta

         .. oe:api::

            OEFieldMeta GetFieldMeta(const std::string& name) const

         Returns an :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` object containing
         the metadata from the named field. If the field does not exist, or the
         field exists but contains no metadata, an empty OEFieldMeta object is
         returned.

         name
           The name of the field to retrieve the metadata from.


      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::HasField` method
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class


      .. oe:method:: GetFields

         .. oe:api::

            std::vector<OEFieldBase> GetFields() const
            template <typename T> std::vector<OEField<T>> GetFields(const OEFieldType<T>& fieldType) const
            template <typename T> std::vector<OEVectorField<T>> GetFields(const OEVectorFieldType<T>& fieldType) const

         Returns the field objects from the record.

         fieldType
           This parameter specifies the type of the field to match.


      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::HasField` method
         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class


      .. oe:method:: GetValue

         .. oe:api::

            template<typename T> T GetValue(const OEField<T>& field) const

         Retrieves the value from a field on the record. If no such value exists
         on the record, this will return a default-constructed T value.

         field
           The field from which the value is retrieved.


         .. oe:api::

            template<typename T> bool GetValue(T& ret, const OEField<T>& field) const

         Retrieves the value from a field on the record. If no such value exists
         on the record, this will return false and leave the value
         unchanged. This overload can avoid a copy of the T value.

         field
           The field from which the value is retrieved.

         value
           The returned value. If no such field exists on the record, this
           is left unchanged.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`

      .. oe:method:: GetVectorField

         .. oe:api::

            template<typename T> OEVectorField<T> GetVectorField(const std::string& name,
                                                                 bool includeMeta = true) const

         Returns the vector field with the specified name and type from the
         record. If no such field exists on the record, an empty (and unusable)
         :ref:`OEVectorField <OEDataFlow_OEVectorField>` object is returned.

         name
           The name of the field to return.

         includeMeta
           When true, the returned field will include metadata from the record.


      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::HasField` method


      .. oe:method:: HasField

         .. oe:api::

            bool HasField(const OEFieldBase& field, bool matchMeta = false) const

         Tests for existence of a field on the record, and returns true if a
         field of the specified name and type exists, regardless of whether
         the field contains a value.

         field
           The field to test for on the record.

         matchMeta
           When true, all metadata on the *field* parameter must be present on
           the record's field to return true.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`

      .. oe:method:: HasValue

         .. oe:api::

            bool HasValue(const OEFieldBase& field) const

         Tests for presence of a value on the record for the specified field,
         and returns true if such a value exists. The method will return false
         if no matching value can be found or if the specified field does not
         exist on the record.

         field
           The field to check for a value.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`

      .. oe:method:: IsEmpty

         .. oe:api::

            bool IsEmpty() const

        Returns true if the record contains no fields or data.


      .. oe:method:: IsNA

         .. oe:api::

            bool IsNA(const OEFieldBase& field) const
            bool IsNA(const std::string& fieldName) const

        Returns true if the specified field contains a null value. Note that this
        is different from the field not containing a value at all.

        field
          The field to test.

        fieldName
          The name of the field to test.


      .. oe:method:: SetValue

         .. oe:api::

            template<typename T, typename U> bool SetValue(const OEField<T>& field,
                                                           const U& value)
            template<typename T, typename U> bool SetValue(const OEVectorField<T>& field,
                                                           const std::vector<U>& value)

        Sets the specified value on the record, and returns true if successful.

        field
          The field to set the value for. If the field exists, its value will
          be overwritten. If the field doesn't exist on the record, it will
          be added.

        value
          The value to be added to the record.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`

      .. oe:method:: CheckField

         .. oe:api::

            unsigned int CheckField(const OEFieldBase& field,
                                    bool matchMeta = false) const

         Tests the existence and state of a field on a record, and returns a
         value from the :oe:constns:`OEDataFlow::OERecordReturnCode`
         namespace.

         field
           The field to test.

         matchMeta
           If this argument is true, the test for a matching field will include
           the *field* parameter's metadata.

      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::HasField` method
         * :oe:meth:`OEDataFlow::OERecord::HasValue` method
         * :ref:`OEField <OEDataFlow_OEField>`



   .. oe:language:: python

      .. oe:api::

         class OERecord

      The :ref:`OERecord <OEDataFlow_OERecord>` class is a data container for
      named, typed data.


      .. ################################################################
         # Constructors
         ################################################################

      .. oe:method:: Constructors

         .. oe:api::

            OERecord()

         The default constructor initializes the record object to an empty
         record with no fields or values.

         .. oe:api::

            OERecord(rhs: OERecord)

         Copy constructor.


      .. oe:method:: add_field

         .. oe:api::

            add_field(field: OEFieldBase) -> bool

         Adds an empty field to the record and returns *True* if
         successful.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`



      .. oe:method:: clear

         .. oe:api::

            clear() -> None

         Removes all fields and data from the record, leaving it empty.


      .. oe:method:: clear_value

         .. oe:api::

            clear_value(field: OEFieldBase) -> bool

         Removes the specified field's value from the record. The field
         will still exist, but will have no associated value. Returns *False*
         if no such field or value exist.


      .. oe:method:: delete_field

         .. oe:api::

            delete_field(field: OEFieldBase) -> bool

         Removes the field and the associated data from the record.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`


      .. oe:method:: get_field

         .. oe:api::

            get_field(name: str, includeMeta: bool = True) -> object

         Returns the field with the specified name and type from the record.
         If no such field exists on the record, an empty (and unusable)
         field object is returned.

         name
           The name of the field to retrieve from the record.

         includeMeta
           If this is *True*, the returned field will include the record's
           metadata for the field.


      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::has_field` method
         * :ref:`OEField <OEDataFlow_OEField>`



      .. oe:method:: get_field_meta

         .. oe:api::

            get_field_meta(name: str) -> OEFieldMeta

         Returns an :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` object containing
         the metadata from the named field. If the field does not exist, or the
         field exists but contains no metadata, an empty OEFieldMeta object is
         returned.

         name
           The name of the field to retrieve the metadata from.


      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::has_field` method
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class


      .. oe:method:: get_fields

         .. oe:api::

            get_fields() -> List[object]
            get_fields(fieldType: OEFieldTypeHandler) -> List[object]

         Returns the field objects from the record.

         fieldType
           This parameter specifies the type of the field to match.


      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::has_field` method
         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class


      .. oe:method:: get_value

         .. oe:api::

            get_value(field: OEField) -> Any

         Retrieves the value from a field on the record. If no such value exists
         on the record, this will return *None*.

         field
           The field from which the value is retrieved.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`

      .. oe:method:: has_field

         .. oe:api::

            has_field(field: OEField, matchMeta: bool = false) -> bool

         Tests for existence of a field on the record, and returns *True* if a
         field of the specified name and type exists, regardless of whether
         the field contains a value.

         field
           The field to test for on the record.

         matchMeta
           When true, all metadata on the *field* parameter must be present on
           the record's field to return true.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`


      .. oe:method:: has_value

         .. oe:api::

            has_value(field: OEFieldBase) -> bool

         Tests for presence of a value on the record for the specified field,
         and returns true if such a value exists. The method will return
         *false* if no matching value can be found or if the specified field
         does not exist on the record.

         field
           The field to check for a value.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class


      .. oe:method:: is_empty

         .. oe:api::

            is_empty() -> bool

        Returns *True* if the record contains no fields or data.


      .. oe:method:: is_na

         .. oe:api::

            is_na(field: OEFieldBase) -> bool
            is_na(fieldName: str) -> bool

        Returns *True* if the specified field contains a null value. Note that
        this is different from the field not containing a value at all.

        field
          The field to test.

        fieldName
          The name of the field to test.


      .. oe:method:: set_value

         .. oe:api::

            set_value(field: OEField, value: Any) -> bool

        Sets the specified value on the record, and returns *True* if successful.

        field
          The field to set the value for. If the field exists, its value will
          be overwritten. If the field doesn't exist on the record, it will
          be added.

        value
          The value to be added to the record.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`



      .. oe:method:: check_field

         .. oe:api::

            check_field(const OEFieldBase &field, bool matchMeta = false) -> int

         Tests the existence and state of a field on a record, and returns a
         value from the :oe:constns:`OEDataFlow::OERecordReturnCode`
         namespace.

         field
           The field to test.

         matchMeta
           If this argument is True, the test for a matching field will include
           the *field* parameter's metadata.

      .. seealso::

         * :oe:meth:`OEDataFlow::OERecord::has_field` method
         * :oe:meth:`OEDataFlow::OERecord::has_value` method
         * :ref:`OEField <OEDataFlow_OEField>`
