Skip to content

docs: improve doctests for complex number typed arrays in blas/ext/base/zfill #11977

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

Merged
kgryte merged 1 commit into from
May 7, 2026
Merged

docs: improve doctests for complex number typed arrays in blas/ext/base/zfill #11977

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
54 changes: 10 additions & 44 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,19 +35,15 @@ var zfill = require( '@stdlib/blas/ext/base/zfill' );
Fills a double-precision complex floating-point strided array `x` with a specified scalar constant `alpha`.

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var Complex128Array = require( '@stdlib/array/complex128' );
var Complex128 = require( '@stdlib/complex/float64/ctor' );

var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
var x = new Complex128Array( arr );
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );

var alpha = new Complex128( 10.0, 10.0 );

zfill( x.length, alpha, x, 1 );

var y = x.get( 0 );
// returns <Complex128>[ 10.0, 10.0 ]
// x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
```

The function has the following parameters:
Expand All @@ -60,36 +56,25 @@ The function has the following parameters:
The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to fill every other element

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var Complex128Array = require( '@stdlib/array/complex128' );
var Complex128 = require( '@stdlib/complex/float64/ctor' );

var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
var x = new Complex128Array( arr );
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );

var alpha = new Complex128( 10.0, 10.0 );

zfill( 2, alpha, x, 2 );

var y = x.get( 0 );
// returns <Complex128>[ 10.0, 10.0 ]

y = x.get( 1 );
// returns <Complex128>[ 3.0, 4.0 ]
// x => <Complex128Array>[ 10.0, 10.0, 3.0, 4.0, 10.0, 10.0, 7.0, 8.0 ]
```

Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var Complex128Array = require( '@stdlib/array/complex128' );
var Complex128 = require( '@stdlib/complex/float64/ctor' );

// Create the underlying floating-point array:
var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );

// Initial array:
var x0 = new Complex128Array( arr );
var x0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );

// Create an offset view:
var x1 = new Complex128Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
Expand All @@ -99,32 +84,23 @@ var alpha = new Complex128( 10.0, 10.0 );

// Fill every other element:
zfill( 2, alpha, x1, 2 );

var y = x0.get( 0 );
// returns <Complex128>[ 1.0, 2.0 ]

y = x0.get( 1 );
// returns <Complex128>[ 10.0, 10.0 ]
// x0 => <Complex128Array>[ 1.0, 2.0, 10.0, 10.0, 5.0, 6.0, 10.0, 10.0 ]
```

#### zfill.ndarray( N, alpha, x, strideX, offsetX )

Fills a double-precision complex floating-point strided array `x` with a specified scalar constant `alpha` using alternative indexing semantics.

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var Complex128Array = require( '@stdlib/array/complex128' );
var Complex128 = require( '@stdlib/complex/float64/ctor' );

var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
var x = new Complex128Array( arr );
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );

var alpha = new Complex128( 10.0, 10.0 );

zfill.ndarray( x.length, alpha, x, 1, 0 );

var y = x.get( 0 );
// returns <Complex128>[ 10.0, 10.0 ]
// x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
```

The function has the following additional parameters:
Expand All @@ -134,25 +110,15 @@ The function has the following additional parameters:
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to access only the last two elements of the strided array

```javascript
var Float64Array = require( '@stdlib/array/float64' );
var Complex128Array = require( '@stdlib/array/complex128' );
var Complex128 = require( '@stdlib/complex/float64/ctor' );

var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
var x = new Complex128Array( arr );
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );

var alpha = new Complex128( 10.0, 10.0 );

zfill.ndarray( 2, alpha, x, 1, x.length-2 );

var y = x.get( 0 );
// returns <Complex128>[ 1.0, 2.0 ]

y = x.get( 1 );
// returns <Complex128>[ 10.0, 10.0 ]

y = x.get( 2 );
// returns <Complex128>[ 10.0, 10.0 ]
// x => <Complex128Array>[ 1.0, 2.0, 10.0, 10.0, 10.0, 10.0 ]
```

</section>
Expand Down
33 changes: 12 additions & 21 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/docs/repl.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,28 +35,23 @@
// Standard Usage:
> var x = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0 ] );
> var alpha = new {{alias:@stdlib/complex/float64/ctor}}( 5.0, -5.0 );
> {{alias}}( x.length, alpha, x, 1 );
> var z = x.get( 0 )
<Complex128>[ 5.0, -5.0 ]
> {{alias}}( x.length, alpha, x, 1 )
<Complex128Array>[ 5.0, -5.0, 5.0, -5.0 ]

// Using `N` and stride parameters:
> x = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
> alpha = new {{alias:@stdlib/complex/float64/ctor}}( 5.0, -5.0 );
> {{alias}}( 2, alpha, x, 2 );
> z = x.get( 0 )
<Complex128>[ 5.0, -5.0 ]
> z = x.get( 2 )
<Complex128>[ 5.0, -5.0 ]
> {{alias}}( 2, alpha, x, 2 )
<Complex128Array>[ 5.0, -5.0, 3.0, 4.0, 5.0, -5.0 ]

