Foundation Classes, Convert - Replace handle-based APIs with direct array access (#1057)

Refactor the Convert package to eliminate heap-allocated handle-based storage
in favor of direct NCollection_Array members, improving performance and
simplifying the API. Deprecate single-element accessors (Pole, Knot, etc.)
in favor of batch const-reference accessors (Poles, Knots, etc.).

Convert_ConicToBSplineCurve:
- Replace handle members (poles, weights, knots, mults) with direct
  NCollection_Array1 fields (myPoles, myWeights, myKnots, myMults).
- Replace BuildCosAndSin handle-based parameters with array references.
- Add batch accessors: Poles(), Weights(), Knots(), Multiplicities().
- Deprecate single-element accessors: Pole(), Weight(), Knot(), Multiplicity().
- Update all conic subclasses: Circle, Ellipse, Hyperbola, Parabola.

Convert_ElementarySurfaceToBSplineSurface:
- Replace handle members with direct NCollection_Array fields
  (myPoles, myWeights, myUKnots, myVKnots, myUMults, myVMults).
- Add Finalize() to trim oversized arrays in derived constructors.
- Add batch accessors: Poles(), Weights(), UKnots(), VKnots(),
  UMultiplicities(), VMultiplicities().
- Deprecate single-element accessors: Pole(), Weight(), UKnot(), VKnot(),
  UMultiplicity(), VMultiplicity().
- Update all surface subclasses: Cone, Cylinder, Sphere, Torus.

Convert_CompPolynomialToPoles / Convert_GridPolynomialToPoles:
- Replace handle-based output parameters with direct const-reference
  accessors for Poles, Knots, Multiplicities.
- Deprecate old handle-based Poles(), Knots(), Multiplicities() overloads.

Convert_CompBezierCurvesToBSplineCurve (2D and 3D):
- Extract common logic into Convert_CompBezierCurvesToBSplineCurveBase
  template header to eliminate code duplication.
- Replace handle<HArray1> members with direct NCollection_Array1 storage
  in the internal sequence, removing unnecessary heap indirection.

NCollection_Sequence:
- Fix Node constructors to use member initializer lists (copy/move
  construction) instead of default-construct + assign, which failed for
  types like NCollection_Array1 where operator= requires matching sizes.

Downstream callers migrated:
- AdvApprox_ApproxAFunction: use new const-ref Knots()/Multiplicities().
- AppDef_Variational: use new const-ref Knots()/Multiplicities().
- AdvApp2Var_ApproxAFunc2Var, AdvApp2Var_Patch: use new const-ref API.
- Geom2dConvert, GeomConvert, GeomConvert_1: use new const-ref API.
- GeomFill_PolynomialConvertor, GeomFill_QuasiAngularConvertor: adapted.
- Geom_OsculatingSurface: use direct array references instead of
  handle->Array*() calls.

Added GTests for all Convert classes covering conic curves,
elementary surfaces, CompBezier, CompPolynomial, and GridPolynomial
conversions.

src/FoundationClasses/TKMath/Convert/Convert_CompPolynomialToPoles.hxx

@@ -20,10 +20,10 @@
 #include <Standard.hxx>
 #include <Standard_DefineAlloc.hxx>
 #include <Standard_Handle.hxx>
+#include <Standard_Macro.hxx>
 
 #include <NCollection_Array1.hxx>
 #include <NCollection_HArray1.hxx>
-#include <Standard_Integer.hxx>
 #include <NCollection_Array2.hxx>
 #include <NCollection_HArray2.hxx>
 
@@ -109,26 +109,40 @@ public:
     const NCollection_Array1<double>& PolynomialIntervals,
     const NCollection_Array1<double>& TrueIntervals);
 
-  //! number of poles of the n-dimensional BSpline
-  Standard_EXPORT int NbPoles() const;
+  //! Returns the number of poles of the n-dimensional BSpline.
+  [[nodiscard]] Standard_EXPORT int NbPoles() const;
 
-  //! returns the poles of the n-dimensional BSpline
-  //! in the following format :
+  //! Returns the poles of the n-dimensional BSpline
+  //! in the following format:
   //! [1..NumPoles][1..Dimension]
-  Standard_EXPORT void Poles(occ::handle<NCollection_HArray2<double>>& Poles) const;
+  [[nodiscard]] Standard_EXPORT const NCollection_Array2<double>& Poles() const;
 
-  Standard_EXPORT int Degree() const;
+  //! Returns the poles of the n-dimensional BSpline via output parameter.
+  Standard_DEPRECATED("Use Poles() returning const reference instead")
+  Standard_EXPORT void Poles(occ::handle<NCollection_HArray2<double>>& thePoles) const;
 
-  //! Degree of the n-dimensional Bspline
-  Standard_EXPORT int NbKnots() const;
+  //! Returns the degree of the n-dimensional BSpline.
+  [[nodiscard]] Standard_EXPORT int Degree() const;
 
-  //! Knots of the n-dimensional Bspline
-  Standard_EXPORT void Knots(occ::handle<NCollection_HArray1<double>>& K) const;
+  //! Returns the number of knots of the n-dimensional BSpline.
+  [[nodiscard]] Standard_EXPORT int NbKnots() const;
 
-  //! Multiplicities of the knots in the BSpline
-  Standard_EXPORT void Multiplicities(occ::handle<NCollection_HArray1<int>>& M) const;
+  //! Returns the knots of the n-dimensional BSpline.
+  [[nodiscard]] Standard_EXPORT const NCollection_Array1<double>& Knots() const;
 
-  Standard_EXPORT bool IsDone() const;
+  //! Returns the knots of the n-dimensional BSpline via output parameter.
+  Standard_DEPRECATED("Use Knots() returning const reference instead")
+  Standard_EXPORT void Knots(occ::handle<NCollection_HArray1<double>>& theKnots) const;
+
+  //! Returns the multiplicities of the knots in the BSpline.
+  [[nodiscard]] Standard_EXPORT const NCollection_Array1<int>& Multiplicities() const;
+
+  //! Returns the multiplicities of the knots via output parameter.
+  Standard_DEPRECATED("Use Multiplicities() returning const reference instead")
+  Standard_EXPORT void Multiplicities(occ::handle<NCollection_HArray1<int>>& theMults) const;
+
+  //! Returns true if the conversion was successful.
+  [[nodiscard]] Standard_EXPORT bool IsDone() const;
 
 private:
   Standard_EXPORT void Perform(const int                         NumCurves,
@@ -139,12 +153,12 @@ private:
                                const NCollection_Array2<double>& PolynomialIntervals,
                                const NCollection_Array1<double>& TrueIntervals);
 
-  occ::handle<NCollection_HArray1<double>> myFlatKnots;
-  occ::handle<NCollection_HArray1<double>> myKnots;
-  occ::handle<NCollection_HArray1<int>>    myMults;
-  occ::handle<NCollection_HArray2<double>> myPoles;
-  int                                      myDegree;
-  bool                                     myDone;
+  NCollection_Array1<double> myFlatKnots;
+  NCollection_Array1<double> myKnots;
+  NCollection_Array1<int>    myMults;
+  NCollection_Array2<double> myPoles;
+  int                        myDegree;
+  bool                       myDone;
 };
 
 #endif // _Convert_CompPolynomialToPoles_HeaderFile