GH-39131: [JS] Add at() for array like types

js/src/recordbatch.ts

@@ -20,6 +20,7 @@ import { Table } from './table.js';
 import { Vector } from './vector.js';
 import { Schema, Field } from './schema.js';
 import { DataType, Struct, Null, TypeMap } from './type.js';
+import { wrapIndex } from './util/vector.js';
 
 import { instance as getVisitor } from './visitor/get.js';
 import { instance as setVisitor } from './visitor/set.js';
@@ -116,7 +117,7 @@ export class RecordBatch<T extends TypeMap = any> {
     }
 
     /**
-     * Check whether an element is null.
+     * Check whether an row is null.
      * @param index The index at which to read the validity bitmap.
      */
     public isValid(index: number) {
@@ -125,15 +126,23 @@ export class RecordBatch<T extends TypeMap = any> {
 
     /**
      * Get a row by position.
-     * @param index The index of the element to read.
+     * @param index The index of the row to read.
      */
     public get(index: number) {
         return getVisitor.visit(this.data, index);
     }
 
+    /**
+      * Get a row value by position.
+      * @param index The index of the row to read. A negative index will count back from the last row.
+      */
+    public at(index: number) {
+        return this.get(wrapIndex(index, this.numRows));
+    }
+
     /**
      * Set a row by position.
-     * @param index The index of the element to write.
+     * @param index The index of the row to write.
      * @param value The value to set.
      */
     public set(index: number, value: Struct<T>['TValue']) {
@@ -175,7 +184,7 @@ export class RecordBatch<T extends TypeMap = any> {
     /**
      * Return a zero-copy sub-section of this RecordBatch.
      * @param start The beginning of the specified portion of the RecordBatch.
-     * @param end The end of the specified portion of the RecordBatch. This is exclusive of the element at the index 'end'.
+     * @param end The end of the specified portion of the RecordBatch. This is exclusive of the row at the index 'end'.
      */
     public slice(begin?: number, end?: number): RecordBatch<T> {
         const [slice] = new Vector([this.data]).slice(begin, end).data;

js/src/table.ts

@@ -40,7 +40,7 @@ import { instance as indexOfVisitor } from './visitor/indexof.js';
 import { instance as iteratorVisitor } from './visitor/iterator.js';
 
 import { DataProps } from './data.js';
-import { clampRange } from './util/vector.js';
+import { clampRange, wrapIndex } from './util/vector.js';
 import { ArrayDataType, BigIntArray, TypedArray, TypedArrayDataType } from './interfaces.js';
 import { RecordBatch, _InternalEmptyPlaceholderRecordBatch } from './recordbatch.js';
 
@@ -196,6 +196,15 @@ export class Table<T extends TypeMap = any> {
     // @ts-ignore
     public get(index: number): Struct<T>['TValue'] | null { return null; }
 
+    /**
+      * Get an element value by position.
+      * @param index The index of the element to read. A negative index will count back from the last element.
+      */
+    // @ts-ignore
+    public at(index: number): Struct<T>['TValue'] | null {
+        return this.get(wrapIndex(index, this.numRows));
+    }
+
     /**
      * Set an element value by position.
      *

js/src/util/vector.ts

@@ -23,19 +23,8 @@ import { compareArrayLike } from '../util/buffer.js';
 /** @ignore */
 type RangeLike = { length: number; stride?: number };
 /** @ignore */
-type ClampThen<T extends RangeLike> = (source: T, index: number) => any;
-/** @ignore */
 type ClampRangeThen<T extends RangeLike> = (source: T, offset: number, length: number) => any;
 
-export function clampIndex<T extends RangeLike>(source: T, index: number): number;
-export function clampIndex<T extends RangeLike, N extends ClampThen<T> = ClampThen<T>>(source: T, index: number, then: N): ReturnType<N>;
-/** @ignore */
-export function clampIndex<T extends RangeLike, N extends ClampThen<T> = ClampThen<T>>(source: T, index: number, then?: N) {
-    const length = source.length;
-    const adjust = index > -1 ? index : (length + (index % length));
-    return then ? then(source, adjust) : adjust;
-}
-
 /** @ignore */
 let tmp: number;
 export function clampRange<T extends RangeLike>(source: T, begin: number | undefined, end: number | undefined): [number, number];
@@ -60,6 +49,9 @@ export function clampRange<T extends RangeLike, N extends ClampRangeThen<T> = Cl
     return then ? then(source, lhs, rhs) : [lhs, rhs];
 }
 
+/** @ignore */
+export const wrapIndex = (index: number, len: number) => index < 0 ? (len + index) : index;
+
 const isNaNFast = (value: any) => value !== value;
 
 /** @ignore */

js/src/vector.ts

@@ -16,7 +16,7 @@
 // under the License.
 
 import { Type } from './enum.js';
-import { clampRange } from './util/vector.js';
+import { clampRange, wrapIndex } from './util/vector.js';
 import { DataType, strideForType } from './type.js';
 import { Data, makeData, DataProps } from './data.js';
 import { BigIntArray, TypedArray, TypedArrayDataType } from './interfaces.js';
@@ -177,6 +177,14 @@ export class Vector<T extends DataType = any> {
     // @ts-ignore
     public get(index: number): T['TValue'] | null { return null; }
 
+    /**
+     * Get an element value by position.
+     * @param index The index of the element to read. A negative index will count back from the last element.
+     */
+    public at(index: number): T['TValue'] | null {
+        return this.get(wrapIndex(index, this.length));
+    }
+
     /**
      * Set an element value by position.
      * @param index The index of the element to write.

js/test/unit/vector/bool-vector-tests.ts

@@ -25,9 +25,10 @@ describe(`BoolVector`, () => {
     const n = values.length;
     const vector = newBoolVector(n, new Uint8Array([27, 0, 0, 0, 0, 0, 0, 0]));
     test(`gets expected values`, () => {
-        let i = -1;
-        while (++i < n) {
+        for (let i = 0; i < values.length; i++) {
             expect(vector.get(i)).toEqual(values[i]);
+            expect(vector.at(i)).toEqual(values.at(i));
+            expect(vector.at(-i)).toEqual(values.at(-i));
         }
     });
     test(`iterates expected values`, () => {
@@ -53,7 +54,7 @@ describe(`BoolVector`, () => {
         const expected2 = [true, true, true, true, true, false, false, false];
         const expected3 = [true, true, false, false, false, false, true, true];
         function validate(expected: boolean[]) {
-            for (let i = -1; ++i < n;) {
+            for (let i = 0; i < n; i++) {
                 expect(v.get(i)).toEqual(expected[i]);
             }
         }

js/test/unit/vector/numeric-vector-tests.ts

@@ -337,10 +337,12 @@ function testAndValidateVector<T extends Int | Float>(vector: Vector<T>, typed:
 function gets_expected_values<T extends Int | Float>(vector: Vector<T>, typed: T['TArray'], values: any[] = [...typed]) {
     test(`gets expected values`, () => {
         expect.hasAssertions();
-        let i = -1, n = vector.length;
+        let i = -1;
         try {
-            while (++i < n) {
+            while (++i < vector.length) {
                 expect(vector.get(i)).toEqual(values[i]);
+                expect(vector.at(i)).toEqual(values.at(i));
+                expect(vector.at(-i)).toEqual(values.at(-i));
             }
         } catch (e) { throw new Error(`${i}: ${e}`); }
     });

js/test/unit/vector/vector-tests.ts

@@ -227,8 +227,10 @@ describe(`ListVector`, () => {
     });
 
     test(`get value`, () => {
-        for (const [i, value] of values.entries()) {
-            expect(vector.get(i)!.toJSON()).toEqual(value);
+        for (let i = 0; i < values.length; i++) {
+            expect(vector.get(i)!.toJSON()).toEqual(values[i]);
+            expect(vector.at(i)!.toJSON()).toEqual(values.at(i));
+            expect(vector.at(-i)!.toJSON()).toEqual(values.at(-i));
         }
     });
 });
@@ -270,9 +272,10 @@ function basicVectorTests(vector: Vector, values: any[], extras: any[]) {
     const n = values.length;
 
     test(`gets expected values`, () => {
-        let i = -1;
-        while (++i < n) {
+        for (let i = 0; i < values.length; i++) {
             expect(vector.get(i)).toEqual(values[i]);
+            expect(vector.at(i)).toEqual(values.at(i));
+            expect(vector.at(-i)).toEqual(values.at(-i));
         }
     });
     test(`iterates expected values`, () => {