Skip to content

README.md

Latest commit

 

History

History
180 lines (116 loc) · 5.81 KB

README.md

File metadata and controls

180 lines (116 loc) · 5.81 KB

gmskrev

Reverse a strided array in-place according to a mask.

Usage

var gmskrev = require( '@stdlib/blas/ext/base/gmskrev' );

gmskrev( N, x, strideX, mask, strideMask )

Reverses a strided array in-place according to a mask.

var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ];
var mask = [ 0, 0, 0, 1, 0, 0, 0, 0 ];

gmskrev( x.length, x, 1, mask, 1 );
// x => [ -3.0, -1.0, 0.0, -5.0, 4.0, 3.0, 1.0, -2.0 ]

The function has the following parameters:

  • N: number of indexed elements.
  • x: input array.
  • strideX: stride length for x.
  • mask: mask array.
  • strideMask: stride length for mask.

The N and stride parameters determine which elements in the strided arrays are accessed at runtime. For example, to reverse every other element:

var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ];
var mask = [ 0, 0, 0, 0 ];

gmskrev( 4, x, 2, mask, 1 );
// x => [ -1.0, 1.0, 4.0, -5.0, 3.0, 0.0, -2.0, -3.0 ]

Note that indexing is relative to the first index. To introduce an offset, use typed array views.

var Float64Array = require( '@stdlib/array/float64' );
var Uint8Array = require( '@stdlib/array/uint8' );

// Initial arrays...
var x0 = new Float64Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] );
var m0 = new Uint8Array( [ 0, 0, 0, 0, 0, 0 ] );

// Create offset views...
var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
var m1 = new Uint8Array( m0.buffer, m0.BYTES_PER_ELEMENT*1 );

// Reverse every other element...
gmskrev( 3, x1, 2, m1, 1 );
// x0 => <Float64Array>[ 1.0, -6.0, 3.0, -4.0, 5.0, -2.0 ]

gmskrev.ndarray( N, x, strideX, offsetX, mask, strideMask, offsetMask )

Reverses a strided array in-place according to a mask and using alternative indexing semantics.

var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ];
var mask = [ 0, 0, 0, 1, 0, 0, 0, 0 ];

gmskrev.ndarray( x.length, x, 1, 0, mask, 1, 0 );
// x => [ -3.0, -1.0, 0.0, -5.0, 4.0, 3.0, 1.0, -2.0 ]

The function has the following additional parameters:

  • offsetX: starting index for x.
  • offsetMask: starting index for mask.

While typed array views mandate a view offset based on the underlying buffer, the offset parameters support indexing semantics based on starting indices. For example, to access only the last three elements:

var x = [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ];
var mask = [ 0, 0, 0, 0, 0, 0 ];

gmskrev.ndarray( 3, x, 1, x.length-3, mask, 1, 3 );
// x => [ 1.0, -2.0, 3.0, -6.0, 5.0, -4.0 ]

Notes

  • If N <= 0, both functions return x unchanged.
  • Both functions support array-like objects having getter and setter accessors for array element access (e.g., @stdlib/array/complex64).
  • A mask value of 0 indicates that the corresponding element in x participates in the reversal, while a non-zero mask value indicates that the corresponding element should be skipped.
  • Where possible, one should "reverse" a strided array by negating its stride, which is an O(1) operation, in contrast to performing an in-place reversal, which is O(N). However, in certain circumstances, this is not tenable, particularly when interfacing with libraries which assume and/or expect a specific memory layout (e.g., strided array elements arranged in memory in ascending order). In general, when working with strided arrays, only perform an in-place reversal when strictly necessary.
  • Depending on the environment, the typed versions (dmskrev, smskrev, etc.) are likely to be significantly more performant.

Examples

var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var Uint8Array = require( '@stdlib/array/uint8' );
var gmskrev = require( '@stdlib/blas/ext/base/gmskrev' );

var x = discreteUniform( 10, -100, 100, {
    'dtype': 'generic'
});
console.log( x );

var mask = new Uint8Array( [ 0, 0, 0, 1, 0, 0, 1, 0, 0, 0 ] );
console.log( mask );

gmskrev( x.length, x, 1, mask, 1 );
console.log( x );