OCCT

// Copyright (c) 2026 OPEN CASCADE SAS
//
// This file is part of Open CASCADE Technology software library.
//
// This library is free software; you can redistribute it and/or modify it under
// the terms of the GNU Lesser General Public License version 2.1 as published
// by the Free Software Foundation, with special exception defined in the file
// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
// distribution for complete text of the license and disclaimer of any warranty.
//
// Alternatively, this file may be used under the terms of Open CASCADE
// commercial license or contractual agreement.

#ifndef _BRepGraph_RelatedIterator_HeaderFile
#define _BRepGraph_RelatedIterator_HeaderFile

#include <BRepGraph.hxx>
#include <BRepGraph_DefsIterator.hxx>
#include <BRepGraph_RefsIterator.hxx>
#include <BRepGraph_ReverseIterator.hxx>
#include <BRepGraph_RefsView.hxx>
#include <BRepGraph_Tool.hxx>
#include <BRepGraph_TopoView.hxx>
#include <NCollection_ForwardRange.hxx>
#include <NCollection_LinearVector.hxx>

//! @brief Single-level iterator over semantically related topology nodes.
//! @see BRepGraph class comment "Iterator guide" for choosing between iterator types.
//!
//! The iterator yields immediate related nodes for one source node together
//! with the relation kind explaining why each node is returned. Results are not
//! deduplicated; callers that need uniqueness should filter on top.
class BRepGraph_RelatedIterator
{
public:
  //! Topological relation kinds yielded by the iterator.
  //! Only geometry-level relations are supported (Face, Edge, Vertex, Wire, CoEdge).
  //! Assembly/container nodes (Solid, Shell, Compound, Product, Occurrence) have
  //! no topological relations - use BRepGraph_ChildExplorer / BRepGraph_ParentExplorer instead.
  enum class RelationKind
  {
    BoundaryEdge,     //!< Face -> Edge bounding the face
    AdjacentFace,     //!< Face -> Face sharing an edge
    OuterWire,        //!< Face -> Wire (outer boundary)
    ReferencedByFace, //!< Edge -> Face that uses this edge
    IncidentVertex,   //!< Edge -> Vertex (start/end)
    WireCoEdge,       //!< Wire -> CoEdge (member)
    OwningFace,       //!< Wire/CoEdge -> Face (container)
    IncidentEdge,     //!< Vertex -> Edge (touching)
    ParentEdge,       //!< CoEdge -> Edge (underlying definition)
    SeamPair,         //!< CoEdge -> CoEdge (seam twin)
  };

  //! Internal traversal stage tracking which sub-iteration is active.
  enum class Stage
  {
    First,    //!< Primary relation iteration.
    Second,   //!< Secondary relation iteration.
    Third,    //!< Tertiary relation iteration.
    Finished, //!< All relations exhausted.
  };

  //! Complete resumable iterator position.
  //!
  //! The position is process-local and valid only with the unchanged graph from
  //! which it was obtained. It owns no graph data and performs no allocation.
  struct Position
  {
    BRepGraph_NodeId Current;
    RelationKind     Relation   = RelationKind::BoundaryEdge;
    Stage            StageValue = Stage::First;
    uint32_t         Index      = 0;
    uint32_t         InnerIndex = 0;
    uint32_t         DeepIndex  = 0;
    bool             HasCurrent = false;
  };

  //! Construct an iterator over all semantically related nodes of the given source node.
  //! @param[in] theGraph graph containing the node
  //! @param[in] theNode  source node whose relations are iterated
  BRepGraph_RelatedIterator(const BRepGraph& theGraph, const BRepGraph_NodeId theNode)
      : myGraph(&theGraph),
        myNode(theNode)
  {
    advance();
  }

  //! Resume an iterator from a previously saved position.
  //! @param[in] theGraph unchanged graph that produced the position
  //! @param[in] theNode source node whose relations are iterated
  //! @param[in] thePosition process-local iterator position
  BRepGraph_RelatedIterator(const BRepGraph&       theGraph,
                            const BRepGraph_NodeId theNode,
                            const Position&        thePosition)
      : myGraph(&theGraph),
        myNode(theNode),
        myCurrent(thePosition.Current),
        myRelation(thePosition.Relation),
        myStage(thePosition.StageValue),
        myIndex(thePosition.Index),
        myInnerIndex(thePosition.InnerIndex),
        myDeepIndex(thePosition.DeepIndex),
        myHasCurrent(thePosition.HasCurrent)
  {
  }

