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

.. oe:namespace:: OEDataFlow

.. attention::

   |TWOLANGUAGE|

..  _OEDataFlow_OEFieldBase:

..  _OEDataFlow_OEField:

.. meta::
   :keywords: OEFieldBase, OEField, datarecord, OERecord
  
.. oe:language:: c++

   .. oe:class:: OEFieldBase
   
      .. oe:api::
   
         class OEFieldBase
   
      The :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class is a base class for
      the templated :ref:`OEField <OEDataFlow_OEField>` classes used to
      set and get data from :ref:`OERecord <OEDataFlow_OERecord>` objects.
      In most cases, the templated, concrete 
      :ref:`OEField <OEDataFlow_OEField>` objects should be used.

      .. oe:method:: Constructors
   
         .. oe:api::

            OEFieldBase()

         The default constructor initializes the field object to an invalid
         field with no name or type.
   
         .. oe:api::

            OEFieldBase(const OEFieldBase& rhs)

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

      .. oe:api::

         OEFieldBase & operator=(const OEFieldBase &)

      Assignment operator.

   
      .. oe:method:: GetName
   
         .. oe:api::

            std::string GetName() const

         Returns the field's name.
   
      .. oe:method:: SetName
   
         .. oe:api::

            void SetName(const std::string& name)

         Sets the name of the field.
   
      .. oe:method:: GetTypeName
   
         .. oe:api::

            std::string GetTypeName() const

         Returns the name of the field's type.
   
   
      .. oe:method:: IsNullable
   
         .. oe:api::

            bool IsNullable() const

         Returns true if the field allows setting of null values.
   
   
      .. oe:method:: IsReadonly
   
         .. oe:api::

            bool IsReadonly() const

         Returns true if the field only allows reading, but not writing, of
         data onto a record.
   
   
      .. oe:method:: IsValid
   
         .. oe:api::

            bool IsValid() const

         Returns true if the field has been initialized.
   
   
      .. oe:method:: GetMeta
   
         .. oe:api::

            OEFieldMeta GetMeta() const

         Returns the metadata associated with this field. If the field has no
         metadata, an empty :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` object
         is returned.
   
   
      .. oe:method:: SetMeta
   
         .. oe:api::

            void SetMeta(const OEFieldMeta& meta)

         Sets metadata for this field.
   
      .. seealso::
   
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>`
   
   .. oe:class:: OEField
   
      .. oe:api::
   
         class OEField
   
      The OEField class is a templated subclass of
      :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` and is templated on types
      that can be stored on :ref:`OERecord <OEDataFlow_OERecord>`.
   
      The following methods are publicly inherited from 
      :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`:
   
      =========================================================== =========================================================
      :oe:meth:`OEDataFlow::OEFieldBase::GetName`       	  :oe:meth:`OEDataFlow::OEFieldBase::SetName`
      :oe:meth:`OEDataFlow::OEFieldBase::GetTypeName`   	  :oe:meth:`OEDataFlow::OEFieldBase::IsNullable`
      :oe:meth:`OEDataFlow::OEFieldBase::IsReadonly`    	  :oe:meth:`OEDataFlow::OEFieldBase::IsValid`
      :oe:meth:`OEDataFlow::OEFieldBase::GetMeta`       	  :oe:meth:`OEDataFlow::OEFieldBase::SetMeta`
      =========================================================== =========================================================
   
      .. ################################################################
         # Constructors
         ################################################################
   
      .. oe:method:: Constructors
   
         .. oe:api::

            template<typename T> OEField<T>::OEField(const string &,
                                                     OEFieldMeta, bool, bool)

         This constructor initializes the field object with the specified type,
         name, and metadata, and sets the readonly and nullable states of the
         field.
   
         The :oe:constns:`OEDataFlow::Types` namespace contains the types of
         T that are supported.
   
         .. note::
   
            OEField objects are best created using the 
            :oe:func:`OEDataFlow::OEMakeField` function instead of this 
            constructor method.
   
         .. seealso::
         
            * :oe:func:`OEDataFlow::OEMakeField`
            * :ref:`OERecord <OEDataFlow_OERecord>`
   
         .. oe:api::

            template<typename T> OEField<T>::OEField(const OEFieldBase& f)

         Copy constructor.
   
      .. oe:method:: GetType
   
         .. oe:api::

            OEFieldType<T> GetType() const

         Returns an :ref:`OEFieldType <OEDataFlow_OEFieldType>` object
         representing the type of objects stored and retrieved by this field.
   
   ..  _OEDataFlow_OEVectorField:

   .. oe:class:: OEVectorField
   
      .. oe:api::
   
         class OEVectorField
   
      The OEVectorField class is a templated subclass of
      :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` and is templated on types
      that can be stored in vectors on :ref:`OERecord <OEDataFlow_OERecord>`.
   
      .. ################################################################
         # Constructors
         ################################################################
   
      .. oe:method:: Constructors
   
         .. oe:api::

            template<typename T> OEVectorField<T>::OEVectorField(const string &,
                                                                 OEFieldMeta = OEFieldMeta(),
                                                                 bool = false,
                                                                 bool = false)

         This constructor initializes the field object with the specified type,
         name, and metadata, and sets the readonly and nullable states of the
         field. An OEVectorField<T> can store and retrieve std::vector<T> objects
         to and from records.
   
         See the :oe:constns:`OEDataFlow::Types` namespace for types of
         T that are supported.
   
         .. note::
   
            OEVectorField objects are best created using the 
            :oe:func:`OEDataFlow::OEMakeField` function instead of this 
            constructor method.
   
   
         .. oe:api::

            template<typename T> OEVectorField<T>::OEVectorField(const OEFieldBase &)

         Copy constructor.
   
      .. oe:method:: GetType
   
         .. oe:api::

            OEVectorFieldType<T> GetType() const

         Returns an OEVectorFieldType object
         representing the type of objects stored and retrieved by this field.
   
   
   .. oe:class:: OEMatchField

      .. oe:api::

         class OEMatchField

      The OEMatchField class is a templated subclass of
      :ref:`OEField <OEDataFlow_OEField>`. It is used to retrieve values
      from an :ref:`OERecord <OEDataFlow_OERecord>` object when the
      name of the field is unknown. An OEMatchField object acts as a surrogate
      for the first field of a record that matches the type and metadata.
   
      .. ################################################################
         # Constructors
         ################################################################
   
      .. oe:method:: Constructors
   
         .. oe:api::

            OEMatchField(const std::string& name,
                         const OEFieldMeta meta = OEFieldMeta(),
                         bool readonly = false, bool nullable = false)

         This constructor initializes the match field object with the specified type,
         name, and metadata, and sets the readonly and nullable states of the
         field. The provided `name` parameter is only used if the match field creates
         a new field on a record.
   
         .. note::
   
            OEMatchField objects are best created using the 
            :oe:func:`OEDataFlow::OEMakeMatchField` function instead of this 
            constructor method.
   
   
      .. seealso::
   
         * :oe:func:`OEDataFlow::OEMakeMatchField`
         * :ref:`OEField <OEDataFlow_OEField>`
   
   
   .. oe:class:: OEMatchVectorField
   
      .. oe:api::
   
         class OEMatchVectorField
   
      The OEMatchVectorField class is a templated subclass of
      :ref:`OEVectorField <OEDataFlow_OEVectorField>`. It is used to retrieve values
      from an :ref:`OERecord <OEDataFlow_OERecord>` object when the
      name of the field is unknown. An OEMatchVectorField object acts as a surrogate
      for the first vector field of a record that matches the type and metadata.
   
   
      .. ################################################################
         # Constructors
         ################################################################
   
      .. oe:method:: Constructors
   
         .. oe:api::

            OEMatchVectorField(const std::string& name,
                               const OEFieldMeta meta = OEFieldMeta(),
                               bool readonly = false, bool nullable = false)

         This constructor initializes the match field object with the specified type,
         name, and metadata, and sets the readonly and nullable states of the
         field. The provided `name` parameter is only used if the match field creates
         a new field on a record. 
   
         .. note::
   
            OEMatchVectorField objects are best created using the 
            :oe:func:`OEDataFlow::OEMakeMatchField` function instead of this 
            constructor method.
   
      .. seealso::
   
         * :oe:func:`OEDataFlow::OEMakeMatchField`
         * :ref:`OEMatchField <OEDataFlow_OEMatchField>`
         * :ref:`OEVectorField <OEDataFlow_OEVectorField>`
   
.. oe:language:: python

   .. oe:class:: OEFieldBase
   
      .. oe:api::
   
         class OEFieldBase
   
      The :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class is a base class for
      a number of specialized classes used to set and get data from 
      :ref:`OERecord <OEDataFlow_OERecord>` objects. These objects are
      returned from the OEField function and are not constructed directly.
   
      .. ################################################################
         # Constructors
         ################################################################
   
      .. oe:method:: Constructors
   
         .. oe:api::

            OEFieldBase()

         The default constructor initializes the field object to an invalid
         field with no name or type.
   
         .. oe:api::

            OEFieldBase(rhs: OEFieldBase)

         Copy constructor.
   
      .. _get_name:

      .. oe:method:: get_name
   
         .. oe:api::

            get_name() -> string

         Returns the field's name.
   
      .. _set_name:

      .. oe:method:: set_name
   
         .. oe:api::

            set_name(name: str) -> None

         Sets the name of the field.
   
      .. _get_type_name:

      .. oe:method:: get_type_name
   
         .. oe:api::

            get_type_name() -> string

         Returns the name of the field's type.
   
   
      .. _is_nullable:

      .. oe:method:: is_nullable
   
         .. oe:api::

            is_nullable() -> bool

         Returns True if the field allows setting of null values.
   
   
      .. _get_read_only:

      .. oe:method:: get_read_only
   
         .. oe:api::

            get_read_only() -> bool

         Returns True if the field only allows reading, but not writing, of
         data onto a record.
   
   
      .. _is_valid:

      .. oe:method:: is_valid
   
         .. oe:api::

            is_valid() -> bool

         Returns True if the field has been initialized.
   
   
      .. _get_meta:

      .. oe:method:: get_meta
   
         .. oe:api::

            get_meta() -> OEFieldMeta

         Returns the metadata associated with this field. If the field has no
         metadata, an empty :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` object
         is returned.
   
   
      .. _set_meta:

      .. oe:method:: set_meta
   
         .. oe:api::

            set_meta(meta: OEFieldMeta) -> None

         Sets metadata for this field.
   
      .. seealso::
   
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>`
   
   .. oe:class:: OEField
   
      .. oe:api::
   
         OEField(name: str, dataType: OEFieldType, meta: OEFieldMeta,
                 read_only: bool = False, nullable: bool = False) -> field object of specific type
         
   
      In Python, OEField is a factory function returning a field object derived from
      :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`. The returned field object can
      be used to set/get values on an :ref:`OERecord <OEDataFlow_OERecord>`.
  
      name
        The name to be given to the created field.

      dataType
        The type of field to create. Supported types come from the 
        :oe:constns:`OEDataFlow::Types` namespace.

      meta
        An :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` object containing
        metadata for the returned field.

      read_only
        If *True*, the returned field can only be used for reading from, and
        not writing to, :ref:`OERecord <OEDataFlow_OERecord>` objects.

      nullable
        If *True*, the returned field can be used to set null values onto
        an :ref:`OERecord <OEDataFlow_OERecord>`.

      The returned field object will have the following methods inherited from 
      :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`:
   
      ================== ==========================
      get_name_          set_name_
      get_type_name_     is_nullable_
      get_read_only_     is_valid_
      get_meta_          set_meta_
      ================== ==========================

      .. seealso::
 
         * :ref:`OERecord <OEDataFlow_OERecord>`
   
      .. oe:method:: get_type
   
         .. oe:api::

            get_type() -> OEFieldType

         Returns an :ref:`OEFieldType <OEDataFlow_OEFieldType>` object
         representing the type of objects stored and retrieved by this field.
   
   
   .. _OEDataFlow_OEMatchField:

   .. oe:class:: OEMatchField
   
      .. oe:api::
   
         class OEMatchField
   
      OEMatchField is a factory function returning a specialized match field
      object. The returned match field is used to retrieve values
      from an :ref:`OERecord <OEDataFlow_OERecord>` object when the
      name of the field is unknown. An OEMatchField object acts as a surrogate
      for the first field of a record that matches the type and metadata.
   
      .. oe:api::
   
         OEMatchField(name: str, meta: OEFieldMeta, read_only: bool = False,
                      nullable: bool = False)
  
      name
        The name to be given to the created match field. It is only used if the
        match field is used to create a new field on a record.

      meta
        An :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` object containing
        metadata for the returned match field.

      read_only
        If *True*, the returned match field can only be used for reading from, and
        not writing to, :ref:`OERecord <OEDataFlow_OERecord>` objects.

      nullable
        If *True*, the returned match field can be used to set null values onto
        an :ref:`OERecord <OEDataFlow_OERecord>`.

        
      .. seealso::
   
         * :ref:`OEField <OEDataFlow_OEField>`
   
   