// Using view offsets:
> var x0 = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
> var x1 = new {{alias:@stdlib/array/complex128}}( x0.buffer, x0.BYTES_PER_ELEMENT*1 );
> alpha = new {{alias:@stdlib/complex/float64/ctor}}( 5.0, -5.0 );
> {{alias}}( 2, alpha, x1, 1 );
> z = x0.get( 0 )
<Complex128>[ 1.0, 2.0 ]
> z = x0.get( 1 )
<Complex128>[ 5.0, -5.0 ]
> {{alias}}( 2, alpha, x1, 1 )
<Complex128Array>[ 5.0, -5.0, 5.0, -5.0 ]
> x0
<Complex128Array>[ 1.0, 2.0, 5.0, -5.0, 5.0, -5.0 ]


{{alias}}.ndarray( N, alpha, x, strideX, offsetX )
Expand Down Expand Up @@ -94,18 +89,14 @@
// Standard Usage:
> var x = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0 ] );
> var alpha = new {{alias:@stdlib/complex/float64/ctor}}( 2.0, 2.0 );
> {{alias}}.ndarray( x.length, alpha, x, 1, 0 );
> var z = x.get( 0 )
<Complex128>[ 2.0, 2.0 ]
> {{alias}}.ndarray( x.length, alpha, x, 1, 0 )
<Complex128Array>[ 2.0, 2.0, 2.0, 2.0 ]

// Using an index offset:
> x = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
> alpha = new {{alias:@stdlib/complex/float64/ctor}}( 5.0, -5.0 );
> {{alias}}.ndarray( 2, alpha, x, 2, 1 );
> z = x.get( 0 )
<Complex128>[ 1.0, 2.0 ]
> z = x.get( 1 )
<Complex128>[ 5.0, -5.0 ]
> {{alias}}.ndarray( 2, alpha, x, 2, 1 )
<Complex128Array>[ 1.0, 2.0, 5.0, -5.0, 5.0, 6.0, 5.0, -5.0 ]

See Also
--------
26 changes: 7 additions & 19 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/docs/types/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,19 +37,15 @@ interface Routine {
* @returns input array
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1 );
*
* var y = x.get( 0 );
* // returns <Complex128>[ 10.0, 10.0 ]
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/
( N: number, alpha: Complex128, x: Complex128Array, strideX: number ): Complex128Array;

Expand All @@ -64,19 +60,15 @@ interface Routine {
* @returns input array
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1, 0 );
*
* var y = x.get( 0 );
* // returns <Complex128>[ 10.0, 10.0 ]
* zfill.ndarray( x.length, alpha, x, 1, 0 );
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/
ndarray( N: number, alpha: Complex128, x: Complex128Array, strideX: number, offsetX: number ): Complex128Array;
}
Expand All @@ -91,19 +83,15 @@ interface Routine {
* @returns input array
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1 );
*
* var y = x.get( 0 );
* // returns <Complex128>[ 10.0, 10.0 ]
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/
declare var zfill: Routine;

Expand Down
8 changes: 2 additions & 6 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/lib/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,20 +24,16 @@
* @module @stdlib/blas/ext/base/zfill
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
* var zfill = require( '@stdlib/blas/ext/base/zfill' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1 );
*
* var y = x.get( 0 );
* // returns <Complex128>[ 10.0, 10.0 ]
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/

// MODULES //
Expand Down
16 changes: 2 additions & 14 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/lib/ndarray.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,27 +43,15 @@ var M = 8;
* @returns {Complex128Array} input array
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
* var real = require( '@stdlib/complex/float64/real' );
* var imag = require( '@stdlib/complex/float64/imag' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1, 0 );
*
* var y = x.get( 0 );
* // returns <Complex128>
*
* var re = real( y );
* // returns 10.0
*
* var im = imag( y );
* // returns 10.0
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/
function zfill( N, alpha, x, strideX, offsetX ) {
var view;
Expand Down
8 changes: 2 additions & 6 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/lib/ndarray.native.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,19 +37,15 @@ var addon = require( './../src/addon.node' );
* @returns {Complex128Array} input array
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1, 0 );
*
* var y = x.get( 0 );
* // returns <Complex128>[ 10.0, 10.0 ]
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/
function zfill( N, alpha, x, strideX, offsetX ) {
var view = reinterpret( x, 0 );
Expand Down
8 changes: 2 additions & 6 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/lib/zfill.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,19 +36,15 @@ var ndarray = require( './ndarray.js' );
* @returns {Complex128Array} input array
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1 );
*
* var y = x.get( 0 );
* // returns <Complex128>[ 10.0, 10.0 ]
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/
function zfill( N, alpha, x, strideX ) {
return ndarray( N, alpha, x, strideX, stride2offset( N, strideX ) );
Expand Down
8 changes: 2 additions & 6 deletions lib/node_modules/@stdlib/blas/ext/base/zfill/lib/zfill.native.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,19 +36,15 @@ var addon = require( './../src/addon.node' );
* @returns {Complex128Array} input array
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var Complex128Array = require( '@stdlib/array/complex128' );
* var Complex128 = require( '@stdlib/complex/float64/ctor' );
*
* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex128Array( arr );
* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
*
* var alpha = new Complex128( 10.0, 10.0 );
*
* zfill( x.length, alpha, x, 1 );
*
* var y = x.get( 0 );
* // returns <Complex128>[ 10.0, 10.0 ]
* // x => <Complex128Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
*/
function zfill( N, alpha, x, strideX ) {
var view = reinterpret( x, 0 );
Expand Down