docs: update examples and documentation

Author: kgryte

lib/node_modules/@stdlib/ndarray/map/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # map
 
-> Apply a callback function to elements in an input ndarray and assign results to elements in an output ndarray.
+> Apply a callback function to elements in an input [ndarray][@stdlib/ndarray/ctor] and assign results to elements in a new output [ndarray][@stdlib/ndarray/ctor].
 
 <section class="intro">
 
@@ -36,56 +36,87 @@ limitations under the License.
 var map = require( '@stdlib/ndarray/map' );
 ```
 
-#### map( x, \[options, ]fcn\[, thisArg] )
+#### map( x\[, options], fcn\[, thisArg] )
 
-Applies a callback function to elements in an input ndarray and assigns results to elements in an output ndarray.
+Applies a callback function to elements in an input [ndarray][@stdlib/ndarray/ctor] and assigns results to elements in a new output [ndarray][@stdlib/ndarray/ctor].
+
+<!-- eslint-disable max-len -->
 
 ```javascript
 var Float64Array = require( '@stdlib/array/float64' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 
-function scale( x ) {
-    return x * 10.0;
+function scale( z ) {
+    return z * 10.0;
 }
 
-// Create the input data buffer:
-var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
-
-// Define the shape of the input ndarray:
-var shape = [ 3, 2 ];
-
-// Define the array strides:
-var strides = [ 2, 1 ];
-
-// Define the index offset:
-var offset = 0;
+var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+var shape = [ 2, 3 ];
+var strides = [ 6, 1 ];
+var offset = 1;
 
-// Create the input ndarray:
 var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
+// returns <ndarray>
 
-// Apply the map function:
 var y = map( x, scale );
+// returns <ndarray>
 
-console.log( y.data );
-// => <Float64Array>[ 10.0, 20.0, 30.0, 40.0, 50.0, 60.0 ]
+var arr = ndarray2array( y );
+// returns [ [ 20.0, 30.0, 40.0 ], [ 80.0, 90.0, 100.0 ] ]
 ```
 
 The function accepts the following arguments:
 
--   **x**: input ndarray.
+-   **x**: input [ndarray][@stdlib/ndarray/ctor].
 -   **options**: function options.
 -   **fcn**: callback to apply.
 -   **thisArg**: callback execution context.
 
 The function accepts the following options:
 
--   **dtype**: output ndarray data type. Defaults to match the input ndarray if not specified.
+-   **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. If not specified, the output ndarray [data type][@stdlib/ndarray/dtypes] is inferred from the input [ndarray][@stdlib/ndarray/ctor].
+
+By default, the output ndarray [data type][@stdlib/ndarray/dtypes] is inferred from the input [ndarray][@stdlib/ndarray/ctor]. To return an ndarray with a different [data type][@stdlib/ndarray/dtypes], specify the `dtype` option.
+
+<!-- eslint-disable max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var ndarray = require( '@stdlib/ndarray/ctor' );
+var dtype = require( '@stdlib/ndarray/dtype' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+function scale( z ) {
+    return z * 10.0;
+}
+
+var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+var shape = [ 2, 3 ];
+var strides = [ 6, 1 ];
+var offset = 1;
+
+var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
+// returns <ndarray>
+
+var opts = {
+    'dtype': 'float32'
+};
+var y = map( x, opts, scale );
+// returns <ndarray>
+
+var dt = dtype( y );
+// returns 'float32'
+
+var arr = ndarray2array( y );
+// returns [ [ 20.0, 30.0, 40.0 ], [ 80.0, 90.0, 100.0 ] ]
+```
 
 The callback function is provided the following arguments:
 
 -   **values**: current array element.
 -   **indices**: current array element indices.
--   **arr**: the input ndarray.
+-   **arr**: the input [ndarray][@stdlib/ndarray/ctor].
 
 </section>
 
@@ -95,6 +126,35 @@ The callback function is provided the following arguments:
 
 ## Notes
 
+-   The function does **not** perform explicit casting (e.g., from a real-valued floating-point number to a complex floating-point number). Any such casting should be performed by a provided callback function.
+
+    <!-- eslint-disable max-len -->
+
+    ```javascript
+    var Float64Array = require( '@stdlib/array/float64' );
+    var ndarray = require( '@stdlib/ndarray/ctor' );
+    var Complex128 = require( '@stdlib/complex/float64/ctor' );
+    var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+    function toComplex( z ) {
+        return new Complex128( z, 0.0 );
+    }
+
+    var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+    var shape = [ 2, 3 ];
+    var strides = [ 6, 1 ];
+    var offset = 1;
+
+    var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
+    // returns <ndarray>
+
+    var opts = {
+        'dtype': 'complex128'
+    };
+    var y = map( x, opts, toComplex );
+    // returns <ndarray>
+    ```
+
 -   For very high-dimensional ndarrays which are non-contiguous, one should consider copying the underlying data to contiguous memory before applying a callback function in order to achieve better performance.
 
 </section>
@@ -110,7 +170,7 @@ The callback function is provided the following arguments:
 ```javascript
 var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var abs = require( '@stdlib/math/base/special/abs' );
-var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var naryFunction = require( '@stdlib/utils/nary-function' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
 var map = require( '@stdlib/ndarray/map' );
@@ -122,10 +182,10 @@ var shape = [ 5, 2 ];
 var strides = [ 2, 1 ];
 var offset = 0;
 var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
+console.log( ndarray2array( x ) );
 
 var y = map( x, naryFunction( abs, 1 ) );
-console.log( ndarray2array( x.data, x.shape, x.strides, x.offset, x.order ) );
-console.log( ndarray2array( y.data, y.shape, y.strides, y.offset, y.order ) );
+console.log( ndarray2array( y ) );
 ```
 
 </section>
@@ -142,6 +202,10 @@ console.log( ndarray2array( y.data, y.shape, y.strides, y.offset, y.order ) );
 
 <section class="links">
 
+[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
+
+[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
+
 <!-- <related-links> -->
 
 <!-- </related-links> -->

lib/node_modules/@stdlib/ndarray/map/docs/types/index.d.ts

@@ -777,7 +777,7 @@ declare function map<T = unknown, V = unknown>( x: typedndarray<T>, options: Flo
 * var Complex128 = require( '@stdlib/complex/float64/ctor' );
 *
 * function toComplex( z ) {
-*     return new Complex128( z, 0 );
+*     return new Complex128( z, 0.0 );
 * }
 *
 * var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
@@ -812,7 +812,7 @@ declare function map<T = unknown, V = unknown>( x: typedndarray<T>, options: Com
 * var Complex64 = require( '@stdlib/complex/float32/ctor' );
 *
 * function toComplex( z ) {
-*     return new Complex64( z, 0 );
+*     return new Complex64( z, 0.0 );
 * }
 *
 * var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );

lib/node_modules/@stdlib/ndarray/map/examples/index.js

@@ -20,7 +20,7 @@
 
 var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var abs = require( '@stdlib/math/base/special/abs' );
-var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var naryFunction = require( '@stdlib/utils/nary-function' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
 var map = require( './../lib' );
@@ -32,7 +32,7 @@ var shape = [ 5, 2 ];
 var strides = [ 2, 1 ];
 var offset = 0;
 var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
-console.log( ndarray2array( x.data, x.shape, x.strides, x.offset, x.order ) );
+console.log( ndarray2array( x ) );
 
 var y = map( x, naryFunction( abs, 1 ) );
-console.log( ndarray2array( y.data, y.shape, y.strides, y.offset, y.order ) );
+console.log( ndarray2array( y ) );