@itwin/core-geometry 5.3.0-dev.2 → 5.3.0-dev.23

package/lib/esm/geometry3d/GrowableXYArray.js

@@ -7,45 +7,41 @@
  */
 import { Geometry } from "../Geometry";
 import { GrowableXYZArray } from "./GrowableXYZArray";
-import { IndexedXYCollection } from "./IndexedXYCollection";
+import { IndexedReadWriteXYCollection, IndexedXYCollection } from "./IndexedXYCollection";
 import { Point2d, Vector2d } from "./Point2dVector2d";
 import { Point3d } from "./Point3dVector3d";
-/** `GrowableXYArray` manages a (possibly growing) Float64Array to pack xy coordinates.
+/**
+ * `GrowableXYArray` manages a (possibly growing) Float64Array to pack xy coordinates.
  * @public
  */
-export class GrowableXYArray extends IndexedXYCollection {
-    /**
-     * array of packed xy xy xy components
-     */
+export class GrowableXYArray extends IndexedReadWriteXYCollection {
+    /** Array of packed xy xy xy components. */
     _data;
-    /**
-     * Number of xy tuples (not floats) in the array
-     */
+    /** Number of xy tuples (not floats) in the array. */
     _xyInUse;
-    /**
-     * capacity in xy tuples. (not floats)
-     */
+    /** Capacity in xy tuples. (not floats). */
     _xyCapacity;
-    /**
-     * multiplier used by ensureCapacity to expand requested reallocation size
-     */
+    /** Multiplier used by ensureCapacity to expand requested reallocation size. */
     _growthFactor;
-    /** Construct a new GrowablePoint2d array.
-     * @param numPoints initial capacity in xy tuples (default 8)
-     * @param growthFactor used by ensureCapacity to expand requested reallocation size (default 1.5)
+    /**
+     * Construct a new GrowablePoint2d array.
+     * @param numPoints initial capacity in xy tuples (default 8).
+     * @param growthFactor used by ensureCapacity to expand requested reallocation size (default 1.5).
+     * @param data optional pre-existing Float64Array to use as the backing memory. If supplied, numPoints is ignored.
      */
-    constructor(numPoints = 8, growthFactor) {
+    constructor(numPoints = 8, growthFactor, data) {
         super();
-        this._data = new Float64Array(numPoints * 2); // 2 values per point
+        this._data = data || new Float64Array(numPoints * 2); // 2 values per point
         this._xyInUse = 0;
-        this._xyCapacity = numPoints;
+        this._xyCapacity = data ? data.length / 2 : numPoints;
         this._growthFactor = (undefined !== growthFactor && growthFactor >= 1.0) ? growthFactor : 1.5;
     }
-    /** Copy xy points from source array. Does not reallocate or change active point count.
-     * @param source array to copy from
-     * @param sourceCount copy the first sourceCount points; all points if undefined
-     * @param destOffset copy to instance array starting at this point index; zero if undefined
-     * @return count and offset of points copied
+    /**
+     * Copy xy points from source array. Does not reallocate or change active point count.
+     * @param source array to copy from.
+     * @param sourceCount copy the first sourceCount points; all points if undefined.
+     * @param destOffset copy to instance array starting at this point index; zero if undefined.
+     * @return count and offset of points copied.
      */
     copyData(source, sourceCount, destOffset) {
         // validate inputs and convert from points to entries
@@ -74,30 +70,45 @@ export class GrowableXYArray extends IndexedXYCollection {
         return { count: myCount / 2, offset: myOffset / 2 };
     }
     /** The number of points in use. When the length is increased, the array is padded with zeroes. */
-    get length() { return this._xyInUse; }
-    set length(newLength) { this.resize(newLength, true); }
+    get length() {
+        return this._xyInUse;
+    }
+    set length(newLength) {
+        this.resize(newLength, true);
+    }
     /** Return the number of float64 in use. */
-    get float64Length() { return this._xyInUse * 2; }
-    /** Return the raw packed data.
+    get float64Length() {
+        return this._xyInUse * 2;
+    }
+    /**
+     * Return the raw packed data.
      * * Note that the length of the returned Float64Array is a count of doubles, and includes the excess capacity
      */
-    float64Data() { return this._data; }
-    /** If necessary, increase the capacity to a new pointCount.  Current coordinates and point count (length) are unchanged. */
+    float64Data() {
+        return this._data;
+    }
+    /** If necessary, increase the capacity to a new pointCount. Current coordinates and point count (length) are unchanged. */
     ensureCapacity(pointCapacity, applyGrowthFactor = true) {
         if (pointCapacity > this._xyCapacity) {
             if (applyGrowthFactor)
-                pointCapacity *= this._growthFactor;
+                pointCapacity = Math.trunc(pointCapacity * this._growthFactor);
             const prevData = this._data;
-            this._data = new Float64Array(pointCapacity * 2);
+            if (this._data.buffer instanceof ArrayBuffer)
+                this._data = new Float64Array(new ArrayBuffer(pointCapacity * 2 * this._data.BYTES_PER_ELEMENT));
+            else
+                this._data = new Float64Array(new SharedArrayBuffer(pointCapacity * 2 * this._data.BYTES_PER_ELEMENT));
             this.copyData(prevData, this._xyInUse);
             this._xyCapacity = pointCapacity;
         }
     }
     /**
-     * * If pointCount is less than current length, just reset current length to pointCount, effectively trimming active points but preserving original capacity.
-     * * If pointCount is greater than current length, reallocate to exactly pointCount, copy existing points, and optionally pad excess with zero.
-     * @param pointCount new number of active points in array
-     * @param padWithZero when increasing point count, whether to zero out new points (default false)
+     * Resize the internal storage to hold a new number of points.
+     * * If pointCount is less than current length, just reset current length to pointCount, effectively trimming active
+     * points but preserving original capacity.
+     * * If pointCount is greater than current length, reallocate to exactly pointCount, copy existing points, and
+     * optionally pad excess with zero.
+     * @param pointCount new number of active points in array.
+     * @param padWithZero when increasing point count, whether to zero out new points (default false).
      */
     resize(pointCount, padWithZero) {
         if (pointCount >= 0 && pointCount < this._xyInUse)
@@ -109,17 +120,15 @@ export class GrowableXYArray extends IndexedXYCollection {
             this._xyInUse = pointCount;
         }
     }
-    /**
-     * Make a copy of the (active) points in this array.
-     * (The clone does NOT get excess capacity)
-     */
+    /** Make a copy of the (active) points in this array (the clone does NOT get excess capacity). */
     clone() {
         const newPoints = new GrowableXYArray(this.length);
         newPoints.copyData(this._data, this.length);
         newPoints._xyInUse = this.length;
         return newPoints;
     }
-    /** Create an array populated from
+    /**
+     * Create an array by copying data from various point formats.
      * Valid inputs are:
      * * Point2d
      * * Point3d
@@ -129,7 +138,9 @@ export class GrowableXYArray extends IndexedXYCollection {
      * * A GrowableXYArray
      * * Any json object satisfying Point3d.isXAndY
      * * A Float64Array of doubles, interpreted as xyxy
-     * * An array of any of the above
+     * * An array of any of the above.
+     * @param data source points.
+     * @param result optional pre-allocated GrowableXYArray to clear and fill.
      */
     static create(data, result) {
         if (result) {
@@ -142,23 +153,32 @@ export class GrowableXYArray extends IndexedXYCollection {
         result.pushFrom(data);
         return result;
     }
-    /** Restructure MultiLineStringDataVariant as array of GrowableXYZArray
+    /**
+     * Create a new GrowableXYArray capturing the provided data. The data is not copied, just referenced.
+     * @param data source data to capture.
+     * @returns a new GrowableXYArray object that references the provided data.
+     */
+    static createCapture(data) {
+        return new GrowableXYArray(0, undefined, data);
+    }
+    /**
+     * Restructure MultiLineStringDataVariant as array of GrowableXYZArray
      * @deprecated in 4.2.0 - will not be removed until after 2026-06-13. Moved to GrowableXYZArray class.
      */
     static createArrayOfGrowableXYZArray(data) {
         return GrowableXYZArray.createArrayOfGrowableXYZArray(data);
     }
-    /** push a point to the end of the array */
+    /** Push a point to the end of the array. */
     push(toPush) {
         this.pushXY(toPush.x, toPush.y);
     }
-    /** push all points of an array */
+    /** Push all points of an array. */
     pushAll(points) {
         this.ensureCapacity(this._xyInUse + points.length, false);
         for (const p of points)
             this.push(p);
     }
-    /** push all points of an array */
+    /** Push all points of an array. */
     pushAllXYAndZ(points) {
         this.ensureCapacity(this._xyInUse + points.length, false);
         if (points instanceof GrowableXYZArray) {
@@ -172,7 +192,8 @@ export class GrowableXYArray extends IndexedXYCollection {
                 this.pushXY(p.x, p.y);
         }
     }
-    /** Push copies of points from variant sources.
+    /**
+     * Push copies of points from variant sources.
      * Valid inputs are:
      * * Point2d
      * * Point3d
@@ -181,7 +202,7 @@ export class GrowableXYArray extends IndexedXYCollection {
      * * A GrowableXYZArray
      * * Any json object satisfying Point3d.isXAndY
      * * A Float64Array of doubles, interpreted as xyxy
-     * * An array of any of the above
+     * * An array of any of the above.
      */
     pushFrom(p) {
         if (p instanceof Point3d) {
@@ -203,7 +224,7 @@ export class GrowableXYArray extends IndexedXYCollection {
             this.pushXY(p[0], p[1]);
         }
         else if (Array.isArray(p)) {
-            // direct recursion re-wraps p and goes infinite. Unroll here.
+            // direct recursion re-wraps p and goes infinite; unroll here.
             for (const q of p)
                 this.pushFrom(q);
         }
@@ -219,7 +240,7 @@ export class GrowableXYArray extends IndexedXYCollection {
     }
     /**
      * Replicate numWrap xy values from the front of the array as new values at the end.
-     * @param numWrap number of xy values to replicate
+     * @param numWrap number of xy values to replicate.
      */
     pushWrap(numWrap) {
         if (this._xyInUse >= numWrap) {
@@ -238,16 +259,17 @@ export class GrowableXYArray extends IndexedXYCollection {
         this._data[index + 1] = y;
         this._xyInUse++;
     }
-    /** Remove one point from the back.
+    /**
+     * Remove one point from the back.
      * * NOTE that (in the manner of std::vector native) this is "just" removing the point -- no point is NOT returned.
-     * * Use `back ()` to get the last x,y assembled into a `Point2d `
+     * * Use `back ()` to get the last x,y assembled into a `Point2d`.
      */
     pop() {
         if (this._xyInUse > 0)
             this._xyInUse--;
     }
     /**
-     * Test if index is valid for an xy (point or vector) within this array
+     * Test if index is valid for an xy (point or vector) within this array.
      * @param index xy index to test.
      */
     isIndexValid(index) {
@@ -255,38 +277,34 @@ export class GrowableXYArray extends IndexedXYCollection {
             return false;
         return true;
     }
-    /**
-     * Clear all xy data, but leave capacity unchanged.
-     */
+    /** Clear all xy data, but leave capacity unchanged. */
     clear() {
         this._xyInUse = 0;
     }
     /**
-     * Get a point by index, strongly typed as a Point2d.  This is unchecked.  Use atPoint2dIndex to have validity test.
-     * @param pointIndex index to access
-     * @param result optional result
+     * Get a point by index, strongly typed as a `Point2d`. This is unchecked. Use atPoint2dIndex to have validity test.
+     * @param pointIndex index to access.
+     * @param result optional result.
      */
     getPoint2dAtUncheckedPointIndex(pointIndex, result) {
         const index = 2 * pointIndex;
         return Point2d.create(this._data[index], this._data[index + 1], result);
     }
     /**
-     * Get x coordinate by point index, with no index checking
-     * @param pointIndex index to access
+     * Get x coordinate by point index, with no index checking.
+     * @param pointIndex index to access.
      */
     getXAtUncheckedPointIndex(pointIndex) {
         return this._data[2 * pointIndex];
     }
     /**
-     * Get y coordinate by point index, with no index checking
-     * @param pointIndex index to access
+     * Get y coordinate by point index, with no index checking.
+     * @param pointIndex index to access.
      */
     getYAtUncheckedPointIndex(pointIndex) {
         return this._data[2 * pointIndex + 1];
     }
-    /**
-     * Gather all points as a Point2d[]
-     */
+    /** Gather all points as a Point2d[]. */
     getPoint2dArray() {
         const n = 2 * this._xyInUse;
         const result = [];
@@ -295,7 +313,7 @@ export class GrowableXYArray extends IndexedXYCollection {
             result.push(Point2d.create(data[i], data[i + 1]));
         return result;
     }
-    /** copy xy into strongly typed Point2d */
+    /** Copy xy into strongly typed Point2d. */
     getPoint2dAtCheckedPointIndex(pointIndex, result) {
         if (this.isIndexValid(pointIndex)) {
             const index = 2 * pointIndex;
@@ -303,7 +321,7 @@ export class GrowableXYArray extends IndexedXYCollection {
         }
         return undefined;
     }
-    /** copy xy into strongly typed Vector2d */
+    /** Copy xy into strongly typed Vector2d. */
     getVector2dAtCheckedVectorIndex(vectorIndex, result) {
         if (this.isIndexValid(vectorIndex)) {
             const index = 2 * vectorIndex;
@@ -313,9 +331,9 @@ export class GrowableXYArray extends IndexedXYCollection {
     }
     /**
      * Read coordinates from source array, place them at index within this array.
-     * @param destIndex point index where coordinates are to be placed in this array
-     * @param source source array
-     * @param sourceIndex point index in source array
+     * @param destIndex point index where coordinates are to be placed in this array.
+     * @param source source array.
+     * @param sourceIndex point index in source array.
      * @returns true if destIndex and sourceIndex are both valid.
      */
     transferFromGrowableXYArray(destIndex, source, sourceIndex) {
@@ -329,13 +347,13 @@ export class GrowableXYArray extends IndexedXYCollection {
         return false;
     }
     /**
-     * push coordinates from the source array to the end of this array.
-     * @param source source array
-     * @param sourceIndex xy index within the source.  If undefined, push entire contents of source
+     * Push coordinates from the source array to the end of this array.
+     * @param source source array.
+     * @param sourceIndex xy index within the source.  If undefined, push entire contents of source.
      * @returns number of points pushed.
      */
     pushFromGrowableXYArray(source, sourceIndex) {
-        // full array push  . . .
+        // full array push
         if (sourceIndex === undefined) {
             const numXYAdd = source.length;
             this.ensureCapacity(this.length + numXYAdd, false);
@@ -343,7 +361,7 @@ export class GrowableXYArray extends IndexedXYCollection {
             this._xyInUse += numXYAdd;
             return numXYAdd;
         }
-        // single point push . . .
+        // single point push
         if (source.isIndexValid(sourceIndex)) {
             const j = sourceIndex * 2;
             this.pushXY(source._data[j], source._data[j + 1]);
@@ -352,8 +370,8 @@ export class GrowableXYArray extends IndexedXYCollection {
         return 0;
     }
     /**
-     * * Compute a point at fractional coordinate between points i and j of source
-     * * push onto this array.
+     * * Compute a point at fractional coordinate between points i and j of source.
+     * * Push onto this array.
      */
     pushInterpolatedFromGrowableXYArray(source, i, fraction, j) {
         if (source.isIndexValid(i) && source.isIndexValid(j)) {
@@ -366,7 +384,7 @@ export class GrowableXYArray extends IndexedXYCollection {
     }
     /**
      * Create an array of xy points from source xyz points.
-     * @param source source array of xyz
+     * @param source source array of xyz.
      * @param transform optional transform to apply to xyz points.
      * @param dest optional result.
      */
@@ -394,17 +412,13 @@ export class GrowableXYArray extends IndexedXYCollection {
         }
         return dest;
     }
-    /**
-     * Return the first point, or undefined if the array is empty.
-     */
+    /** Return the first point, or undefined if the array is empty. */
     front(result) {
         if (this._xyInUse === 0)
             return undefined;
         return this.getPoint2dAtUncheckedPointIndex(0, result);
     }
-    /**
-     * Return the last point, or undefined if the array is empty.
-     */
+    /** Return the last point, or undefined if the array is empty. */
     back(result) {
         if (this._xyInUse < 1)
             return undefined;
@@ -412,8 +426,8 @@ export class GrowableXYArray extends IndexedXYCollection {
     }
     /**
      * Set the coordinates of a single point.
-     * @param pointIndex index of point to set
-     * @param value coordinates to set
+     * @param pointIndex index of point to set.
+     * @param value coordinates to set.
      */
     setAtCheckedPointIndex(pointIndex, value) {
         if (!this.isIndexValid(pointIndex))
@@ -425,9 +439,9 @@ export class GrowableXYArray extends IndexedXYCollection {
     }
     /**
      * Set the coordinates of a single point given as coordinates.
-     * @param pointIndex index of point to set
-     * @param x x coordinate
-     * @param y y coordinate
+     * @param pointIndex index of point to set.
+     * @param x x coordinate.
+     * @param y y coordinate.
      */
     setXYAtCheckedPointIndex(pointIndex, x, y) {
         if (!this.isIndexValid(pointIndex))
@@ -437,9 +451,7 @@ export class GrowableXYArray extends IndexedXYCollection {
         this._data[index + 1] = y;
         return true;
     }
-    /**
-     * Copy all points into a simple array of Point3d with given z.
-     */
+    /** Copy all points into a simple array of Point3d with given z. */
     getPoint3dArray(z = 0) {
         const n = 2 * this._xyInUse;
         const result = [];
@@ -448,7 +460,7 @@ export class GrowableXYArray extends IndexedXYCollection {
             result.push(Point3d.create(data[i], data[i + 1], z));
         return result;
     }
-    /** reverse the order of points. */
+    /** Reverse the order of points. */
     reverseInPlace() {
         const n = this.length;
         let j0, j1;
@@ -467,7 +479,7 @@ export class GrowableXYArray extends IndexedXYCollection {
             data[j1] = a;
         }
     }
-    /** multiply each point by the transform, replace values. */
+    /** Multiply each point by the transform, replace values. */
     multiplyTransformInPlace(transform) {
         const data = this._data;
         const nDouble = this.float64Length;
@@ -484,7 +496,7 @@ export class GrowableXYArray extends IndexedXYCollection {
             data[i + 1] = coffs[3] * x + coffs[4] * y + y0;
         }
     }
-    /** multiply each xy (as a vector) by matrix, replace values. */
+    /** Multiply each xy (as a vector) by matrix, replace values. */
     multiplyMatrix3dInPlace(matrix) {
         const data = this._data;
         const nDouble = this.float64Length;
@@ -498,7 +510,7 @@ export class GrowableXYArray extends IndexedXYCollection {
             data[i + 1] = coffs[3] * x + coffs[4] * y;
         }
     }
-    /** multiply each point by the transform, replace values. */
+    /** Multiply each point by the transform, replace values. */
     tryTransformInverseInPlace(transform) {
         const data = this._data;
         const nDouble = this.float64Length;
@@ -533,7 +545,7 @@ export class GrowableXYArray extends IndexedXYCollection {
                 rangeToExtend.extendXY(data[i], data[i + 1]);
         }
     }
-    /** sum the lengths of segments between points. */
+    /** Sum the lengths of segments between points. */
     sumLengths() {
         let sum = 0.0;
         const n = 2 * (this._xyInUse - 1); // Length already takes into account what specifically is in use
@@ -544,7 +556,7 @@ export class GrowableXYArray extends IndexedXYCollection {
     }
     /**
      * Multiply each x,y by the scale factor.
-     * @param factor
+     * @param factor scale factor.
      */
     scaleInPlace(factor) {
         if (this._data) {
@@ -553,7 +565,7 @@ export class GrowableXYArray extends IndexedXYCollection {
                 this._data[i] = this._data[i] * factor;
         }
     }
-    /** Compute a point at fractional coordinate between points i and j */
+    /** Compute a point at fractional coordinate between points i and j. */
     interpolate(i, fraction, j, result) {
         if (this.isIndexValid(i) && this.isIndexValid(j)) {
             const fraction0 = 1.0 - fraction;
@@ -564,10 +576,10 @@ export class GrowableXYArray extends IndexedXYCollection {
         }
         return undefined;
     }
-    /** Sum the signed areas of the projection to xy plane */
+    /** Sum the signed areas of the projection to xy plane. */
     areaXY() {
         let area = 0.0;
-        const n = 2 * this._xyInUse; // float count !!
+        const n = 2 * this._xyInUse; // float count
         if (n > 4) {
             const x0 = this._data[n - 2];
             const y0 = this._data[n - 1];
@@ -583,7 +595,7 @@ export class GrowableXYArray extends IndexedXYCollection {
         }
         return 0.5 * area;
     }
-    /** Compute a vector from index origin i to indexed target j  */
+    /** Compute a vector from index origin i to indexed target j. */
     vectorIndexIndex(i, j, result) {
         if (!this.isIndexValid(i) || !this.isIndexValid(j))
             return undefined;
@@ -592,7 +604,7 @@ export class GrowableXYArray extends IndexedXYCollection {
         j = 2 * j;
         return Vector2d.create(data[j] - data[i], data[j + 1] - data[i + 1], result);
     }
-    /** Compute a vector from origin to indexed target j */
+    /** Compute a vector from origin to indexed target j. */
     vectorXAndYIndex(origin, j, result) {
         if (this.isIndexValid(j)) {
             const data = this._data;
@@ -601,7 +613,7 @@ export class GrowableXYArray extends IndexedXYCollection {
         }
         return undefined;
     }
-    /** Compute the cross product of vectors from from indexed origin to indexed targets i and j */
+    /** Compute the cross product of vectors from from indexed origin to indexed targets i and j. */
     crossProductIndexIndexIndex(originIndex, targetAIndex, targetBIndex) {
         if (this.isIndexValid(originIndex) && this.isIndexValid(targetAIndex) && this.isIndexValid(targetBIndex)) {
             const i = originIndex * 2;
@@ -612,7 +624,7 @@ export class GrowableXYArray extends IndexedXYCollection {
         }
         return undefined;
     }
-    /** Compute the cross product of vectors from from origin to indexed targets i and j */
+    /** Compute the cross product of vectors from from origin to indexed targets i and j. */
     crossProductXAndYIndexIndex(origin, targetAIndex, targetBIndex) {
         if (this.isIndexValid(targetAIndex) && this.isIndexValid(targetBIndex)) {
             const j = targetAIndex * 2;
@@ -652,7 +664,7 @@ export class GrowableXYArray extends IndexedXYCollection {
         // if both are null it is equal, otherwise unequal
         return (!dataA && !dataB);
     }
-    /** Return an array of block indices sorted per compareLexicalBlock function */
+    /** Return an array of block indices sorted per compareLexicalBlock function. */
     sortIndicesLexical() {
         const n = this._xyInUse;
         // let numCompare = 0;
@@ -678,13 +690,13 @@ export class GrowableXYArray extends IndexedXYCollection {
             if (ax < bx)
                 return -1;
         }
-        return ia - ib; // so original order is maintained among duplicates !!!!
+        return ia - ib; // so original order is maintained among duplicates
     }
-    /** Access a single double at offset within a block.  This has no index checking. */
+    /** Access a single double at offset within a block. This has no index checking. */
     component(pointIndex, componentIndex) {
         return this._data[2 * pointIndex + componentIndex];
     }
-    /** Toleranced equality test */
+    /** Toleranced equality test. */
     isAlmostEqual(other, tolerance = Geometry.smallMetricDistance) {
         const numXY = this._xyInUse;
         if (other._xyInUse !== numXY)