/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

#ifndef _DAI_AGGR_BASE_H
#define _DAI_AGGR_BASE_H

#include "OdPlatformSettings.h"
#include "OdaCommon.h"
#include "SharedPtr.h"

#include "daiBuildOptions.h"
#include "daiObjectId.h"
#include "daiAggrBaseValueType.h"

#include "daiError/daiException.h"

#include "TD_PackPush.h"

class OdRxValueType;
class OdRxValue;

/** \details 
Implements the Data Access Interface (DAI) that provides functionality for manipulating data that is defined within the EXPRESS SCHEMA format.
*/
namespace OdDAI
{
  /**The default lower bound for unordered aggregates.*/
  static const unsigned int unorderedDefaultLowerBound = 0;
  /**The default upper bound for unordered aggregates.*/
  static const unsigned int unorderedDefaultUpperBound = static_cast<unsigned int>(-1);

  /**The default lower bound for ordered aggregates.*/
  static const int orderedDefaultLowerBound = 0;
  /**The default upper bound for ordered aggregates.*/
  static const int orderedDefaultUpperBound = unorderedDefaultUpperBound >> 1;

  class OdSpfFilerBase;

  class AggregationType;

  class AggrInstance;
  typedef OdSharedPtr<AggrInstance> AggrInstancePtr;

  class Iterator;
  typedef OdSharedPtr<Iterator> IteratorPtr;

  class ConstIterator;
  typedef OdSharedPtr<ConstIterator> ConstIteratorPtr;

  /** \details
  Defines aggregation types.
  */
  enum AggrType
  {
    /** Array type */
    aggrTypeArray,

    /** Bag type */
    aggrTypeBag,

    /** List type */
    aggrTypeList,

    /** Set type */
    aggrTypeSet,
  };

  //DOM-IGNORE-BEGIN
  class DAI_EXPORT AggrInstance;
  class DAI_EXPORT OrderedLogic;
  class DAI_EXPORT UnorderedLogic;

  template<class TWorkInstance>
  class DAI_EXPORT AggrInstanceDefaultBase;

  template<class TWorkInstance>
  class DAI_EXPORT AggrInstanceDefault;

  template<class TWorkInstance>
  class DAI_EXPORT TypedAggrInstanceDefault;

  template<typename TItem>
  class AggrInstanceCommon;
  //DOM-IGNORE-END
  
  //DOM-IGNORE-BEGIN
  /** \details
  An abstract class that provides an interface for reading data from <link OdDAI::Aggr, aggregates>.
  */
  template<class TItem>
  class IAggrReader
  {
  public:
    /** \details 
    Skips data from an <link OdDAI::Aggr, aggregate> until a specified symbol appears.
    \param symbol [in] A symbol that should appear to stop skipping data.
    \returns true if the specified symbol appeared, and false if the specified symbol didn't appear or when a syntax error was found.
    */
    virtual bool skipUntil(const char symbol) = 0;
    
    /** \details 
    Skips data from an <link OdDAI::Aggr, aggregate> until a specified symbol appears. 
    If a syntax error occurs the the method returns to the position before the symbol where the error appears.
    \param symbol [in] A symbol that should appear to stop skipping data.
    \returns true if the specified symbol appeared, and false if the specified symbol didn't appear or when a syntax error was found.
    */
    virtual bool skipUntilRet(const char symbol) = 0;
    
    /** \details 
    Reads an aggregate item. 
    \param readTo     [out] A placeholder for the read data.
    \param commaNeed  [in] A flag that determines whether data should be skipped until a comma symbol is found.
    \returns eOk if the value of a primitive type was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult read(TItem& readTo, bool commaNeed) = 0;
  };

  /** \details
  An abstract class that provides an interface for writing data to <link OdDAI::Aggr, aggregates>.
  */
  template<class TItem>
  class IAggrWriter
  {
  public:
  
    /** \details 
    Writes a symbol. 
    \param symbol[in] A symbol to write.
    \returns true if the symbol was successfully written; otherwise, the method returns false.
    */
    virtual bool wrChar(const char symbol) = 0;
    
    /** \details 
    Writes an item of a primitive type. 
    \param readTo     [out] A placeholder for the written data.
    \returns true if the value of a primitive type was successfully written; otherwise, the method returns false.
    */
    virtual bool wrPrimitive(TItem& readTo) = 0;
  };
  //DOM-IGNORE-END

