Refactor and rename base array utility to return accessors for each indexed array dtype

Author: kgryte

lib/node_modules/@stdlib/array/base/get/docs/repl.txt

@@ -18,9 +18,9 @@ limitations under the License.
 
 -->
 
-# get
+# getter
 
-> Return an element from an indexed array-like object.
+> Return an accessor function for retrieving an element from an indexed array-like object.
 
 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
 
@@ -37,20 +37,26 @@ limitations under the License.
 ## Usage
 
 ```javascript
-var get = require( '@stdlib/array/base/get' );
+var getter = require( '@stdlib/array/base/getter' );
 ```
 
-#### get( arr, idx )
+#### getter( dtype )
 
-Returns an element from an indexed array-like object.
+Returns an accessor function for retrieving an element from an indexed array-like object.
 
 ```javascript
 var arr = [ 1, 2, 3, 4 ];
 
+var get = getter( 'generic' );
 var v = get( arr, 2 );
 // returns 3
 ```
 
+The returned accessor function accepts the following arguments:
+
+-   **arr**: input array.
+-   **idx**: element index.
+
 </section>
 
 <!-- /.usage -->
@@ -61,7 +67,9 @@ var v = get( arr, 2 );
 
 ## Notes
 
--   The function does **not** perform bounds checking.
+-   If provided an unrecognized [`dtype`][@stdlib/array/dtypes], the function returns a default accessor function for accessing elements from any indexed array-like object; otherwise, the function returns an accessor function which should **only** be provided an array instance corresponding to `dtype` (e.g., if `dtype` is `'float64'`, the returned accessor function should only be provided instances of `Float64Array`).
+-   Accessor functions do **not** verify that provided input arrays are array instances corresponding to `dtype`, as doing so would introduce performance overhead. If array instances corresponding to other data types are provided to an accessor function, JavaScript runtimes will consider the function polymorphic, potentially triggering de-optimization. In order to ensure maximum performance, **always** ensure that an accessor function is monomorphic.
+-   Accessor functions do **not** perform bounds checking.
 -   An _indexed_ array-like object is a data structure in which one retrieves elements via integer indices via bracket `[]` notation (e.g., `Float64Array`, `Int32Array`, `Array`, etc). This is in contrast to an _accessor_ array-like object in which one retrieves elements using `get` and `set` methods (e.g., `Complex64Array` and `Complex128Array`).
 
 </section>
@@ -78,42 +86,43 @@ var v = get( arr, 2 );
 
 ```javascript
 var filled = require( '@stdlib/array/filled' );
-var get = require( '@stdlib/array/base/get' );
+var dtype = require( '@stdlib/array/dtype' );
+var getter = require( '@stdlib/array/base/getter' );
 
 var arr = filled( 1.0, 10, 'float64' );
-var v = get( arr, 2 );
+var v = getter( dtype( arr ) )( arr, 2 );
 // returns 1.0
 
 arr = filled( 2.0, 10, 'float32' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 2.0
 
 arr = filled( 3, 10, 'int32' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 3
 
 arr = filled( 4, 10, 'int16' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 4
 
 arr = filled( 5, 10, 'int8' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 5
 
 arr = filled( 6, 10, 'uint32' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 6
 
 arr = filled( 7, 10, 'uint16' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 7
 
 arr = filled( 8, 10, 'uint8' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 8
 
 arr = filled( 9, 10, 'uint8c' );
-v = get( arr, 2 );
+v = getter( dtype( arr ) )( arr, 2 );
 // returns 9
 ```
 
@@ -141,6 +150,8 @@ v = get( arr, 2 );
 
 <section class="links">
 
+[@stdlib/array/dtypes]: https://github.com/stdlib-js/stdlib
+
 </section>
 
 <!-- /.links -->