  //! Return the complete position for later resumption.
  //! @return process-local position at the current item
  [[nodiscard]] Position CurrentPosition() const
  {
    return {myCurrent, myRelation, myStage, myIndex, myInnerIndex, myDeepIndex, myHasCurrent};
  }

  //! True if another related node is available.
  [[nodiscard]] bool More() const { return myHasCurrent; }

  //! Advance to the next related node.
  void Next()
  {
    if (!myHasCurrent)
    {
      return;
    }
    advance();
  }

  //! Return the current related node id.
  [[nodiscard]] const BRepGraph_NodeId& Current() const { return myCurrent; }

  //! Return the relation kind explaining why the current node is related.
  [[nodiscard]] RelationKind CurrentRelation() const { return myRelation; }

  //! Returns an STL-compatible iterator for range-based for loops.
  NCollection_ForwardRangeIterator<BRepGraph_RelatedIterator> begin()
  {
    return NCollection_ForwardRangeIterator<BRepGraph_RelatedIterator>(this);
  }

  //! Returns a sentinel marking the end of iteration.
  NCollection_ForwardRangeSentinel end() const { return NCollection_ForwardRangeSentinel{}; }

private:
  [[nodiscard]] bool setCurrent(const BRepGraph_NodeId theNode, const RelationKind theRelation);

  template <class IteratorT>
  [[nodiscard]] bool advanceRefChildren(IteratorT theIterator, const RelationKind theRelation)
  {
    for (; theIterator.More(); theIterator.Next())
    {
      if (theIterator.Index() < myIndex)
      {
        continue;
      }

      myIndex = theIterator.Index() + 1;
      BRepGraph_NodeId aChildNode;
      if constexpr (std::is_convertible_v<decltype(theIterator.CurrentId()), BRepGraph_RefId>)
      {
        aChildNode = myGraph->Refs().Gen().ChildNode(theIterator.CurrentId());
      }
      else
      {
        aChildNode = BRepGraph_NodeId(theIterator.CurrentId());
      }
      return setCurrent(aChildNode, theRelation);
    }

    return false;
  }

  template <class IteratorT>
  [[nodiscard]] bool advanceDefChildren(IteratorT theIterator, const RelationKind theRelation)
  {
    for (; theIterator.More(); theIterator.Next())
    {
      if (theIterator.Index() < myIndex)
      {
        continue;
      }

      myIndex = theIterator.Index() + 1;
      return setCurrent(BRepGraph_NodeId(theIterator.CurrentId()), theRelation);
    }

    return false;
  }

  [[nodiscard]] bool advanceFaceBoundaryEdge();

  [[nodiscard]] bool advanceAdjacentFace();

  [[nodiscard]] bool advanceEdgeVertex()
  {
    return advanceDefChildren(
      BRepGraph_DefsVertexOfEdge(*myGraph, BRepGraph_EdgeId::FromNodeId(myNode)),
      RelationKind::IncidentVertex);
  }

  //! Advance through a relation iterator (e.g. BRepGraph_FacesOfEdge).
  //! Constructs a ParentsOf starting at myIndex for O(1) amortized resumption.
  template <typename TypedIdT>
  [[nodiscard]] bool advanceParents(const NCollection_LinearVector<TypedIdT>& theParents,
                                    const RelationKind                        theRelation)
  {
    BRepGraph_ReverseIterator::ParentsOf<TypedIdT, NCollection_LinearVector<TypedIdT>> anIt(
      *myGraph,
      theParents,
      myIndex);
    if (anIt.More())
    {
      myIndex = anIt.Index() + 1;
      return setCurrent(BRepGraph_NodeId(anIt.CurrentId()), theRelation);
    }

    return false;
  }

  template <typename IteratorT>
  [[nodiscard]] bool advanceParentIterator(IteratorT theIterator, const RelationKind theRelation)
  {
    if (theIterator.More())
    {
      myIndex = theIterator.Index() + 1;
      return setCurrent(BRepGraph_NodeId(theIterator.CurrentId()), theRelation);
    }
    return false;
  }

  Standard_EXPORT void advance();

private:
  const BRepGraph* myGraph;
  BRepGraph_NodeId myNode;
  BRepGraph_NodeId myCurrent;
  RelationKind     myRelation   = RelationKind::BoundaryEdge;
  Stage            myStage      = Stage::First;
  uint32_t         myIndex      = 0;
  uint32_t         myInnerIndex = 0;
  uint32_t         myDeepIndex  = 0;
  bool             myHasCurrent = false;
};

#endif // _BRepGraph_RelatedIterator_HeaderFile