  /** \details
  A base class for containers defined within a schema.
  */
  class DAI_EXPORT Aggr
  {
  public:

    /** \details
    Non-virtual destructor!
    */
    ~Aggr();

    /** \details
    Creates a new iterator along elements of aggregate.
    \return Returns a shared pointer to the newly created iterator.
    */
    IteratorPtr createIterator();

    /** \details
    Creates a new const iterator along elements of aggregate.
    \return Returns a shared pointer to the newly created const iterator.
    */
    ConstIteratorPtr createConstIterator() const;

    /** \details
    Checks if aggregate is unset.
    \return Returns true if aggregate is unset.
    */
    bool isNil() const;

    /** \details
    Clean the aggregate with deletion of all its content.
    */
    void nullify();

    /** \details
    Returns a value type of aggregate instance elements.
    \returns Returns a value type of aggregate instance elements.
    */
    const OdRxValueType&  type() const;

    /** \details
    Returns a type of aggregate.
    \returns Returns a type of aggregate.
    */
    AggrType aggrType() const;

    /** \details
    Check if aggregate is ordered.
    \returns Returns true if ordered, otherwise returns false.
    */
    bool isOrdered() const;

    /** \details
    Initializes an aggregate. Creates an empty instance inside aggregate.
    \returns Returns true if operation succeeded, in other case function  returns false.
    */
    bool createEmpty();


    /** \details
    Provides aggregates lower bound.
    \returns Returns an aggregate lower bound.
    */
    int getLowerBound() const;

    /** \details
    Provides aggregates upper bound.
    \returns Returns an aggregate upper bound.
    */
    int getUpperBound() const;


    /** \details
    Clear the aggregate with deletion of all its content.
    */
    void clear();

    /** \details
    Returns amount of aggregate elements.
    \returns Returns an amount of aggregate elements.
    */
    int getMemberCount() const;

    /** \details
    Check if aggregate contains a member.
    \param itemToCheck [in] an item to check.
    \returns Returns true if aggregate contains a member and false in otherwise.
    */
    bool isMember(const OdRxValue& itemToCheck) const;


    /** \details
    The equality operator for <link OdDAI::Aggr, aggregates>.
    \param aggr [in] Another <link OdDAI::Aggr, aggregate> (the right operand of comparison operation) to compare.
    \returns true if <link OdDAI::Aggr, aggregates> are equal; otherwise, the operator returns false.
    */
    bool operator == (const Aggr& aggr) const;

    /** \details
    Check aggregate for any elements. 
    \returns Returns true if aggregate is empty and false in otherwise.
    */
    bool empty() const;

    /** \details
    Clones the <link OdDAI::Aggr, aggregate> object, i.e. creates a new <link OdDAI::Aggr, aggregate> that is an exact copy of the origin <link OdDAI::Aggr, aggregate>.
    \param withItems [in] A flag that determines whether the original <link OdDAI::Aggr, aggregate> should be cloned with its items (equals true) 
                          or without them (false). By default, the flag equals true.
    \returns A valid pointer to the copy of the origin <link OdDAI::Aggr, aggregate> if success; otherwise, returns NULL.
    \remarks 
    Use the delete operator to clean the returned pointer.
    */
    Aggr* clone(bool withItems = true) const;

    /** \details
    Copy from aggregate.
    \param otherAggr [in] aggregate to copy from.
    \returns Returns true if copy was succeeded, otherwise false
    \remarks
    The copy should work between the same type aggregates. 
    In case with different aggregates types the function should be failed.
    */
    bool copyFromAggr(const Aggr& otherAggr);


    /** \details
    Template check if aggregate contains a member.
    \param itemToCheck [in] item to check.
    \returns Returns an amount of aggregate elements.
    */
    template<class TItem>
    bool isMember(const TItem& itemToCheck) const;

    /** \details
    Providing internal OdArray to the outside.
    \returns Returns constant pointer to internal array. If aggregate is empty it can return null.
    */
    template<class TItem>
    operator const OdArray<TItem>* () const;

    /** \details
    Provides the internal <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">OdArray</exref> object to the outside.
    \param to [in/out] A placeholder that should be filled with the constant valid pointer to the internal 
                       <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">OdArray</exref> object if the <link OdDAI::Aggr, aggregate> is not empty.
    \returns true if the <link OdDAI::Aggr, aggregate> is not empty; otherwise, the method returns false.
    */
    template<typename TItem>
    bool getArray(const OdArray<TItem>*& to) const;

