.. oe:namespace:: OEChem

.. meta::
   :keywords: OECIFCategory, CIFCategory


.. _OEChem_OECIFCategory:

.. oe:class:: OECIFCategory

   .. oe:api::

      struct OECIFCategory

   This class represents the :ref:`OECIFCategory <OEChem_OECIFCategory>` that holds CIF header data and acts as an
   interface to interact with this header data. This object reflects what is contained in a CIF category.

   The :ref:`section_moldata_CIF` section explains in more detail the CIF data structure.

   .. seealso::

      * :oe:cls:`OEChem::OECIFData` class
      * :oe:cls:`OEChem::OECIFOptions` class
      * :ref:`section_moldata_cif`

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OECIFCategory()
            OECIFCategory(const std::string& categoryName,
                          const std::vector<std::string>& attributes,
                          const std::vector<std::string>& values)
            OECIFCategory(const std::string& categoryName,
                          const std::string& attribute,
                          const std::string& value)
            OECIFCategory(const std::string& categoryName,
                          const std::vector<std::string>& attributes)
            OECIFCategory(const std::string& categoryName)

      .. oe:language:: python

         .. oe:api:: python

            OECIFCategory() -> OECIFCategory
            OECIFCategory(categoryName: str) -> OECIFCategory
            OECIFCategory(categoryName: str, attributes: OEStringVector) -> OECIFCategory
            OECIFCategory(categoryName: str, attributes: OEStringVector,
                          values: OEStringVector) -> OECIFCategory
            OECIFCategory(categoryName: str, attribute: str, value: str) -> OECIFCategory
            OECIFCategory(category: OECIFCategory) -> OECIFCategory

      Create a :ref:`OECIFCategory <OEChem_OECIFCategory>` object.

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

      .. oe:api::

         OECIFCategory & operator=(const OECIFCategory & category)

      Assignment operator.


   .. oe:method:: AddAttribute

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool AddAttribute(const std::string& newAttribute,
                              const std::string& newValue = "?")
            bool AddAttribute(const std::string& newAttribute,
                              const std::vector<std::string>& newValues)

      .. oe:language:: python

         .. oe:api:: python

            AddAttribute(newAttribute: str, newValues: OEStringVector) -> bool

      Adds a column of values to the indicated CIF attribute.
      If no values are input, a question mark "?" value will be used to populate attribute values.

   .. oe:method:: AddRow

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool AddRow(const std::vector<std::string>& nvals)
            bool AddRow(const std::string init = "?")

      .. oe:language:: python

         .. oe:api:: python

            AddRow(newValues: OEStringVector) -> bool

      Adds a row of value(s) to the CIF category.

      If no values are input, by default, it will add a question mark "?" to every attribute in the category.

   .. oe:method:: DeleteRow

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool DeleteRow(unsigned int row)

      .. oe:language:: python

         .. oe:api:: python

            DeleteRow(row: int) -> bool

      Deletes a category's indicated row.

   .. oe:method:: DeleteAttribute

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool DeleteAttribute(const std::string& attribute)

      .. oe:language:: python

         .. oe:api:: python

            DeleteAttribute(attribute: str) -> bool

      Deletes a category attribute.

   .. oe:method:: GetAttributes

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::vector<std::string> GetAttributes() const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributes() -> OEStringVector

      Returns the category's attributes.

   .. oe:method:: GetAttributeValue

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::string GetAttributeValue(const std::string& attribute,
                                          bool raw = false) const
            std::string GetAttributeValue(const std::string& attribute,
                                          unsigned int row, bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributeValue(attribute: str, raw: bool = False) -> str
            GetAttributeValue(attribute: str, row: int, raw: bool = False) -> str

      Gets the saved value on the indicated attribute.
      If multiple values exist for a given attribute, then a row number must be identified.

   .. oe:method:: GetAttributeValues

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::vector<std::string> GetAttributeValues(const std::string& attribute,
                                                        bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributeValues(attribute: str, raw: bool = False) -> OEStringVector

      Gets all the saved values on the indicated attribute.

   .. oe:method:: GetAttributeIndex

      .. oe:language:: c++ java csharp

         .. oe:api::

            int GetAttributeIndex(const std::string& attribute) const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributeIndex(attribute: str) -> int

      Returns the attribute's base-0 index. For any given row of data associated with the category, this index
      correlates with the attribute's value in that row.
      For example, if GetAttributeIndex("type")=1, for every row generated by
      GetRows(), the _category.type data would be the [1] value in that row.

   .. oe:method:: GetCategoryName

      .. oe:language:: c++ java csharp

         .. oe:api::

            const std::string& GetCategoryName() const

      .. oe:language:: python

         .. oe:api:: python

            GetCategoryName() -> str

      Returns the category's name.

   .. oe:method:: GetDataItem

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::string GetDataItem(const std::string& attribute) const

      .. oe:language:: python

         .. oe:api:: python

            GetDataItem(attribute: str) -> str

      Returns the CIF data item name in the format: '_category.attribute'

   .. oe:method:: GetDataItems

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::vector<std::string> GetDataItems() const

      .. oe:language:: python

         .. oe:api:: python

            GetDataItems() -> OEStringVector

      Returns all the CIF data item names in the category in the format: '_category.attribute'

   .. oe:method:: GetNumRows

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetNumRows() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumRows() -> int

      Number of CIF rows in the category.

   .. oe:method:: GetNumAttributes

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetNumAttributes() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumAttributes() -> int

      Number of CIF attributes in the category.

   .. oe:method:: GetNumericAttributeValue

      .. oe:language:: c++

         .. oe:api::

            bool GetNumericAttributeValue(const std::string& attribute,
                                          float& val) const
            bool GetNumericAttributeValue(const std::string& attribute,
                                          int& val) const
            bool GetNumericAttributeValue(const std::string& attribute,
                                          unsigned int row, float& val) const
            bool GetNumericAttributeValue(const std::string& attribute,
                                          unsigned int row, int& val) const

      .. oe:language:: java

         .. oe:api::

            GetFloatAttributeValue(String attribute, Float val)
            GetIntAttributeValue(String attribute, Integer val)
            GetFloatAttributeValue(String attribute, Integer row, Float val)
            GetIntAttributeValue(String attribute, Integer row, Integer val)

      Gets the saved value for the indicated attribute and converts it to a numeric value.
      If multiple values exist for a given attribute, then a row number must be identified.
      If a value cannot be easily converted to a numeric value, it will default to 0.

   .. oe:method:: GetNumericAttributeValues

      .. oe:language:: c++

         .. oe:api::

            bool GetNumericAttributeValues(const std::string& attribute,
                                           std::vector<float>& vals) const
            bool GetNumericAttributeValues(const std::string& attribute,
                                           std::vector<int>& vals) const

      .. oe:language:: java

         .. oe:api::

            bool GetFloatAttributeValues(String attribute, Vector<Float> vals)
            bool GetIntAttributeValues(String attribute, Vector<Integer> vals)

      .. oe:language:: python

         .. oe:api:: python

            GetNumericAttributeValues(attribute: str, vals: OEFloatVector) -> bool
            GetNumericAttributeValues(attribute: str, vals: OEIntVector) -> bool

      Gets all the saved values for the indicated attribute and converts to a numeric value.
      If a value cannot be easily converted to a numeric value, it will default to 0.

   .. oe:method:: GetRow

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::vector<std::string> GetRow(unsigned int row, bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetRow(row: int, raw: bool = False) -> OEStringVector

      Returns as a specific row from the category. Row indicators are base-0.
      Raw values are formatted as they will appear in the header. This is most noticeable with values that contain
      space characters, as CIF formatting requires single or double quotes around such a string value.

   .. oe:method:: GetRows

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::vector<std::vector<std::string>> GetRows(int beginRow,
                                                          int endRow,
                                                          bool raw = false) const
            std::vector<std::vector<std::string>> GetRows(bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetRows(beginRow: int, endRow: int, raw: bool = False) -> OEStringVectorVector
            GetRows(raw: bool = False) -> OEStringVectorVector

      Returns rows from the category. Row indicators are base-0.
      Raw values are formatted as they will appear in the header. This is most noticeable with values that contain
      space characters, as CIF formatting requires single or double quotes around such a string value.

   .. oe:method:: GetRowIndices

      .. oe:language:: c++ java csharp

         .. oe:api::

            std::vector<unsigned int> GetRowIndices(const std::string& attribute,
                                                    const std::string& matchValue) const

      .. oe:language:: python

         .. oe:api:: python

            GetRowIndices(attribute: str, matchValue: str) -> OEUIntVector

      Returns the base-0 row indices whose values string-match with input match values.

   .. oe:method:: HasAttribute

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool HasAttribute(const std::string& attribute) const

      .. oe:language:: python

         .. oe:api:: python

            HasAttribute(attribute: str) -> bool

      Returns if an attribute is present in this object.

   .. oe:method:: SetData

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool SetData(const std::string& attribute,
                         const std::string& newValue)
            bool SetData(const std::string& attribute, unsigned int row,
                         const std::string& newValue,
                         const std::string init = "?")
            bool SetData(const std::string& attribute,
                         const std::vector<std::string>& newValues)
            bool SetData(unsigned int row,
                         const std::vector<std::string>& newValues,
                         const std::string init = "?")

      .. oe:language:: python

         .. oe:api:: python

            SetData(attribute: str, newValues: OEStringVector) -> bool
            SetData(attribute: str, row: int, newValue: str, init: str = "?") -> bool
            SetData(row: int, newValues: OEStringVector, init: str = "?") -> bool

      Sets attribute and row data. When setting data related to row values, if the
      indicated row value exceeds the maximum number of rows, then empty values will populate any undefined attributes
      values.
      Rows indicators are base-0.

   .. oe:method:: SortByAttribute

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SortByAttribute(const std::string& attribute)

      .. oe:language:: python

         .. oe:api:: python

            SortByAttribute(attribute: str) -> None

      All rows will be rearranged according to the alphanumeric order of the indicated attribute's values.
