docs: update README to desired API

Author: kgryte

lib/node_modules/@stdlib/ndarray/fill-slice/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # fillSlice
 
-> Fill an input [`ndarray`][@stdlib/ndarray/ctor] with a specified value in the region defined by a [`MultiSlice`][@stdlib/slice/multi].
+> Fill an input [`ndarray`][@stdlib/ndarray/ctor] slice with a specified value.
 
 <section class="intro">
 
@@ -36,9 +36,9 @@ limitations under the License.
 var fillSlice = require( '@stdlib/ndarray/fill-slice' );
 ```
 
-#### fillSlice( x, s, value )
+#### fillSlice( x, value, ...s\[, options] )
 
-Fills an input [`ndarray`][@stdlib/ndarray/ctor] with a specified value in the region defined by a [`MultiSlice`][@stdlib/slice/multi].
+Fills an input [`ndarray`][@stdlib/ndarray/ctor] slice with a specified value.
 
 ```javascript
 var zeros = require( '@stdlib/ndarray/zeros' );
@@ -50,27 +50,111 @@ var x = zeros( [ 3, 4 ], {
     'dtype': 'float64'
 });
 
-// Create a MultiSlice to specify the fill region:
+// Define the fill region:
 var s0 = new Slice( 1, 3 );
 var s1 = new Slice( 2, 4 );
 var s = new MultiSlice( s0, s1 );
 
-// Fill the ndarray with a scalar value:
-var y = fillSlice( x, s, 5.0 );
+// Fill the region with a scalar value:
+var y = fillSlice( x, 5.0, s );
 // returns <ndarray>
 
 var bool = ( y === x );
 // returns true
 
 var arr = ndarray2array( x );
-// returns [ [ 0, 0, 0, 0 ], [ 0, 0, 5, 5 ], [ 0, 0, 5, 5 ] ]
+
+// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 5.0, 5.0 ], [ 0.0, 0.0, 5.0, 5.0 ] ]
 ```
 
 The function accepts the following arguments:
 
 -   **x**: array-like object containing an input [`ndarray`][@stdlib/ndarray/ctor].
--   **s**: [`MultiSlice`][@stdlib/slice/multi] specifying the fill region of the input [`ndarray`][@stdlib/ndarray/ctor].
 -   **value**: scalar value.
+-   **s**: [`MultiSlice`][@stdlib/slice/multi] instance, an array of slice arguments, or slice arguments as separate arguments.
+-   **options**: function options.
+
+The function supports three (mutually exclusive) means for providing slice arguments:
+
+1.  providing a single [`MultiSlice`][@stdlib/slice/multi] instance.
+2.  providing a single array of slice arguments.
+3.  providing slice arguments as separate arguments.
+
+The following example demonstrates each invocation style achieving equivalent results.
+
+```javascript
+var zeros = require( '@stdlib/ndarray/zeros' );
+var MultiSlice = require( '@stdlib/slice/multi' );
+var Slice = require( '@stdlib/slice/ctor' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+var opts = {
+    'dtype': 'float64'
+};
+
+// 1. Using a MultiSlice:
+var x = zeros( [ 3, 4 ], opts );
+
+var s0 = new Slice( 1, 3 );
+var s1 = new Slice( 2, 4 );
+var s = new MultiSlice( s0, s1 );
+
+var out = fillSlice( x, 5.0, s );
+// returns <ndarray>
+
+var arr = ndarray2array( out );
+// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 5.0, 5.0 ], [ 0.0, 0.0, 5.0, 5.0 ] ]
+
+// 2. Using an array of slice arguments:
+x = zeros( [ 3, 4 ], opts );
+
+out = fillSlice( x, 5.0, [ s0, s1 ] );
+// returns <ndarray>
+
+arr = ndarray2array( out );
+// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 5.0, 5.0 ], [ 0.0, 0.0, 5.0, 5.0 ] ]
+
+// 3. Providing separate arguments:
+x = zeros( [ 3, 4 ], opts );
+
+out = fillSlice( x, 5.0, s0, s1 );
+// returns <ndarray>
+
+arr = ndarray2array( out );
+// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 5.0, 5.0 ], [ 0.0, 0.0, 5.0, 5.0 ] ]
+```
+
+The function supports the following options:
+
+-   **strict**: boolean indicating whether to enforce strict bounds checking.
+
+By default, the function throws an error when provided a slice which exceeds array bounds. To ignore slice indices exceeding array bounds, set the `strict` option to `false`.
+
+```javascript
+var zeros = require( '@stdlib/ndarray/zeros' );
+var MultiSlice = require( '@stdlib/slice/multi' );
+var Slice = require( '@stdlib/slice/ctor' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+var x = zeros( [ 3, 4 ], {
+    'dtype': 'float64'
+});
+
+// Define the fill region:
+var s0 = new Slice( 1, null, 1 );
+var s1 = new Slice( 10, 20, 1 );
+var s = new MultiSlice( s0, s1 );
+
+// Fill the region with a scalar value:
+var y = fillSlice( x, 5.0, s, {
+    'strict': false
+});
+// returns <ndarray>
+
+var arr = ndarray2array( x );
+
+// returns [ [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0, 0.0 ] ]
+```
 
 </section>
 
@@ -81,10 +165,9 @@ The function accepts the following arguments:
 ## Notes
 
 -   An input [`ndarray`][@stdlib/ndarray/ctor] **must** be writable. If provided a **read-only** [`ndarray`][@stdlib/ndarray/ctor], the function throws an error.
--   If `value` is a number and `x` has a complex [data type][@stdlib/ndarray/dtypes], the function fills an input [`ndarray`][@stdlib/ndarray/ctor] with a complex number whose real component equals the provided scalar `value` and whose imaginary component is zero.
--   A `value` must be able to safely cast to the input [`ndarray`][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes]. Scalar values having floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., a scalar double-precision floating-point number can be used to fill a `'float32'` input [`ndarray`][@stdlib/ndarray/ctor]).
+-   If an input `value` is a number and `x` has a complex [data type][@stdlib/ndarray/dtypes], the function fills an input [`ndarray`][@stdlib/ndarray/ctor] with a complex number whose real component equals the provided scalar `value` and whose imaginary component is zero.
+-   An input `value` must be able to safely cast to the input [`ndarray`][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes]. Scalar values having floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., a scalar double-precision floating-point number can be used to fill a `'float32'` input [`ndarray`][@stdlib/ndarray/ctor]).
 -   The function **mutates** the input [`ndarray`][@stdlib/ndarray/ctor].
--   Multi-slice instances have no explicit functionality; however, they are used by [`ndarray`][@stdlib/ndarray/ctor] and other packages for creating views into multi-dimensional data structures.
 
 </section>
 
@@ -109,14 +192,14 @@ var x = zeros( [ 2, 3, 4 ], {
 });
 console.log( ndarray2array( x ) );
 
-// Create a MultiSlice to specify the fill region:
+// Define a fill region:
 var s0 = new Slice( 1, 2 );
 var s1 = new Slice( null, null );
 var s2 = new Slice( 2, 4 );
 var s = new MultiSlice( s0, s1, s2 );
 
-// Fill the ndarray with a scalar value:
-fillSlice( x, s, 10.0 );
+// Fill the region with a scalar value:
+fillSlice( x, 10.0, s );
 console.log( ndarray2array( x ) );
 ```