    /** \details 
    Retrieves the elements of the <link OdDAI::Aggr, aggregate> as an <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">array</exref>.
    \param to [out] An <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">OdArray</exref> object that is the placeholder for the <link OdDAI::Aggr, aggregate> elements.
    \returns true if the elements were successfully returned; otherwise, the method returns false.
    */
    template<typename TItem, class TOtherItem>
    bool getArrayValues(OdArray<TOtherItem>& to) const;

    /** \details
    Sets <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">OdArray</exref> items to the <link OdDAI::Aggr,, aggregate>.
    \param from [in] An <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">array</exref> to copy items from.
    */
    template<typename TItem>
    void setArray(const OdArray<TItem>& from);

    /** \details 
    Adds new elements to the <link OdDAI::Aggr, aggregate> from an <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">array</exref>.
    \param from [in] An <exref target="../tkernel_api_cpp/OdArray@classT@classA.html">OdArray</exref> object that contains elements for the <link OdDAI::Aggr, aggregate>.
    */
    template<typename TItem, class TOtherItem>
    void setArrayValues(OdArray<TOtherItem>& from);

    /** \details 
    Reads the <link OdDAI::Aggr, aggregate> data from a STEP Physical File (SPF).
    \param readFiler [in] A raw pointer to the filer object that provides access to the content of the SPF file.
    \returns true if the data was successfully read; otherwise, the method returns false.
    */
    bool read(OdSpfFilerBase* readFiler);

    /** \details 
    Writes the <link OdDAI::Aggr, aggregate> data in a STEP Physical File (SPF).
    \param writeFiler [in] A raw pointer to the filer object that provides access to the content of the SPF file.
    \returns true if the data was successfully written; otherwise, the method returns false.
    */
    bool write(OdSpfFilerBase* writeFiler) const;
    
    /** \details 
    Creates a new <link OdDAI::Aggr, aggregate> of a specified type.
    \param createFrom [in] A raw pointer to an <link OdDAI::AggregationType, AggregationType> object that represents the type of the created aggregate.
    \returns A raw pointer to the created <link OdDAI::Aggr, aggregate> object.
    */
    static Aggr* CreateAggrByType(const AggregationType* createFrom);
    
    /** \details 
    Generates an item of the <link OdDAI::Aggr, aggregate> with unset value.
    \returns The generated item of a specified type.
    */
    template<typename TItem>
    TItem generateAggrItem() const;

    /** \details
     Checks aggregate for duplicate values.
      \returns true if all values in aggregate are unique, otherwise it returns false.
    */
    bool checkValuesUniqueness () const;

    /** \details
     Performs an attempt to find value within aggregation.
      \param startIndex  [in] Index to start search.
      \param valueToFind [in] Value to find.
      \returns Index of found item, or -1 if aggregation doesn't contain item with such value, starting from startIndex.
    */
    template<typename TItem>
    int hasValue(int startIndex, const TItem& valueToFind) const;

    /** \details
     Performs an attempt to find value within aggregation.
      \param startIndex  [in] Index to start search.
      \param valueToFind [in] Value to find.
      \returns Index of found item, or -1 if aggregation doesn't contain item with such value, starting from startIndex.
    */
    int hasValue(int startIndex, const OdRxValue& valueToFind) const;


    /** \details
     Returns internal aggregation type if it exists.
      \returns valid pointer of aggregation type for aggregate with complex(not POD) items, otherwise it returns nullptr.
    */
    const OdDAI::AggregationType* getAggregationTypeIfExist() const;

    //DOM-IGNORE-BEGIN

    /** \details
    Temporary method for OdArray compatibility.
    */

    Aggr& operator = (const Aggr& aggr) = delete;
    Aggr(const Aggr& aggr) = delete;
    Aggr(Aggr&& aggr) = delete;

    static void rxUninit();

  protected:
    Aggr(AggrInstance* defaultInstance);
    Aggr& operator = (Aggr&& aggr);

    template<class TInstance>
    TInstance instance() const;

  private:
    AggrInstance*   m_pInstance;

  };
}

#include "impl/daiAggr.hpp"

//DOM-IGNORE-END

#include "TD_PackPop.h"

#endif // _DAI_AGGR_BASE_H