Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify types of array/slice and array/base/slice via use of generic type parameter #1318

Merged
merged 5 commits into from
Feb 21, 2024
Merged

Simplify types of array/slice and array/base/slice via use of generic type parameter #1318

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3c06d16
refactor: simplify via use of generic type parameter
Planeshifter Feb 17, 2024
7ab004b
refactor: revert back to original signature for generic collections
Planeshifter Feb 19, 2024
e572eb0
docs: fix examples
Planeshifter Feb 21, 2024
0067d03
Apply suggestions from code review
kgryte Feb 21, 2024
e1d0be8
Apply suggestions from code review
kgryte Feb 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 4 additions & 192 deletions lib/node_modules/@stdlib/array/base/slice/docs/types/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@

/// <reference types="@stdlib/types"/>

import { Collection, Complex128Array, Complex64Array } from '@stdlib/types/array';
import { Collection, ComplexTypedArray } from '@stdlib/types/array';

/**
* Returns a shallow copy of a portion of an array.
Expand All @@ -37,204 +37,16 @@ import { Collection, Complex128Array, Complex64Array } from '@stdlib/types/array
*
* var out = slice( x, 0, 3 );
* // returns <Float64Array>[ 1.0, 2.0, 3.0 ]
*/
declare function slice( x: Float64Array, start: number, end: number ): Float64Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Float32Array = require( '@stdlib/array/float32' );
*
* var x = new Float32Array( [ 1.0, 2.0, 3.0 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Float32Array>[ 1.0, 2.0, 3.0 ]
*/
declare function slice( x: Float32Array, start: number, end: number ): Float32Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Int32Array = require( '@stdlib/array/int32' );
*
* var x = new Int32Array( [ 1, 2, 3 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Int32Array>[ 1, 2, 3 ]
*/
declare function slice( x: Int32Array, start: number, end: number ): Int32Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Int16Array = require( '@stdlib/array/int16' );
*
* var x = new Int16Array( [ 1, 2, 3 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Int16Array>[ 1, 2, 3 ]
*/
declare function slice( x: Int16Array, start: number, end: number ): Int16Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Int8Array = require( '@stdlib/array/int8' );
*
* var x = new Int8Array( [ 1, 2, 3 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Int8Array>[ 1, 2, 3 ]
*/
declare function slice( x: Int8Array, start: number, end: number ): Int8Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Uint32Array = require( '@stdlib/array/uint32' );
*
* var x = new Uint32Array( [ 1, 2, 3 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Uint32Array>[ 1, 2, 3 ]
*/
declare function slice( x: Uint32Array, start: number, end: number ): Uint32Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Uint16Array = require( '@stdlib/array/uint16' );
*
* var x = new Uint16Array( [ 1, 2, 3 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Uint16Array>[ 1, 2, 3 ]
*/
declare function slice( x: Uint16Array, start: number, end: number ): Uint16Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Uint8Array = require( '@stdlib/array/uint8' );
*
* var x = new Uint8Array( [ 1, 2, 3 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Uint8Array>[ 1, 2, 3 ]
*/
declare function slice( x: Uint8Array, start: number, end: number ): Uint8Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Uint8ClampedArray = require( '@stdlib/array/uint8c' );
*
* var x = new Uint8ClampedArray( [ 1, 2, 3 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Uint8ClampedArray>[ 1, 2, 3 ]
*/
declare function slice( x: Uint8ClampedArray, start: number, end: number ): Uint8ClampedArray;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Complex128Array = require( '@stdlib/array/complex128' );
*
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Complex128Array>[ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]
*/
declare function slice( x: Complex128Array, start: number, end: number ): Complex128Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var Complex64Array = require( '@stdlib/array/complex64' );
kgryte marked this conversation as resolved.
Show resolved Hide resolved
*
* var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
*
* var out = slice( x, 0, 3 );
* // returns <Complex64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]
*/
declare function slice( x: Complex64Array, start: number, end: number ): Complex64Array;

/**
* Returns a shallow copy of a portion of an array.
*
* @param x - input array
* @param start - starting index (inclusive)
* @param end - ending index (exclusive)
* @returns output array
*
* @example
* var x = [ 1, 2, 3, 4, 5, 6 ];
* var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0 ] );
*
* var out = slice( x, 0, 3 );
* // returns [ 1, 2, 3 ]
* // returns <Complex64Array>[ 1.0, 2.0, 3.0 ]
Planeshifter marked this conversation as resolved.
Show resolved Hide resolved
*/
declare function slice<T = unknown>( x: Collection<T>, start: number, end: number ): Array<T>;
declare function slice<T extends Collection | ComplexTypedArray>( x: T, start: number, end: number ): T;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we lost some info here. Namely, if T is a collection without a slice method, we always return a "generic" array having elements of the same type. The prior definition was a fall back definition for "unknown" collections and "generic" arrays. We can probably do better by defining an interface which extends Collection and has a slice method conforming to a particular signature. In that case, T in and T out. Otherwise, for a collection without a slice method, we return a "generic" array having elements of type U.

Copy link
Member Author

@Planeshifter Planeshifter Feb 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kgryte I reverted back to the prior definitions for a generic collection. We also have to do this as my proposed type broke down for tuples (say [1,2,3] as const), which would incorrectly be set as the return type irrespective of what was sliced off.

But we do have another issue that was present before, namely that the definition doesn't work for strings, as it incorrectly asserts that the return value will be an array of strings in this case, though it is just a string. Should we handle this, even though the package is in the array namespace?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my mind, that the function does not apply to strings is fine with me and part of the original reason why I typed it as Collection, rather than ArrayLike. For users wanting to slice strings, they'd be better off using a dedicated @stdlib/string/slice package.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kgryte Makes sense, although I believe strings do fall under our Collections as well, right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, no.

See

stdlib/tools/docs/jsdoc/typedefs/objects.js

Line 54 in 4315e33

* A collection, which is defined as either an array, typed array, or an array-like object (excluding strings and functions).
and

stdlib/lib/node_modules/@stdlib/assert/is-collection/lib/main.js

Line 45 in 4315e33

typeof value === 'object' &&
.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strings do fall under the TypeScript definition (

stdlib/lib/node_modules/@stdlib/types/index.d.ts

Line 595 in 4315e33

type Collection<T = any> = Array<T> | TypedArray | ArrayLike<T>; // eslint-disable-line @typescript-eslint/no-explicit-any
); but this was because we, I believe, could not easily type an "array-like object".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Things may have changed, but IIRC it may have been influenced by TypeScript 2.1 capabilities.



// EXPORTS //
Expand Down
Loading
Loading