README.md - time-to-botec - Benchmark sampling in different programming languages

README.md (107518B)
      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2018 The Stdlib Authors.
      6 
      7 Licensed under the Apache License, Version 2.0 (the "License");
      8 you may not use this file except in compliance with the License.
      9 You may obtain a copy of the License at
     10 
     11    http://www.apache.org/licenses/LICENSE-2.0
     12 
     13 Unless required by applicable law or agreed to in writing, software
     14 distributed under the License is distributed on an "AS IS" BASIS,
     15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     16 See the License for the specific language governing permissions and
     17 limitations under the License.
     18 
     19 -->
     20 
     21 <!-- lint disable maximum-heading-length -->
     22 
     23 # ndarray
     24 
     25 > Multidimensional array constructor.
     26 
     27 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
     28 
     29 <section class="intro">
     30 
     31 </section>
     32 
     33 <!-- /.intro -->
     34 
     35 <!-- Package usage documentation. -->
     36 
     37 <section class="usage">
     38 
     39 ## Usage
     40 
     41 ```javascript
     42 var ndarray = require( '@stdlib/ndarray/ctor' );
     43 ```
     44 
     45 <a name="main"></a>
     46 
     47 #### ndarray( dtype, buffer, shape, strides, offset, order\[, options] )
     48 
     49 Returns an `ndarray` instance.
     50 
     51 ```javascript
     52 // Specify the array configuration:
     53 var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
     54 var shape = [ 2, 2 ];
     55 var order = 'row-major';
     56 var strides = [ 2, 1 ];
     57 var offset = 0;
     58 
     59 // Create a new ndarray:
     60 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
     61 // returns <ndarray>
     62 ```
     63 
     64 The constructor expects the following arguments:
     65 
     66 -   **dtype**: underlying [data type][@stdlib/ndarray/dtypes].
     67 -   **buffer**: data buffer.
     68 -   **shape**: array shape (dimensions).
     69 -   **strides**: array strides which are index offsets specifying how to access along corresponding dimensions.
     70 -   **offset**: index offset specifying the location of the first indexed element in the data buffer.
     71 -   **order**: array order, which is either `row-major` (C-style) or `column-major` (Fortran-style).
     72 
     73 The constructor accepts the following `options`:
     74 
     75 -   **mode**: specifies how to handle indices which exceed array dimensions. Default: `'throw'`.
     76 -   **submode**: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions. If provided fewer modes than dimensions, the constructor recycles modes using modulo arithmetic. Default: `[ options.mode ]`.
     77 
     78 The constructor supports the following `modes`:
     79 
     80 -   **throw**: specifies that an `ndarray` instance should throw an error when an index exceeds array dimensions.
     81 -   **wrap**: specifies that an `ndarray` instance should wrap around an index exceeding array dimensions using modulo arithmetic.
     82 -   **clamp**: specifies that an `ndarray` instance should set an index exceeding array dimensions to either `0` (minimum index) or the maximum index.
     83 
     84 By default, an `ndarray` instance **throws** when provided an index which exceeds array dimensions. To support alternative indexing behavior, set the `mode` option, which will affect all public methods for getting and setting array elements.
     85 
     86 ```javascript
     87 var opts = {
     88     'mode': 'clamp'
     89 };
     90 
     91 // Specify the array configuration:
     92 var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
     93 var shape = [ 2, 2 ];
     94 var order = 'row-major';
     95 var strides = [ 2, 1 ];
     96 var offset = 0;
     97 
     98 // Create a new ndarray:
     99 var arr = ndarray( 'generic', buffer, shape, strides, offset, order, opts );
    100 // returns <ndarray>
    101 
    102 // Attempt to access an out-of-bounds linear index (clamped):
    103 var v = arr.iget( 10 );
    104 // returns 4.0
    105 ```
    106 
    107 By default, the `mode` option is applied to subscripts which exceed array dimensions. To specify behavior for each dimension, set the `submode` option.
    108 
    109 ```javascript
    110 var opts = {
    111     'submode': [ 'wrap', 'clamp' ]
    112 };
    113 
    114 // Specify the array configuration:
    115 var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
    116 var shape = [ 2, 2, 2 ];
    117 var order = 'row-major';
    118 var strides = [ 4, 2, 1 ];
    119 var offset = 0;
    120 
    121 // Create a new ndarray:
    122 var arr = ndarray( 'generic', buffer, shape, strides, offset, order, opts );
    123 // returns <ndarray>
    124 
    125 // Attempt to access out-of-bounds subscripts:
    126 var v = arr.get( -2, 10, -1 ); // linear index: 3
    127 // returns 4.0
    128 ```
    129 
    130 * * *
    131 
    132 ### Properties
    133 
    134 <a name="static-prop-name"></a>
    135 
    136 #### ndarray.name
    137 
    138 String value of the ndarray constructor name.
    139 
    140 ```javascript
    141 var str = ndarray.name;
    142 // returns 'ndarray'
    143 ```
    144 
    145 <a name="prop-byte-length"></a>
    146 
    147 #### ndarray.prototype.byteLength
    148 
    149 Size (in bytes) of the array (if known).
    150 
    151 ```javascript
    152 var Float64Array = require( '@stdlib/array/float64' );
    153 
    154 // Specify the array configuration:
    155 var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] );
    156 var shape = [ 2, 2 ];
    157 var order = 'row-major';
    158 var strides = [ 2, 1 ];
    159 var offset = 0;
    160 
    161 // Create a new ndarray:
    162 var arr = ndarray( 'float64', buffer, shape, strides, offset, order );
    163 
    164 // Get the byte length:
    165 var nbytes = arr.byteLength;
    166 // returns 32
    167 ```
    168 
    169 If unable to determine the size of the array, the property value is `null`.
    170 
    171 ```javascript
    172 // Specify the array configuration:
    173 var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
    174 var shape = [ 2, 2 ];
    175 var order = 'row-major';
    176 var strides = [ 2, 1 ];
    177 var offset = 0;
    178 
    179 // Create a new ndarray:
    180 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    181 
    182 // Get the byte length:
    183 var nbytes = arr.byteLength;
    184 // returns null
    185 ```
    186 
    187 <a name="prop-bytes-per-element"></a>
    188 
    189 #### ndarray.prototype.BYTES_PER_ELEMENT
    190 
    191 Size (in bytes) of each array element (if known).
    192 
    193 ```javascript
    194 var Float32Array = require( '@stdlib/array/float32' );
    195 
    196 // Specify the array configuration:
    197 var buffer = new Float32Array( [ 1.0, 2.0, 3.0, 4.0 ] );
    198 var shape = [ 2, 2 ];
    199 var order = 'row-major';
    200 var strides = [ 2, 1 ];
    201 var offset = 0;
    202 
    203 // Create a new ndarray:
    204 var arr = ndarray( 'float32', buffer, shape, strides, offset, order );
    205 
    206 // Get the number of bytes per element:
    207 var nbytes = arr.BYTES_PER_ELEMENT;
    208 // returns 4
    209 ```
    210 
    211 If size of each array element is unknown, the property value is `null`.
    212 
    213 ```javascript
    214 // Specify the array configuration:
    215 var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
    216 var shape = [ 2, 2 ];
    217 var order = 'row-major';
    218 var strides = [ 2, 1 ];
    219 var offset = 0;
    220 
    221 // Create a new ndarray:
    222 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    223 
    224 // Get the number of bytes per element:
    225 var nbytes = arr.BYTES_PER_ELEMENT;
    226 // returns null
    227 ```
    228 
    229 <a name="prop-data"></a>
    230 
    231 #### ndarray.prototype.data
    232 
    233 A reference to the underlying data buffer.
    234 
    235 ```javascript
    236 var Int8Array = require( '@stdlib/array/int8' );
    237 
    238 // Specify the array configuration:
    239 var buffer = new Int8Array( [ 1, 2, 3, 4 ] );
    240 var shape = [ 2, 2 ];
    241 var order = 'row-major';
    242 var strides = [ 2, 1 ];
    243 var offset = 0;
    244 
    245 // Create a new ndarray:
    246 var arr = ndarray( 'int8', buffer, shape, strides, offset, order );
    247 
    248 // Get the buffer reference:
    249 var d = arr.data;
    250 // returns <Int8Array>[ 1, 2, 3, 4 ]
    251 
    252 var bool = ( d === buffer );
    253 // returns true
    254 ```
    255 
    256 <a name="prop-dtype"></a>
    257 
    258 #### ndarray.prototype.dtype
    259 
    260 Underlying [data type][@stdlib/ndarray/dtypes].
    261 
    262 ```javascript
    263 var Uint8Array = require( '@stdlib/array/uint8' );
    264 
    265 // Specify the array configuration:
    266 var buffer = new Uint8Array( [ 1, 2, 3, 4 ] );
    267 var shape = [ 2, 2 ];
    268 var order = 'row-major';
    269 var strides = [ -2, 1 ];
    270 var offset = 2;
    271 
    272 // Create a new ndarray:
    273 var arr = ndarray( 'uint8', buffer, shape, strides, offset, order );
    274 
    275 // Get the underlying data type:
    276 var dtype = arr.dtype;
    277 // returns 'uint8'
    278 ```
    279 
    280 <a name="prop-flags"></a>
    281 
    282 #### ndarray.prototype.flags
    283 
    284 Information regarding the memory layout of the array. The returned `object` has the following properties:
    285 
    286 -   **ROW_MAJOR_CONTIGUOUS**: `boolean` indicating if an array is row-major contiguous.
    287 -   **COLUMN_MAJOR_CONTIGUOUS**: `boolean` indicating if an array is column-major contiguous.
    288 
    289 An array is contiguous if (1) an array is compatible with being stored in a single memory segment and (2) each array element is adjacent to the next array element. Note that an array can be both row-major contiguous and column-major contiguous at the same time (e.g., if an array is a 1-dimensional ndarray with `strides = [1]`).
    290 
    291 ```javascript
    292 var Int32Array = require( '@stdlib/array/int32' );
    293 
    294 // Specify the array configuration:
    295 var buffer = new Int32Array( [ 1, 2, 3, 4 ] );
    296 var shape = [ 2, 2 ];
    297 var order = 'column-major';
    298 var strides = [ 1, 2 ];
    299 var offset = 0;
    300 
    301 // Create a new ndarray:
    302 var arr = ndarray( 'int32', buffer, shape, strides, offset, order );
    303 
    304 // Get the array flags:
    305 var flg = arr.flags;
    306 // returns {...}
    307 ```
    308 
    309 <a name="prop-length"></a>
    310 
    311 #### ndarray.prototype.length
    312 
    313 Number of array elements.
    314 
    315 ```javascript
    316 var Uint16Array = require( '@stdlib/array/uint16' );
    317 
    318 // Specify the array configuration:
    319 var buffer = new Uint16Array( [ 1, 2, 3, 4 ] );
    320 var shape = [ 2, 2 ];
    321 var order = 'column-major';
    322 var strides = [ -1, -2 ];
    323 var offset = 3;
    324 
    325 // Create a new ndarray:
    326 var arr = ndarray( 'uint16', buffer, shape, strides, offset, order );
    327 
    328 // Get the array length:
    329 var len = arr.length;
    330 // returns 4
    331 ```
    332 
    333 <a name="prop-ndims"></a>
    334 
    335 #### ndarray.prototype.ndims
    336 
    337 Number of dimensions.
    338 
    339 ```javascript
    340 var Uint8ClampedArray = require( '@stdlib/array/uint8c' );
    341 
    342 // Specify the array configuration:
    343 var buffer = new Uint8ClampedArray( [ 1, 2, 3, 4 ] );
    344 var shape = [ 2, 2 ];
    345 var order = 'row-major';
    346 var strides = [ -2, -1 ];
    347 var offset = 3;
    348 
    349 // Create a new ndarray:
    350 var arr = ndarray( 'uint8c', buffer, shape, strides, offset, order );
    351 
    352 // Get the number of dimensions:
    353 var ndims = arr.ndims;
    354 // returns 2
    355 ```
    356 
    357 <a name="prop-offset"></a>
    358 
    359 #### ndarray.prototype.offset
    360 
    361 Index offset which specifies the `buffer` index at which to start iterating over array elements.
    362 
    363 ```javascript
    364 var Int16Array = require( '@stdlib/array/int16' );
    365 
    366 // Specify the array configuration:
    367 var buffer = new Int16Array( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ] );
    368 var shape = [ 2, 2 ];
    369 var order = 'row-major';
    370 var strides = [ -2, -1 ];
    371 var offset = 10;
    372 
    373 // Create a new ndarray:
    374 var arr = ndarray( 'int16', buffer, shape, strides, offset, order );
    375 
    376 // Get the index offset:
    377 var o = arr.offset;
    378 // returns 10
    379 ```
    380 
    381 <a name="prop-order"></a>
    382 
    383 #### ndarray.prototype.order
    384 
    385 Array order. The array order is either row-major (C-style) or column-major (Fortran-style).
    386 
    387 ```javascript
    388 var Uint32Array = require( '@stdlib/array/uint32' );
    389 
    390 // Specify the array configuration:
    391 var buffer = new Uint32Array( [ 1, 2, 3, 4 ] );
    392 var shape = [ 2, 2 ];
    393 var order = 'row-major';
    394 var strides = [ 2, 1 ];
    395 var offset = 0;
    396 
    397 // Create a new ndarray:
    398 var arr = ndarray( 'uint32', buffer, shape, strides, offset, order );
    399 
    400 // Get the array order:
    401 var ord = arr.order;
    402 // returns 'row-major'
    403 ```
    404 
    405 <a name="prop-shape"></a>
    406 
    407 #### ndarray.prototype.shape
    408 
    409 Returns a copy of the array shape.
    410 
    411 ```javascript
    412 // Specify the array configuration:
    413 var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
    414 var shape = [ 2, 2 ];
    415 var order = 'row-major';
    416 var strides = [ 2, 1 ];
    417 var offset = 2;
    418 
    419 // Create a new ndarray:
    420 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    421 
    422 // Get the array shape:
    423 var dims = arr.shape;
    424 // returns [ 2, 2 ]
    425 ```
    426 
    427 <a name="prop-strides"></a>
    428 
    429 #### ndarray.prototype.strides
    430 
    431 Returns a copy of the array strides which specify how to access data along corresponding array dimensions.
    432 
    433 ```javascript
    434 // Specify the array configuration:
    435 var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
    436 var shape = [ 2, 2 ];
    437 var order = 'column-major';
    438 var strides = [ -1, 2 ];
    439 var offset = 1;
    440 
    441 // Create a new ndarray:
    442 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    443 
    444 // Get the array strides:
    445 var s = arr.strides;
    446 // returns [ -1, 2 ]
    447 ```
    448 
    449 * * *
    450 
    451 ### Methods
    452 
    453 <a name="method-get"></a>
    454 
    455 #### ndarray.prototype.get( i, j, k, ... )
    456 
    457 Returns an array element specified according to provided subscripts. The number of provided subscripts must **equal** the number of dimensions.
    458 
    459 ```javascript
    460 // Specify the array configuration:
    461 var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
    462 var shape = [ 2, 2 ];
    463 var order = 'row-major';
    464 var strides = [ 2, 1 ];
    465 var offset = 2;
    466 
    467 // Create a new ndarray:
    468 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    469 
    470 // Get the element located at (1,1):
    471 var v = arr.get( 1, 1 );
    472 // returns 6.0
    473 ```
    474 
    475 <a name="method-iget"></a>
    476 
    477 #### ndarray.prototype.iget( idx )
    478 
    479 Returns an array element located at a specified linear index.
    480 
    481 ```javascript
    482 // Specify the array configuration:
    483 var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
    484 var shape = [ 2, 2 ];
    485 var order = 'row-major';
    486 var strides = [ 2, 1 ];
    487 var offset = 2;
    488 
    489 // Create a new ndarray:
    490 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    491 
    492 // Get the element located at index 3:
    493 var v = arr.iget( 3 );
    494 // returns 6.0
    495 ```
    496 
    497 For zero-dimensional arrays, the input argument is ignored and, for clarity, should **not** be provided.
    498 
    499 <a name="method-set"></a>
    500 
    501 #### ndarray.prototype.set( i, j, k, ..., v )
    502 
    503 Sets an array element specified according to provided subscripts. The number of provided subscripts must **equal** the number of dimensions.
    504 
    505 ```javascript
    506 // Specify the array configuration:
    507 var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
    508 var shape = [ 2, 2 ];
    509 var order = 'row-major';
    510 var strides = [ 2, 1 ];
    511 var offset = 0;
    512 
    513 // Create a new ndarray:
    514 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    515 
    516 // Set the element located at (1,1):
    517 arr.set( 1, 1, 40.0 );
    518 var v = arr.get( 1, 1 );
    519 // returns 40.0
    520 
    521 // Get the underlying buffer:
    522 var d = arr.data;
    523 // returns [ 1.0, 2.0, 3.0, 40.0 ]
    524 ```
    525 
    526 The method returns the `ndarray` instance.
    527 
    528 <a name="method-iset"></a>
    529 
    530 #### ndarray.prototype.iset( idx, v )
    531 
    532 Sets an array element located at a specified linear index.
    533 
    534 ```javascript
    535 // Specify the array configuration:
    536 var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
    537 var shape = [ 2, 2 ];
    538 var order = 'row-major';
    539 var strides = [ 2, 1 ];
    540 var offset = 0;
    541 
    542 // Create a new ndarray:
    543 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    544 
    545 // Set the element located at index 3:
    546 arr.iset( 3, 40.0 );
    547 var v = arr.iget( 3 );
    548 // returns 40.0
    549 
    550 // Get the underlying buffer:
    551 var d = arr.data;
    552 // returns [ 1.0, 2.0, 3.0, 40.0 ]
    553 ```
    554 
    555 For zero-dimensional arrays, the first, and **only**, argument should be the value `v` to set. The method returns the `ndarray` instance.
    556 
    557 <a name="method-to-string"></a>
    558 
    559 #### ndarray.prototype.toString()
    560 
    561 Serializes an `ndarray` as a `string`.
    562 
    563 ```javascript
    564 // Specify the array configuration:
    565 var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
    566 var shape = [ 3, 2 ];
    567 var order = 'row-major';
    568 var strides = [ 2, 1 ];
    569 var offset = 2;
    570 
    571 // Create a new ndarray:
    572 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    573 
    574 // Serialize to a string:
    575 var str = arr.toString();
    576 // returns "ndarray( 'generic', [ 3, 4, 5, 6, 7, 8 ], [ 3, 2 ], [ 2, 1 ], 0, 'row-major' )"
    577 ```
    578 
    579 The method does **not** serialize data outside of the buffer region defined by the array configuration.
    580 
    581 <a name="method-to-json"></a>
    582 
    583 #### ndarray.prototype.toJSON()
    584 
    585 Serializes an `ndarray` as a [JSON][json] `object`. `JSON.stringify()` implicitly calls this method when stringifying an `ndarray` instance.
    586 
    587 ```javascript
    588 // Specify the array configuration:
    589 var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
    590 var shape = [ 3, 2 ];
    591 var order = 'row-major';
    592 var strides = [ 2, 1 ];
    593 var offset = 2;
    594 
    595 // Create a new ndarray:
    596 var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    597 
    598 // Serialize to JSON:
    599 var o = arr.toJSON();
    600 // returns { 'type': 'ndarray', 'dtype': 'generic', 'flags': {...}, 'offset': 0, 'order': 'row-major', 'shape': [ 3, 2 ], 'strides': [ 2, 1 ], 'data': [ 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] }
    601 ```
    602 
    603 The method does **not** serialize data outside of the buffer region defined by the array configuration.
    604 
    605 </section>
    606 
    607 <!-- /.usage -->
    608 
    609 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    610 
    611 <section class="notes">
    612 
    613 ## Notes
    614 
    615 -   To create a zero-dimensional array, provide an empty `shape` and a single `strides` element equal to `0`. The `order` can be either `row-major` or `column-major` and has no effect on data storage or access.
    616 
    617     ```javascript
    618     var buffer = [ 1 ];
    619     var shape = [];
    620     var order = 'row-major';
    621     var strides = [ 0 ];
    622     var offset = 0;
    623 
    624     // Create a new zero-dimensional array:
    625     var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
    626     // returns <ndarray>
    627     ```
    628 
    629 </section>
    630 
    631 <!-- /.notes -->
    632 
    633 <!-- Package usage examples. -->
    634 
    635 <section class="examples">
    636 
    637 * * *
    638 
    639 ## Examples
    640 
    641 <!-- eslint no-undef: "error" -->
    642 
    643 ```javascript
    644 var Float32Array = require( '@stdlib/array/float32' );
    645 var ndarray = require( '@stdlib/ndarray/ctor' );
    646 
    647 // Create a data buffer:
    648 var buffer = new Float32Array( (3*3*3*3) + 100 );
    649 
    650 // Specify the array shape:
    651 var shape = [ 3, 3, 3, 3 ];
    652 
    653 // Specify the array strides:
    654 var strides = [ 27, 9, 3, 1 ];
    655 
    656 // Specify the index offset:
    657 var offset = 4;
    658 
    659 // Specify the order:
    660 var order = 'row-major'; // C-style
    661 
    662 // Create a new ndarray:
    663 var arr = ndarray( 'float32', buffer, shape, strides, offset, order );
    664 
    665 // Retrieve an array value:
    666 var v = arr.get( 1, 2, 1, 2 );
    667 // returns 0.0
    668 
    669 // Set an array value:
    670 arr.set( 1, 2, 1, 2, 10.0 );
    671 
    672 // Retrieve the array value:
    673 v = arr.get( 1, 2, 1, 2 );
    674 // returns 10.0
    675 
    676 // Serialize the array as a string:
    677 var str = arr.toString();
    678 // returns "ndarray( 'float32', new Float32Array( [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] ), [ 3, 3, 3, 3 ], [ 27, 9, 3, 1 ], 0, 'row-major' )"
    679 
    680 // Serialize the array as JSON:
    681 str = JSON.stringify( arr.toJSON() );
    682 // returns '{"type":"ndarray","dtype":"float32","flags":{},"order":"row-major","shape":[3,3,3,3],"strides":[27,9,3,1],"data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,10,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}'
    683 ```
    684 
    685 </section>
    686 
    687 <!-- /.examples -->
    688 
    689 <!-- C interface documentation. -->
    690 
    691 * * *
    692 
    693 <section class="c">
    694 
    695 ## C APIs
    696 
    697 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
    698 
    699 <section class="intro">
    700 
    701 </section>
    702 
    703 <!-- /.intro -->
    704 
    705 <!-- C usage documentation. -->
    706 
    707 <section class="usage">
    708 
    709 ### Usage
    710 
    711 ```c
    712 #include "stdlib/ndarray/ctor.h"
    713 ```
    714 
    715 #### ndarray
    716 
    717 Structure holding ndarray data.
    718 
    719 ```c
    720 #include "stdlib/ndarray/dtypes.h"
    721 #include "stdlib/ndarray/index_modes.h"
    722 #include "stdlib/ndarray/orders.h"
    723 #include "stdlib/ndarray/base/bytes_per_element.h"
    724 #include <stdint.h>
    725 
    726 struct ndarray {
    727     // Underlying data type:
    728     int16_t dtype;
    729 
    730     // Pointer to the underlying byte array:
    731     uint8_t *data;
    732 
    733     // Number of array dimensions:
    734     int64_t ndims;
    735 
    736     // Array shape (dimensions):
    737     int64_t *shape;
    738 
    739     // Array strides (in bytes) specifying how to iterate over a strided array:
    740     int64_t *strides;
    741 
    742     // Byte offset which specifies the location at which to start iterating over array elements:
    743     int64_t offset;
    744 
    745     // Array order (either row-major (C-style) or column-major (Fortran-style)):
    746     int8_t order;
    747 
    748     // Mode specifying how to handle indices which exceed array dimensions:
    749     int8_t imode;
    750 
    751     // Number of subscript modes:
    752     int64_t nsubmodes;
    753 
    754     // Mode(s) specifying how to handle subscripts which exceed array dimensions on a per dimension basis:
    755     int8_t *submodes;
    756 
    757     // Number of array elements:
    758     int64_t length;
    759 
    760     // Size in bytes:
    761     int64_t byteLength;
    762 
    763     // Number of bytes per element (i.e., item size):
    764     int64_t BYTES_PER_ELEMENT;
    765 
    766     // Bit mask providing information regarding the memory layout of the array (e.g., see macros):
    767     int64_t flags;
    768 };
    769 ```
    770 
    771 #### STDLIB_NDARRAY_ROW_MAJOR_CONTIGUOUS_FLAG
    772 
    773 Macro defining a flag indicating whether an ndarray is row-major (C-style) contiguous.
    774 
    775 ```c
    776 #define STDLIB_NDARRAY_ROW_MAJOR_CONTIGUOUS_FLAG 0x0001
    777 ```
    778 
    779 Notes:
    780 
    781 -   Row-major order indicates that the last ndarray index varies the fastest.
    782 -   Contiguous means that an ndarray is compatible with being stored in a single memory segment and that ndarray elements are adjacent to each other in memory.
    783 -   `strides` array is in reverse order to that of column-major order.
    784 -   An ndarray can be both row-major and column-major contiguous (e.g., if an ndarray is one-dimensional).
    785 
    786 #### STDLIB_NDARRAY_COLUMN_MAJOR_CONTIGUOUS_FLAG
    787 
    788 Macro defining a flag indicating whether an ndarray is column-major (Fortran-style) contiguous.
    789 
    790 ```c
    791 #define STDLIB_NDARRAY_COLUMN_MAJOR_CONTIGUOUS_FLAG 0x0002
    792 ```
    793 
    794 Notes:
    795 
    796 -   Column-major order indicates that the first ndarray index varies the fastest.
    797 -   Contiguous means that an ndarray is compatible with being stored in a single memory segment and that ndarray elements are adjacent to each other in memory.
    798 -   `strides` array is in reverse order to that of row-major order.
    799 -   An ndarray can be both row-major and column-major contiguous (e.g., if an ndarray is one-dimensional).
    800 
    801 * * *
    802 
    803 <!-- NOTE: keep functions in alphabetical order -->
    804 
    805 #### stdlib_ndarray_allocate( dtype, \*data, ndims, \*shape, \*strides, offset, order, imode, nsubmodes, \*submodes )
    806 
    807 Returns a pointer to a dynamically allocated ndarray.
    808 
    809 ```c
    810 #include "stdlib/ndarray/ctor.h"
    811 #include "stdlib/ndarray/dtypes.h"
    812 #include "stdlib/ndarray/index_modes.h"
    813 #include "stdlib/ndarray/orders.h"
    814 #include "stdlib/ndarray/base/bytes_per_element.h"
    815 #include <stdlib.h>
    816 #include <stdio.h>
    817 #include <stdint.h>
    818 
    819 // Specify the underlying data type:
    820 enum STDLIB_NDARRAY_DTYPE dtype = STDLIB_NDARRAY_FLOAT64;
    821 
    822 // Create an underlying byte array:
    823 uint8_t buffer[] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
    824 
    825 // Specify the number of array dimensions:
    826 int64_t ndims = 1;
    827 
    828 // Specify the array shape:
    829 int64_t shape[] = { 3 }; // vector consisting of 3 doubles
    830 
    831 // Specify the array strides:
    832 int64_t strides[] = { STDLIB_NDARRAY_FLOAT64_BYTES_PER_ELEMENT };
    833 
    834 // Specify the byte offset:
    835 int64_t offset = 0;
    836 
    837 // Specify the array order (note: this does not matter for a 1-dimensional array):
    838 enum STDLIB_NDARRAY_ORDER order = STDLIB_NDARRAY_ROW_MAJOR;
    839 
    840 // Specify the index mode:
    841 enum STDLIB_NDARRAY_INDEX_MODE imode = STDLIB_NDARRAY_INDEX_ERROR;
    842 
    843 // Specify the subscript index modes:
    844 int8_t submodes[] = { STDLIB_NDARRAY_INDEX_ERROR };
    845 int64_t nsubmodes = 1;
    846 
    847 // Create an ndarray:
    848 struct ndarray *x = stdlib_ndarray_allocate( dtype, buffer, ndims, shape, strides, offset, order, imode, nsubmodes, submodes );
    849 if ( x == NULL ) {
    850     fprintf( stderr, "Error allocating memory.\n" );
    851     exit( 1 );
    852 }
    853 
    854 // Free allocated memory:
    855 stdlib_ndarray_free( x );
    856 ```
    857 
    858 The function accepts the following arguments:
    859 
    860 -   **dtype**: `[in] int16_t` [data type][@stdlib/ndarray/dtypes].
    861 -   **data**: `[in] uint8_t*` pointer to the underlying byte array.
    862 -   **ndims**: `[in] int64_t` number of dimensions.
    863 -   **shape**: `[in] int64_t*` array shape (i.e., dimensions).
    864 -   **strides**: `[in] int64_t*` array strides (in bytes).
    865 -   **offset**: `[in] int64_t` byte offset specifying the location of the first element.
    866 -   **order**: `[in] int8_t` specifies whether an array is [row-major][@stdlib/ndarray/orders] (C-style) or [column-major][@stdlib/ndarray/orders] (Fortran-style).
    867 -   **imode**: `[in] int8_t` specifies the [index mode][@stdlib/ndarray/index-modes] (i.e., how to handle indices which exceed array dimensions).
    868 -   **nsubmodes**: `[in] int64_t` number of subscript modes.
    869 -   **submodes**: `[in] int8_t*` specifies how to handle subscripts which [exceed][@stdlib/ndarray/index-modes] array dimensions on a per dimension basis (if provided fewer submodes than dimensions, submodes are recycled using modulo arithmetic).
    870 
    871 ```c
    872 struct ndarray * stdlib_ndarray_allocate( int16_t dtype, uint8_t *data, int64_t ndims, int64_t *shape, int64_t *strides, int64_t offset, int8_t order, int8_t imode, int64_t nsubmodes, int8_t *submodes );
    873 ```
    874 
    875 Notes:
    876 
    877 -   The user is responsible for freeing the allocated memory.
    878 
    879 #### stdlib_ndarray_bytelength( *arr )
    880 
    881 Returns the size of an ndarray (in bytes).
    882 
    883 ```c
    884 #include "stdlib/ndarray/ctor.h"
    885 #include <stdint.h>
    886 #include <stdlib.h>
    887 #include <stdio.h>
    888 
    889 // ...
    890 
    891 // Create an ndarray:
    892 struct ndarray *x = stdlib_ndarray_allocate( ... );
    893 if ( x == NULL ) {
    894     fprintf( stderr, "Error allocating memory.\n" );
    895     exit( 1 );
    896 }
    897 
    898 // ...
    899 
    900 // Retrieve the ndarray size:
    901 int64_t N = stdlib_ndarray_bytelength( x );
    902 
    903 // ...
    904 
    905 // Free allocated memory:
    906 stdlib_ndarray_free( x );
    907 ```
    908 
    909 The function accepts the following arguments:
    910 
    911 -   **arr**: `[in] struct ndarray*` input ndarray.
    912 
    913 ```c
    914 int64_t stdlib_ndarray_bytelength( const struct ndarray *arr );
    915 ```
    916 
    917 #### stdlib_ndarray_data( *arr )
    918 
    919 Returns a pointer to an ndarray's underlying byte array.
    920 
    921 ```c
    922 #include "stdlib/ndarray/ctor.h"
    923 #include <stdint.h>
    924 #include <stdlib.h>
    925 #include <stdio.h>
    926 
    927 // ...
    928 
    929 // Create an ndarray:
    930 struct ndarray *x = stdlib_ndarray_allocate( ... );
    931 if ( x == NULL ) {
    932     fprintf( stderr, "Error allocating memory.\n" );
    933     exit( 1 );
    934 }
    935 
    936 // ...
    937 
    938 // Retrieve the underlying byte array:
    939 uint8_t *data = stdlib_ndarray_data( x );
    940 
    941 // ...
    942 
    943 // Free allocated memory:
    944 stdlib_ndarray_free( x );
    945 ```
    946 
    947 The function accepts the following arguments:
    948 
    949 -   **arr**: `[in] struct ndarray*` input ndarray.
    950 
    951 ```c
    952 uint8_t * stdlib_ndarray_data( const struct ndarray *arr );
    953 ```
    954 
    955 #### stdlib_ndarray_dimension( *arr, i )
    956 
    957 Returns an ndarray dimension.
    958 
    959 ```c
    960 #include "stdlib/ndarray/ctor.h"
    961 #include <stdint.h>
    962 #include <stdlib.h>
    963 #include <stdio.h>
    964 
    965 // ...
    966 
    967 // Create an ndarray:
    968 struct ndarray *x = stdlib_ndarray_allocate( ... );
    969 if ( x == NULL ) {
    970     fprintf( stderr, "Error allocating memory.\n" );
    971     exit( 1 );
    972 }
    973 
    974 // ...
    975 
    976 // Retrieve a dimension:
    977 int64_t dim = stdlib_ndarray_dimension( x, 0 );
    978 
    979 // ...
    980 
    981 // Free allocated memory:
    982 stdlib_ndarray_free( x );
    983 ```
    984 
    985 The function accepts the following arguments:
    986 
    987 -   **arr**: `[in] struct ndarray*` input ndarray.
    988 -   **i**: `[in] int64_t` dimension index.
    989 
    990 ```c
    991 int64_t stdlib_ndarray_dimension( const struct ndarray *arr, const int64_t i );
    992 ```
    993 
    994 Notes:
    995 
    996 -   The function does perform bounds checking for the dimension index.
    997 
    998 #### stdlib_ndarray_disable_flags( *arr, flags )
    999 
   1000 Disables specified ndarray flags.
   1001 
   1002 ```c
   1003 #include "stdlib/ndarray/ctor.h"
   1004 #include <stdint.h>
   1005 #include <stdlib.h>
   1006 #include <stdio.h>
   1007 
   1008 // ...
   1009 
   1010 // Create an ndarray:
   1011 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1012 if ( x == NULL ) {
   1013     fprintf( stderr, "Error allocating memory.\n" );
   1014     exit( 1 );
   1015 }
   1016 
   1017 // ...
   1018 
   1019 // Disables specified ndarray flags:
   1020 int8_t status = stdlib_ndarray_disable_flags( x, STDLIB_NDARRAY_ROW_MAJOR_CONTIGUOUS_FLAG );
   1021 
   1022 // ...
   1023 
   1024 // Free allocated memory:
   1025 stdlib_ndarray_free( x );
   1026 ```
   1027 
   1028 The function accepts the following arguments:
   1029 
   1030 -   **arr**: `[in] struct ndarray*` input ndarray.
   1031 -   **flags**: `[in] int64_t` bit mask to disable flags.
   1032 
   1033 The function returns a status code of `0` if able to successfully disable flags.
   1034 
   1035 ```c
   1036 int8_t stdlib_ndarray_disable_flags( const struct ndarray *arr, const int64_t flags );
   1037 ```
   1038 
   1039 Notes:
   1040 
   1041 -   The function does not perform any sanity checks and **assumes** the user knows what s/he is doing.
   1042 
   1043 #### stdlib_ndarray_dtype( *arr )
   1044 
   1045 Returns the data type of an ndarray.
   1046 
   1047 ```c
   1048 #include "stdlib/ndarray/ctor.h"
   1049 #include "stdlib/ndarray/dtypes.h"
   1050 #include <stdlib.h>
   1051 #include <stdio.h>
   1052 
   1053 // ...
   1054 
   1055 // Create an ndarray:
   1056 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1057 if ( x == NULL ) {
   1058     fprintf( stderr, "Error allocating memory.\n" );
   1059     exit( 1 );
   1060 }
   1061 
   1062 // ...
   1063 
   1064 // Retrieve the dtype:
   1065 enum STDLIB_NDARRAY_DTYPE dtype = stdlib_ndarray_dtype( x );
   1066 
   1067 // ...
   1068 
   1069 // Free allocated memory:
   1070 stdlib_ndarray_free( x );
   1071 ```
   1072 
   1073 The function accepts the following arguments:
   1074 
   1075 -   **arr**: `[in] struct ndarray*` input ndarray.
   1076 
   1077 ```c
   1078 int16_t stdlib_ndarray_dtype( const struct ndarray *arr );
   1079 ```
   1080 
   1081 #### stdlib_ndarray_enable_flags( *arr, flags )
   1082 
   1083 Enables specified ndarray flags.
   1084 
   1085 ```c
   1086 #include "stdlib/ndarray/ctor.h"
   1087 #include <stdint.h>
   1088 #include <stdlib.h>
   1089 #include <stdio.h>
   1090 
   1091 // ...
   1092 
   1093 // Create an ndarray:
   1094 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1095 if ( x == NULL ) {
   1096     fprintf( stderr, "Error allocating memory.\n" );
   1097     exit( 1 );
   1098 }
   1099 
   1100 // ...
   1101 
   1102 // Enables specified ndarray flags:
   1103 int8_t status = stdlib_ndarray_enable_flags( x, STDLIB_NDARRAY_ROW_MAJOR_CONTIGUOUS_FLAG );
   1104 
   1105 // ...
   1106 
   1107 // Free allocated memory:
   1108 stdlib_ndarray_free( x );
   1109 ```
   1110 
   1111 The function accepts the following arguments:
   1112 
   1113 -   **arr**: `[in] struct ndarray*` input ndarray.
   1114 -   **flags**: `[in] int64_t` bit mask to enable flags.
   1115 
   1116 The function returns a status code of `0` if able to successfully enable flags.
   1117 
   1118 ```c
   1119 int8_t stdlib_ndarray_enable_flags( const struct ndarray *arr, const int64_t flags );
   1120 ```
   1121 
   1122 Notes:
   1123 
   1124 -   The function does not perform any sanity checks and **assumes** the user knows what s/he is doing.
   1125 
   1126 #### stdlib_ndarray_flags( *arr )
   1127 
   1128 Returns ndarray flags as a single integer value.
   1129 
   1130 ```c
   1131 #include "stdlib/ndarray/ctor.h"
   1132 #include <stdint.h>
   1133 #include <stdlib.h>
   1134 #include <stdio.h>
   1135 
   1136 // ...
   1137 
   1138 // Create an ndarray:
   1139 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1140 if ( x == NULL ) {
   1141     fprintf( stderr, "Error allocating memory.\n" );
   1142     exit( 1 );
   1143 }
   1144 
   1145 // ...
   1146 
   1147 // Retrieve the ndarray flags:
   1148 int64_t flags = stdlib_ndarray_flags( x );
   1149 
   1150 // ...
   1151 
   1152 // Free allocated memory:
   1153 stdlib_ndarray_free( x );
   1154 ```
   1155 
   1156 The function accepts the following arguments:
   1157 
   1158 -   **arr**: `[in] struct ndarray*` input ndarray.
   1159 
   1160 ```c
   1161 int64_t stdlib_ndarray_flags( const struct ndarray *arr );
   1162 ```
   1163 
   1164 #### stdlib_ndarray_free( *arr )
   1165 
   1166 Frees an ndarray's allocated memory.
   1167 
   1168 ```c
   1169 #include "stdlib/ndarray/ctor.h"
   1170 #include <stdlib.h>
   1171 #include <stdio.h>
   1172 
   1173 // ...
   1174 
   1175 // Create an ndarray:
   1176 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1177 if ( x == NULL ) {
   1178     fprintf( stderr, "Error allocating memory.\n" );
   1179     exit( 1 );
   1180 }
   1181 
   1182 // ...
   1183 
   1184 // Free allocated memory:
   1185 stdlib_ndarray_free( x );
   1186 ```
   1187 
   1188 The function accepts the following arguments:
   1189 
   1190 -   **arr**: `[in] struct ndarray*` input ndarray.
   1191 
   1192 ```c
   1193 void stdlib_ndarray_free( struct ndarray *arr );
   1194 ```
   1195 
   1196 #### stdlib_ndarray_has_flags( *arr, flags )
   1197 
   1198 Tests whether an ndarray has specified flags enabled.
   1199 
   1200 ```c
   1201 #include "stdlib/ndarray/ctor.h"
   1202 #include <stdint.h>
   1203 #include <stdlib.h>
   1204 #include <stdio.h>
   1205 
   1206 // ...
   1207 
   1208 // Create an ndarray:
   1209 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1210 if ( x == NULL ) {
   1211     fprintf( stderr, "Error allocating memory.\n" );
   1212     exit( 1 );
   1213 }
   1214 
   1215 // ...
   1216 
   1217 // Test whether an ndarray is row-major contiguous:
   1218 int8_t out = stdlib_ndarray_flags( x, STDLIB_NDARRAY_ROW_MAJOR_CONTIGUOUS_FLAG );
   1219 
   1220 // ...
   1221 
   1222 // Free allocated memory:
   1223 stdlib_ndarray_free( x );
   1224 ```
   1225 
   1226 The function accepts the following arguments:
   1227 
   1228 -   **arr**: `[in] struct ndarray*` input ndarray.
   1229 -   **flags**: `[in] int64_t` bit mask specifying flags to test against.
   1230 
   1231 The function returns `1` if flags are set and `0` otherwise.
   1232 
   1233 ```c
   1234 int8_t stdlib_ndarray_has_flags( const struct ndarray *arr, const int64_t flags );
   1235 ```
   1236 
   1237 #### stdlib_ndarray_index_mode( *arr )
   1238 
   1239 Returns the index mode of an ndarray.
   1240 
   1241 ```c
   1242 #include "stdlib/ndarray/ctor.h"
   1243 #include "stdlib/ndarray/index_modes.h"
   1244 #include <stdlib.h>
   1245 #include <stdio.h>
   1246 
   1247 // ...
   1248 
   1249 // Create an ndarray:
   1250 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1251 if ( x == NULL ) {
   1252     fprintf( stderr, "Error allocating memory.\n" );
   1253     exit( 1 );
   1254 }
   1255 
   1256 // ...
   1257 
   1258 // Retrieve the index mode:
   1259 enum STDLIB_NDARRAY_INDEX_MODE imode = stdlib_ndarray_index_mode( x );
   1260 
   1261 // ...
   1262 
   1263 // Free allocated memory:
   1264 stdlib_ndarray_free( x );
   1265 ```
   1266 
   1267 The function accepts the following arguments:
   1268 
   1269 -   **arr**: `[in] struct ndarray*` input ndarray.
   1270 
   1271 ```c
   1272 int8_t stdlib_ndarray_index_mode( const struct ndarray *arr );
   1273 ```
   1274 
   1275 #### stdlib_ndarray_length( *arr )
   1276 
   1277 Returns the number of elements in an ndarray.
   1278 
   1279 ```c
   1280 #include "stdlib/ndarray/ctor.h"
   1281 #include <stdint.h>
   1282 #include <stdlib.h>
   1283 #include <stdio.h>
   1284 
   1285 // ...
   1286 
   1287 // Create an ndarray:
   1288 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1289 if ( x == NULL ) {
   1290     fprintf( stderr, "Error allocating memory.\n" );
   1291     exit( 1 );
   1292 }
   1293 
   1294 // ...
   1295 
   1296 // Retrieve the number of elements:
   1297 int64_t N = stdlib_ndarray_length( x );
   1298 
   1299 // ...
   1300 
   1301 // Free allocated memory:
   1302 stdlib_ndarray_free( x );
   1303 ```
   1304 
   1305 The function accepts the following arguments:
   1306 
   1307 -   **arr**: `[in] struct ndarray*` input ndarray.
   1308 
   1309 ```c
   1310 int64_t stdlib_ndarray_length( const struct ndarray *arr );
   1311 ```
   1312 
   1313 #### stdlib_ndarray_ndims( *arr )
   1314 
   1315 Returns the number of ndarray dimensions.
   1316 
   1317 ```c
   1318 #include "stdlib/ndarray/ctor.h"
   1319 #include <stdint.h>
   1320 #include <stdlib.h>
   1321 #include <stdio.h>
   1322 
   1323 // ...
   1324 
   1325 // Create an ndarray:
   1326 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1327 if ( x == NULL ) {
   1328     fprintf( stderr, "Error allocating memory.\n" );
   1329     exit( 1 );
   1330 }
   1331 
   1332 // ...
   1333 
   1334 // Retrieve the number of dimensions:
   1335 int64_t ndims = stdlib_ndarray_ndims( x );
   1336 
   1337 // ...
   1338 
   1339 // Free allocated memory:
   1340 stdlib_ndarray_free( x );
   1341 ```
   1342 
   1343 The function accepts the following arguments:
   1344 
   1345 -   **arr**: `[in] struct ndarray*` input ndarray.
   1346 
   1347 ```c
   1348 int64_t stdlib_ndarray_ndims( const struct ndarray *arr );
   1349 ```
   1350 
   1351 #### stdlib_ndarray_nsubmodes( *arr )
   1352 
   1353 Returns the number of ndarray subscript modes.
   1354 
   1355 ```c
   1356 #include "stdlib/ndarray/ctor.h"
   1357 #include <stdint.h>
   1358 #include <stdlib.h>
   1359 #include <stdio.h>
   1360 
   1361 // ...
   1362 
   1363 // Create an ndarray:
   1364 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1365 if ( x == NULL ) {
   1366     fprintf( stderr, "Error allocating memory.\n" );
   1367     exit( 1 );
   1368 }
   1369 
   1370 // ...
   1371 
   1372 // Retrieve the number of index modes:
   1373 int64_t n = stdlib_ndarray_nsubmodes( x );
   1374 
   1375 // ...
   1376 
   1377 // Free allocated memory:
   1378 stdlib_ndarray_free( x );
   1379 ```
   1380 
   1381 The function accepts the following arguments:
   1382 
   1383 -   **arr**: `[in] struct ndarray*` input ndarray.
   1384 
   1385 ```c
   1386 int64_t stdlib_ndarray_nsubmodes( const struct ndarray *arr );
   1387 ```
   1388 
   1389 #### stdlib_ndarray_offset( *arr )
   1390 
   1391 Returns an ndarray index offset (in bytes).
   1392 
   1393 ```c
   1394 #include "stdlib/ndarray/ctor.h"
   1395 #include <stdint.h>
   1396 #include <stdlib.h>
   1397 #include <stdio.h>
   1398 
   1399 // ...
   1400 
   1401 // Create an ndarray:
   1402 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1403 if ( x == NULL ) {
   1404     fprintf( stderr, "Error allocating memory.\n" );
   1405     exit( 1 );
   1406 }
   1407 
   1408 // ...
   1409 
   1410 // Retrieve the index offset:
   1411 int64_t offset = stdlib_ndarray_offset( x );
   1412 
   1413 // ...
   1414 
   1415 // Free allocated memory:
   1416 stdlib_ndarray_free( x );
   1417 ```
   1418 
   1419 The function accepts the following arguments:
   1420 
   1421 -   **arr**: `[in] struct ndarray*` input ndarray.
   1422 
   1423 ```c
   1424 int64_t stdlib_ndarray_offset( const struct ndarray *arr );
   1425 ```
   1426 
   1427 #### stdlib_ndarray_order( *arr )
   1428 
   1429 Returns the order of an ndarray.
   1430 
   1431 ```c
   1432 #include "stdlib/ndarray/ctor.h"
   1433 #include "stdlib/ndarray/orders.h"
   1434 #include <stdlib.h>
   1435 #include <stdio.h>
   1436 
   1437 // ...
   1438 
   1439 // Create an ndarray:
   1440 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1441 if ( x == NULL ) {
   1442     fprintf( stderr, "Error allocating memory.\n" );
   1443     exit( 1 );
   1444 }
   1445 
   1446 // ...
   1447 
   1448 // Retrieve the order:
   1449 enum STDLIB_NDARRAY_ORDER order = stdlib_ndarray_order( x );
   1450 
   1451 // ...
   1452 
   1453 // Free allocated memory:
   1454 stdlib_ndarray_free( x );
   1455 ```
   1456 
   1457 The function accepts the following arguments:
   1458 
   1459 -   **arr**: `[in] struct ndarray*` input ndarray.
   1460 
   1461 ```c
   1462 int8_t stdlib_ndarray_order( const struct ndarray *arr );
   1463 ```
   1464 
   1465 #### stdlib_ndarray_shape( *arr )
   1466 
   1467 Returns a pointer to an array containing an ndarray shape (dimensions).
   1468 
   1469 ```c
   1470 #include "stdlib/ndarray/ctor.h"
   1471 #include <stdint.h>
   1472 #include <stdlib.h>
   1473 #include <stdio.h>
   1474 
   1475 // ...
   1476 
   1477 // Create an ndarray:
   1478 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1479 if ( x == NULL ) {
   1480     fprintf( stderr, "Error allocating memory.\n" );
   1481     exit( 1 );
   1482 }
   1483 
   1484 // ...
   1485 
   1486 // Retrieve the shape:
   1487 int64_t *shape = stdlib_ndarray_shape( x );
   1488 
   1489 // ...
   1490 
   1491 // Free allocated memory:
   1492 stdlib_ndarray_free( x );
   1493 ```
   1494 
   1495 The function accepts the following arguments:
   1496 
   1497 -   **arr**: `[in] struct ndarray*` input ndarray.
   1498 
   1499 ```c
   1500 int64_t * stdlib_ndarray_shape( const struct ndarray *arr );
   1501 ```
   1502 
   1503 #### stdlib_ndarray_stride( *arr, i )
   1504 
   1505 Returns an ndarray stride (in bytes).
   1506 
   1507 ```c
   1508 #include "stdlib/ndarray/ctor.h"
   1509 #include <stdint.h>
   1510 #include <stdlib.h>
   1511 #include <stdio.h>
   1512 
   1513 // ...
   1514 
   1515 // Create an ndarray:
   1516 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1517 if ( x == NULL ) {
   1518     fprintf( stderr, "Error allocating memory.\n" );
   1519     exit( 1 );
   1520 }
   1521 
   1522 // ...
   1523 
   1524 // Retrieve a stride:
   1525 int64_t s = stdlib_ndarray_stride( x, 0 );
   1526 
   1527 // ...
   1528 
   1529 // Free allocated memory:
   1530 stdlib_ndarray_free( x );
   1531 ```
   1532 
   1533 The function accepts the following arguments:
   1534 
   1535 -   **arr**: `[in] struct ndarray*` input ndarray.
   1536 -   **i**: `[in] int64_t` dimension index.
   1537 
   1538 ```c
   1539 int64_t stdlib_ndarray_stride( const struct ndarray *arr, const int64_t i );
   1540 ```
   1541 
   1542 Notes:
   1543 
   1544 -   the function does perform bounds checking for the dimension index.
   1545 
   1546 #### stdlib_ndarray_strides( *arr )
   1547 
   1548 Returns a pointer to an array containing ndarray strides (in bytes).
   1549 
   1550 ```c
   1551 #include "stdlib/ndarray/ctor.h"
   1552 #include <stdint.h>
   1553 #include <stdlib.h>
   1554 #include <stdio.h>
   1555 
   1556 // ...
   1557 
   1558 // Create an ndarray:
   1559 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1560 if ( x == NULL ) {
   1561     fprintf( stderr, "Error allocating memory.\n" );
   1562     exit( 1 );
   1563 }
   1564 
   1565 // ...
   1566 
   1567 // Retrieve the strides:
   1568 int64_t *strides = stdlib_ndarray_strides( x );
   1569 
   1570 // ...
   1571 
   1572 // Free allocated memory:
   1573 stdlib_ndarray_free( x );
   1574 ```
   1575 
   1576 The function accepts the following arguments:
   1577 
   1578 -   **arr**: `[in] struct ndarray*` input ndarray.
   1579 
   1580 ```c
   1581 int64_t * stdlib_ndarray_strides( const struct ndarray *arr );
   1582 ```
   1583 
   1584 #### stdlib_ndarray_submode( *arr, i )
   1585 
   1586 Returns an ndarray subscript mode.
   1587 
   1588 ```c
   1589 #include "stdlib/ndarray/ctor.h"
   1590 #include "stdlib/ndarray/index_modes.h"
   1591 #include <stdlib.h>
   1592 #include <stdio.h>
   1593 
   1594 // ...
   1595 
   1596 // Create an ndarray:
   1597 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1598 if ( x == NULL ) {
   1599     fprintf( stderr, "Error allocating memory.\n" );
   1600     exit( 1 );
   1601 }
   1602 
   1603 // ...
   1604 
   1605 // Retrieve an index mode:
   1606 enum STDLIB_NDARRAY_INDEX_MODE mode = stdlib_ndarray_submode( x, 0 );
   1607 
   1608 // ...
   1609 
   1610 // Free allocated memory:
   1611 stdlib_ndarray_free( x );
   1612 ```
   1613 
   1614 The function accepts the following arguments:
   1615 
   1616 -   **arr**: `[in] struct ndarray*` input ndarray.
   1617 -   **i**: `[in] int64_t` dimension index.
   1618 
   1619 ```c
   1620 int8_t stdlib_ndarray_submode( const struct ndarray *arr, const int64_t i );
   1621 ```
   1622 
   1623 Notes:
   1624 
   1625 -   If an ndarray has fewer subscript modes than dimensions, modes are recycled using modulo arithmetic.
   1626 -   The function does not perform bounds checking for the dimension index.
   1627 
   1628 #### stdlib_ndarray_submodes( *arr )
   1629 
   1630 Returns ndarray subscript modes.
   1631 
   1632 ```c
   1633 #include "stdlib/ndarray/ctor.h"
   1634 #include "stdlib/ndarray/index_modes.h"
   1635 #include <stdlib.h>
   1636 #include <stdio.h>
   1637 
   1638 // ...
   1639 
   1640 // Create an ndarray:
   1641 struct ndarray *x = stdlib_ndarray_allocate( ... );
   1642 if ( x == NULL ) {
   1643     fprintf( stderr, "Error allocating memory.\n" );
   1644     exit( 1 );
   1645 }
   1646 
   1647 // ...
   1648 
   1649 // Retrieve the index subscript modes:
   1650 int8_t *modes = stdlib_ndarray_submodes( x );
   1651 
   1652 // ...
   1653 
   1654 // Free allocated memory:
   1655 stdlib_ndarray_free( x );
   1656 ```
   1657 
   1658 The function accepts the following arguments:
   1659 
   1660 -   **arr**: `[in] struct ndarray*` input ndarray.
   1661 
   1662 ```c
   1663 int8_t * stdlib_ndarray_submodes( const struct ndarray *arr );
   1664 ```
   1665 
   1666 * * *
   1667 
   1668 #### stdlib_ndarray_get( \*arr, \*sub, \*out )
   1669 
   1670 Returns an ndarray data element.
   1671 
   1672 ```c
   1673 int8_t stdlib_ndarray_get( const struct ndarray *arr, const int64_t *sub, void *out );
   1674 ```
   1675 
   1676 The function accepts the following arguments:
   1677 
   1678 -   **arr**: `[in] struct ndarray *` input ndarray.
   1679 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1680 -   **out**: `[out] void *` output address.
   1681 
   1682 Notes:
   1683 
   1684 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1685 -   The function requires a `void` pointer for the output address `out` in order to provide a generic API supporting ndarrays having different data types.
   1686 
   1687 #### stdlib_ndarray_get_float64( \*arr, \*sub, \*out )
   1688 
   1689 Returns a double-precision floating-point ndarray data element.
   1690 
   1691 ```c
   1692 int8_t stdlib_ndarray_get_float64( const struct ndarray *arr, const int64_t *sub, double *out );
   1693 ```
   1694 
   1695 The function accepts the following arguments:
   1696 
   1697 -   **arr**: `[in] struct ndarray *` input ndarray.
   1698 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1699 -   **out**: `[out] double *` output address.
   1700 
   1701 Notes:
   1702 
   1703 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1704 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1705 
   1706 #### stdlib_ndarray_get_float32( \*arr, \*sub, \*out )
   1707 
   1708 Returns a single-precision floating-point ndarray data element.
   1709 
   1710 ```c
   1711 int8_t stdlib_ndarray_get_float32( const struct ndarray *arr, const int64_t *sub, float *out );
   1712 ```
   1713 
   1714 The function accepts the following arguments:
   1715 
   1716 -   **arr**: `[in] struct ndarray *` input ndarray.
   1717 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1718 -   **out**: `[out] float *` output address.
   1719 
   1720 Notes:
   1721 
   1722 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1723 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1724 
   1725 #### stdlib_ndarray_get_uint64( \*arr, \*sub, \*out )
   1726 
   1727 Returns an unsigned 64-bit integer ndarray data element.
   1728 
   1729 ```c
   1730 int8_t stdlib_ndarray_get_uint64( const struct ndarray *arr, const int64_t *sub, uint64_t *out );
   1731 ```
   1732 
   1733 The function accepts the following arguments:
   1734 
   1735 -   **arr**: `[in] struct ndarray *` input ndarray.
   1736 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1737 -   **out**: `[out] uint64_t *` output address.
   1738 
   1739 Notes:
   1740 
   1741 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1742 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1743 
   1744 #### stdlib_ndarray_get_int64( \*arr, \*sub, \*out )
   1745 
   1746 Returns a signed 64-bit integer ndarray data element.
   1747 
   1748 ```c
   1749 int8_t stdlib_ndarray_get_int64( const struct ndarray *arr, const int64_t *sub, int64_t *out );
   1750 ```
   1751 
   1752 The function accepts the following arguments:
   1753 
   1754 -   **arr**: `[in] struct ndarray *` input ndarray.
   1755 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1756 -   **out**: `[out] int64_t *` output address.
   1757 
   1758 Notes:
   1759 
   1760 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1761 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1762 
   1763 #### stdlib_ndarray_get_uint32( \*arr, \*sub, \*out )
   1764 
   1765 Returns an unsigned 32-bit integer ndarray data element.
   1766 
   1767 ```c
   1768 int8_t stdlib_ndarray_get_uint32( const struct ndarray *arr, const int64_t *sub, uint32_t *out );
   1769 ```
   1770 
   1771 The function accepts the following arguments:
   1772 
   1773 -   **arr**: `[in] struct ndarray *` input ndarray.
   1774 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1775 -   **out**: `[out] uint32_t *` output address.
   1776 
   1777 Notes:
   1778 
   1779 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1780 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1781 
   1782 #### stdlib_ndarray_get_int32( \*arr, \*sub, \*out )
   1783 
   1784 Returns a signed 32-bit integer ndarray data element.
   1785 
   1786 ```c
   1787 int8_t stdlib_ndarray_get_int32( const struct ndarray *arr, const int64_t *sub, int32_t *out );
   1788 ```
   1789 
   1790 The function accepts the following arguments:
   1791 
   1792 -   **arr**: `[in] struct ndarray *` input ndarray.
   1793 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1794 -   **out**: `[out] int32_t *` output address.
   1795 
   1796 Notes:
   1797 
   1798 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1799 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1800 
   1801 #### stdlib_ndarray_get_uint16( \*arr, \*sub, \*out )
   1802 
   1803 Returns an unsigned 16-bit integer ndarray data element.
   1804 
   1805 ```c
   1806 int8_t stdlib_ndarray_get_uint16( const struct ndarray *arr, const int64_t *sub, uint16_t *out );
   1807 ```
   1808 
   1809 The function accepts the following arguments:
   1810 
   1811 -   **arr**: `[in] struct ndarray *` input ndarray.
   1812 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1813 -   **out**: `[out] uint16_t *` output address.
   1814 
   1815 Notes:
   1816 
   1817 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1818 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1819 
   1820 #### stdlib_ndarray_get_int16( \*arr, \*sub, \*out )
   1821 
   1822 Returns a signed 16-bit integer ndarray data element.
   1823 
   1824 ```c
   1825 int8_t stdlib_ndarray_get_int16( const struct ndarray *arr, const int64_t *sub, int16_t *out );
   1826 ```
   1827 
   1828 The function accepts the following arguments:
   1829 
   1830 -   **arr**: `[in] struct ndarray *` input ndarray.
   1831 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1832 -   **out**: `[out] int16_t *` output address.
   1833 
   1834 Notes:
   1835 
   1836 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1837 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1838 
   1839 #### stdlib_ndarray_get_uint8( \*arr, \*sub, \*out )
   1840 
   1841 Returns an unsigned 8-bit integer ndarray data element.
   1842 
   1843 ```c
   1844 int8_t stdlib_ndarray_get_uint8( const struct ndarray *arr, const int64_t *sub, uint8_t *out );
   1845 ```
   1846 
   1847 The function accepts the following arguments:
   1848 
   1849 -   **arr**: `[in] struct ndarray *` input ndarray.
   1850 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1851 -   **out**: `[out] uint8_t *` output address.
   1852 
   1853 Notes:
   1854 
   1855 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1856 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1857 
   1858 #### stdlib_ndarray_get_int8( \*arr, \*sub, \*out )
   1859 
   1860 Returns a signed 8-bit integer ndarray data element.
   1861 
   1862 ```c
   1863 int8_t stdlib_ndarray_get_int8( const struct ndarray *arr, const int64_t *sub, int8_t *out );
   1864 ```
   1865 
   1866 The function accepts the following arguments:
   1867 
   1868 -   **arr**: `[in] struct ndarray *` input ndarray.
   1869 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1870 -   **out**: `[out] int8_t *` output address.
   1871 
   1872 Notes:
   1873 
   1874 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1875 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1876 
   1877 #### stdlib_ndarray_get_complex128( \*arr, \*sub, \*out )
   1878 
   1879 Returns a double-precision complex floating-point ndarray data element.
   1880 
   1881 ```c
   1882 int8_t stdlib_ndarray_get_complex128( const struct ndarray *arr, const int64_t *sub, double complex *out );
   1883 ```
   1884 
   1885 The function accepts the following arguments:
   1886 
   1887 -   **arr**: `[in] struct ndarray *` input ndarray.
   1888 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1889 -   **out**: `[out] double complex *` output address.
   1890 
   1891 Notes:
   1892 
   1893 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1894 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1895 
   1896 #### stdlib_ndarray_get_complex64( \*arr, \*sub, \*out )
   1897 
   1898 Returns a single-precision complex floating-point ndarray data element.
   1899 
   1900 ```c
   1901 int8_t stdlib_ndarray_get_complex64( const struct ndarray *arr, const int64_t *sub, float complex *out );
   1902 ```
   1903 
   1904 The function accepts the following arguments:
   1905 
   1906 -   **arr**: `[in] struct ndarray *` input ndarray.
   1907 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1908 -   **out**: `[out] float complex *` output address.
   1909 
   1910 Notes:
   1911 
   1912 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1913 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1914 
   1915 #### stdlib_ndarray_get_bool( \*arr, \*sub, \*out )
   1916 
   1917 Returns a boolean ndarray data element.
   1918 
   1919 ```c
   1920 int8_t stdlib_ndarray_get_bool( const struct ndarray *arr, const int64_t *sub, bool *out );
   1921 ```
   1922 
   1923 The function accepts the following arguments:
   1924 
   1925 -   **arr**: `[in] struct ndarray *` input ndarray.
   1926 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1927 -   **out**: `[out] bool *` output address.
   1928 
   1929 Notes:
   1930 
   1931 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1932 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   1933 
   1934 * * *
   1935 
   1936 #### stdlib_ndarray_get_ptr( \*arr, \*sub )
   1937 
   1938 Returns a pointer to an ndarray data element in the underlying byte array.
   1939 
   1940 ```c
   1941 uint8_t * stdlib_ndarray_get_ptr( const struct ndarray *arr, const int64_t *sub );
   1942 ```
   1943 
   1944 The function accepts the following arguments:
   1945 
   1946 -   **arr**: `[in] struct ndarray *` input ndarray.
   1947 -   **sub**: `[in] int64_t *` ndarray subscripts.
   1948 
   1949 #### stdlib_ndarray_get_ptr_value( \*arr, \*idx, \*out )
   1950 
   1951 Returns an ndarray data element specified by a byte array pointer.
   1952 
   1953 ```c
   1954 int8_t stdlib_ndarray_get_ptr_value( const struct ndarray *arr, const uint8_t *idx, void *out );
   1955 ```
   1956 
   1957 The function accepts the following arguments:
   1958 
   1959 -   **arr**: `[in] struct ndarray *` input ndarray.
   1960 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   1961 -   **out**: `[out] void *` output address.
   1962 
   1963 Notes:
   1964 
   1965 -   The function does **not** perform bounds checking and **assumes** you know what you are doing.
   1966 -   The function returns `-1` if unable to get an element and `0` otherwise.
   1967 -   The function requires a `void` pointer for the output address `out` in order to provide a generic API supporting ndarrays having different data types.
   1968 
   1969 #### stdlib_ndarray_get_ptr_float64( \*idx, \*out )
   1970 
   1971 Returns a double-precision floating-point ndarray data element specified by a byte array pointer.
   1972 
   1973 ```c
   1974 int8_t stdlib_ndarray_get_ptr_float64( const uint8_t *idx, double *out );
   1975 ```
   1976 
   1977 The function accepts the following arguments:
   1978 
   1979 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   1980 -   **out**: `[out] double *` output address.
   1981 
   1982 Notes:
   1983 
   1984 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   1985 -   The function always returns `0`.
   1986 
   1987 #### stdlib_ndarray_get_ptr_float32( \*idx, \*out )
   1988 
   1989 Returns a single-precision floating-point ndarray data element specified by a byte array pointer.
   1990 
   1991 ```c
   1992 int8_t stdlib_ndarray_get_ptr_float32( const uint8_t *idx, float *out );
   1993 ```
   1994 
   1995 The function accepts the following arguments:
   1996 
   1997 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   1998 -   **out**: `[out] float *` output address.
   1999 
   2000 Notes:
   2001 
   2002 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2003 -   The function always returns `0`.
   2004 
   2005 #### stdlib_ndarray_get_ptr_uint64( \*idx, \*out )
   2006 
   2007 Returns an unsigned 64-bit integer ndarray data element specified by a byte array pointer.
   2008 
   2009 ```c
   2010 int8_t stdlib_ndarray_get_ptr_uint64( const uint8_t *idx, uint64_t *out );
   2011 ```
   2012 
   2013 The function accepts the following arguments:
   2014 
   2015 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2016 -   **out**: `[out] uint64_t *` output address.
   2017 
   2018 Notes:
   2019 
   2020 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2021 -   The function always returns `0`.
   2022 
   2023 #### stdlib_ndarray_get_ptr_int64( \*idx, \*out )
   2024 
   2025 Returns a signed 64-bit integer ndarray data element specified by a byte array pointer.
   2026 
   2027 ```c
   2028 int8_t stdlib_ndarray_get_ptr_int64( const uint8_t *idx, int64_t *out );
   2029 ```
   2030 
   2031 The function accepts the following arguments:
   2032 
   2033 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2034 -   **out**: `[out] int64_t *` output address.
   2035 
   2036 Notes:
   2037 
   2038 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2039 -   The function always returns `0`.
   2040 
   2041 #### stdlib_ndarray_get_ptr_uint32( \*idx, \*out )
   2042 
   2043 Returns an unsigned 32-bit integer ndarray data element specified by a byte array pointer.
   2044 
   2045 ```c
   2046 int8_t stdlib_ndarray_get_ptr_uint32( const uint8_t *idx, uint32_t *out );
   2047 ```
   2048 
   2049 The function accepts the following arguments:
   2050 
   2051 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2052 -   **out**: `[out] uint32_t *` output address.
   2053 
   2054 Notes:
   2055 
   2056 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2057 -   The function always returns `0`.
   2058 
   2059 #### stdlib_ndarray_get_ptr_int32( \*idx, \*out )
   2060 
   2061 Returns a signed 32-bit integer ndarray data element specified by a byte array pointer.
   2062 
   2063 ```c
   2064 int8_t stdlib_ndarray_get_ptr_int32( const uint8_t *idx, int32_t *out );
   2065 ```
   2066 
   2067 The function accepts the following arguments:
   2068 
   2069 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2070 -   **out**: `[out] int32_t *` output address.
   2071 
   2072 Notes:
   2073 
   2074 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2075 -   The function always returns `0`.
   2076 
   2077 #### stdlib_ndarray_get_ptr_uint16( \*idx, \*out )
   2078 
   2079 Returns an unsigned 16-bit integer ndarray data element specified by a byte array pointer.
   2080 
   2081 ```c
   2082 int8_t stdlib_ndarray_get_ptr_uint16( const uint8_t *idx, uint16_t *out );
   2083 ```
   2084 
   2085 The function accepts the following arguments:
   2086 
   2087 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2088 -   **out**: `[out] uint16_t *` output address.
   2089 
   2090 Notes:
   2091 
   2092 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2093 -   The function always returns `0`.
   2094 
   2095 #### stdlib_ndarray_get_ptr_int16( \*idx, \*out )
   2096 
   2097 Returns a signed 16-bit integer ndarray data element specified by a byte array pointer.
   2098 
   2099 ```c
   2100 int8_t stdlib_ndarray_get_ptr_int16( const uint8_t *idx, int16_t *out );
   2101 ```
   2102 
   2103 The function accepts the following arguments:
   2104 
   2105 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2106 -   **out**: `[out] int16_t *` output address.
   2107 
   2108 Notes:
   2109 
   2110 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2111 -   The function always returns `0`.
   2112 
   2113 #### stdlib_ndarray_get_ptr_uint8( \*idx, \*out )
   2114 
   2115 Returns an unsigned 8-bit integer ndarray data element specified by a byte array pointer.
   2116 
   2117 ```c
   2118 int8_t stdlib_ndarray_get_ptr_uint8( const uint8_t *idx, uint8_t *out );
   2119 ```
   2120 
   2121 The function accepts the following arguments:
   2122 
   2123 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2124 -   **out**: `[out] uint8_t *` output address.
   2125 
   2126 Notes:
   2127 
   2128 -   The function always returns `0`.
   2129 
   2130 #### stdlib_ndarray_get_ptr_int8( \*idx, \*out )
   2131 
   2132 Returns a signed 8-bit integer ndarray data element specified by a byte array pointer.
   2133 
   2134 ```c
   2135 int8_t stdlib_ndarray_get_ptr_int8( const uint8_t *idx, int8_t *out );
   2136 ```
   2137 
   2138 The function accepts the following arguments:
   2139 
   2140 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2141 -   **out**: `[out] int8_t *` output address.
   2142 
   2143 Notes:
   2144 
   2145 -   The function always returns `0`.
   2146 
   2147 #### stdlib_ndarray_get_ptr_complex128( \*idx, \*out )
   2148 
   2149 Returns a double-precision complex floating-point ndarray data element specified by a byte array pointer.
   2150 
   2151 ```c
   2152 int8_t stdlib_ndarray_get_ptr_complex128( const uint8_t *idx, double complex *out );
   2153 ```
   2154 
   2155 The function accepts the following arguments:
   2156 
   2157 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2158 -   **out**: `[out] double complex *` output address.
   2159 
   2160 Notes:
   2161 
   2162 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2163 -   The function always returns `0`.
   2164 
   2165 #### stdlib_ndarray_get_ptr_complex64( \*idx, \*out )
   2166 
   2167 Returns a single-precision complex floating-point ndarray data element specified by a byte array pointer.
   2168 
   2169 ```c
   2170 int8_t stdlib_ndarray_get_ptr_complex64( const uint8_t *idx, float complex *out );
   2171 ```
   2172 
   2173 The function accepts the following arguments:
   2174 
   2175 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2176 -   **out**: `[out] float complex *` output address.
   2177 
   2178 Notes:
   2179 
   2180 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2181 -   The function always returns `0`.
   2182 
   2183 #### stdlib_ndarray_get_ptr_bool( \*idx, \*out )
   2184 
   2185 Returns a boolean ndarray data element specified by a byte array pointer.
   2186 
   2187 ```c
   2188 int8_t stdlib_ndarray_get_ptr_bool( const uint8_t *idx, bool *out );
   2189 ```
   2190 
   2191 The function accepts the following arguments:
   2192 
   2193 -   **idx**: `[in] uint8_t *` byte array pointer to an ndarray data element.
   2194 -   **out**: `[out] bool *` output address.
   2195 
   2196 Notes:
   2197 
   2198 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2199 -   The function always returns `0`.
   2200 
   2201 * * *
   2202 
   2203 #### stdlib_ndarray_iget( \*arr, idx, \*out )
   2204 
   2205 Returns an ndarray data element located at a specified linear index.
   2206 
   2207 ```c
   2208 int8_t stdlib_ndarray_iget( const struct ndarray *arr, const int64_t idx, void *out );
   2209 ```
   2210 
   2211 The function accepts the following arguments:
   2212 
   2213 -   **arr**: `[in] struct ndarray*` input ndarray.
   2214 -   **idx**: `[in] int64_t` linear view index.
   2215 -   **out**: `[out] void *` output address.
   2216 
   2217 Notes:
   2218 
   2219 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2220 -   The function requires a `void` pointer for the output address `out` in order to provide a generic API supporting ndarrays having different data types.
   2221 -   The function places the burden on the user to ensure that the output address is compatible with the data type of input ndarray data elements.
   2222 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2223 
   2224 #### stdlib_ndarray_iget_float64( \*arr, idx, \*out )
   2225 
   2226 Returns a double-precision floating-point ndarray data element located at a specified linear index.
   2227 
   2228 ```c
   2229 int8_t stdlib_ndarray_iget_float64( const struct ndarray *arr, const int64_t idx, double *out );
   2230 ```
   2231 
   2232 The function accepts the following arguments:
   2233 
   2234 -   **arr**: `[in] struct ndarray*` input ndarray.
   2235 -   **idx**: `[in] int64_t` linear view index.
   2236 -   **out**: `[out] double *` output address.
   2237 
   2238 Notes:
   2239 
   2240 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2241 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2242 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2243 
   2244 #### stdlib_ndarray_iget_float32( \*arr, idx, \*out )
   2245 
   2246 Returns a single-precision floating-point ndarray data element located at a specified linear index.
   2247 
   2248 ```c
   2249 int8_t stdlib_ndarray_iget_float32( const struct ndarray *arr, const int64_t idx, float *out );
   2250 ```
   2251 
   2252 The function accepts the following arguments:
   2253 
   2254 -   **arr**: `[in] struct ndarray*` input ndarray.
   2255 -   **idx**: `[in] int64_t` linear view index.
   2256 -   **out**: `[out] float *` output address.
   2257 
   2258 Notes:
   2259 
   2260 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2261 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2262 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2263 
   2264 #### stdlib_ndarray_iget_uint64( \*arr, idx, \*out )
   2265 
   2266 Returns an unsigned 64-bit integer ndarray data element located at a specified linear index.
   2267 
   2268 ```c
   2269 int8_t stdlib_ndarray_iget_uint64( const struct ndarray *arr, const int64_t idx, uint64_t *out );
   2270 ```
   2271 
   2272 The function accepts the following arguments:
   2273 
   2274 -   **arr**: `[in] struct ndarray*` input ndarray.
   2275 -   **idx**: `[in] int64_t` linear view index.
   2276 -   **out**: `[out] uint64_t *` output address.
   2277 
   2278 Notes:
   2279 
   2280 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2281 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2282 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2283 
   2284 #### stdlib_ndarray_iget_int64( \*arr, idx, \*out )
   2285 
   2286 Returns a signed 64-bit integer ndarray data element located at a specified linear index.
   2287 
   2288 ```c
   2289 int8_t stdlib_ndarray_iget_int64( const struct ndarray *arr, const int64_t idx, int64_t *out );
   2290 ```
   2291 
   2292 The function accepts the following arguments:
   2293 
   2294 -   **arr**: `[in] struct ndarray*` input ndarray.
   2295 -   **idx**: `[in] int64_t` linear view index.
   2296 -   **out**: `[out] int64_t *` output address.
   2297 
   2298 Notes:
   2299 
   2300 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2301 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2302 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2303 
   2304 #### stdlib_ndarray_iget_uint32( \*arr, idx, \*out )
   2305 
   2306 Returns an unsigned 32-bit integer ndarray data element located at a specified linear index.
   2307 
   2308 ```c
   2309 int8_t stdlib_ndarray_iget_uint32( const struct ndarray *arr, const int64_t idx, uint32_t *out );
   2310 ```
   2311 
   2312 The function accepts the following arguments:
   2313 
   2314 -   **arr**: `[in] struct ndarray*` input ndarray.
   2315 -   **idx**: `[in] int64_t` linear view index.
   2316 -   **out**: `[out] uint32_t *` output address.
   2317 
   2318 Notes:
   2319 
   2320 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2321 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2322 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2323 
   2324 #### stdlib_ndarray_iget_int32( \*arr, idx, \*out )
   2325 
   2326 Returns a signed 32-bit integer ndarray data element located at a specified linear index.
   2327 
   2328 ```c
   2329 int8_t stdlib_ndarray_iget_int32( const struct ndarray *arr, const int64_t idx, int32_t *out );
   2330 ```
   2331 
   2332 The function accepts the following arguments:
   2333 
   2334 -   **arr**: `[in] struct ndarray*` input ndarray.
   2335 -   **idx**: `[in] int64_t` linear view index.
   2336 -   **out**: `[out] int32_t *` output address.
   2337 
   2338 Notes:
   2339 
   2340 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2341 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2342 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2343 
   2344 #### stdlib_ndarray_iget_uint16( \*arr, idx, \*out )
   2345 
   2346 Returns an unsigned 16-bit integer ndarray data element located at a specified linear index.
   2347 
   2348 ```c
   2349 int8_t stdlib_ndarray_iget_uint16( const struct ndarray *arr, const int64_t idx, uint16_t *out );
   2350 ```
   2351 
   2352 The function accepts the following arguments:
   2353 
   2354 -   **arr**: `[in] struct ndarray*` input ndarray.
   2355 -   **idx**: `[in] int64_t` linear view index.
   2356 -   **out**: `[out] uint16_t *` output address.
   2357 
   2358 Notes:
   2359 
   2360 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2361 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2362 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2363 
   2364 #### stdlib_ndarray_iget_int16( \*arr, idx, \*out )
   2365 
   2366 Returns a signed 16-bit integer ndarray data element located at a specified linear index.
   2367 
   2368 ```c
   2369 int8_t stdlib_ndarray_iget_int16( const struct ndarray *arr, const int64_t idx, int16_t *out );
   2370 ```
   2371 
   2372 The function accepts the following arguments:
   2373 
   2374 -   **arr**: `[in] struct ndarray*` input ndarray.
   2375 -   **idx**: `[in] int64_t` linear view index.
   2376 -   **out**: `[out] int16_t *` output address.
   2377 
   2378 Notes:
   2379 
   2380 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2381 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2382 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2383 
   2384 #### stdlib_ndarray_iget_uint8( \*arr, idx, \*out )
   2385 
   2386 Returns an unsigned 8-bit integer ndarray data element located at a specified linear index.
   2387 
   2388 ```c
   2389 int8_t stdlib_ndarray_iget_uint8( const struct ndarray *arr, const int64_t idx, uint8_t *out );
   2390 ```
   2391 
   2392 The function accepts the following arguments:
   2393 
   2394 -   **arr**: `[in] struct ndarray*` input ndarray.
   2395 -   **idx**: `[in] int64_t` linear view index.
   2396 -   **out**: `[out] uint8_t *` output address.
   2397 
   2398 Notes:
   2399 
   2400 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2401 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2402 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2403 
   2404 #### stdlib_ndarray_iget_int8( \*arr, idx, \*out )
   2405 
   2406 Returns a signed 8-bit integer ndarray data element located at a specified linear index.
   2407 
   2408 ```c
   2409 int8_t stdlib_ndarray_iget_int8( const struct ndarray *arr, const int64_t idx, int8_t *out );
   2410 ```
   2411 
   2412 The function accepts the following arguments:
   2413 
   2414 -   **arr**: `[in] struct ndarray*` input ndarray.
   2415 -   **idx**: `[in] int64_t` linear view index.
   2416 -   **out**: `[out] int8_t *` output address.
   2417 
   2418 Notes:
   2419 
   2420 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2421 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2422 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2423 
   2424 #### stdlib_ndarray_iget_complex128( \*arr, idx, \*out )
   2425 
   2426 Returns a double-precision complex floating-point ndarray data element located at a specified linear index.
   2427 
   2428 ```c
   2429 int8_t stdlib_ndarray_iget_complex128( const struct ndarray *arr, const int64_t idx, double complex *out );
   2430 ```
   2431 
   2432 The function accepts the following arguments:
   2433 
   2434 -   **arr**: `[in] struct ndarray*` input ndarray.
   2435 -   **idx**: `[in] int64_t` linear view index.
   2436 -   **out**: `[out] double complex *` output address.
   2437 
   2438 Notes:
   2439 
   2440 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2441 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2442 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2443 
   2444 #### stdlib_ndarray_iget_complex64( \*arr, idx, \*out )
   2445 
   2446 Returns a single-precision complex floating-point ndarray data element located at a specified linear index.
   2447 
   2448 ```c
   2449 int8_t stdlib_ndarray_iget_complex64( const struct ndarray *arr, const int64_t idx, float complex *out );
   2450 ```
   2451 
   2452 The function accepts the following arguments:
   2453 
   2454 -   **arr**: `[in] struct ndarray*` input ndarray.
   2455 -   **idx**: `[in] int64_t` linear view index.
   2456 -   **out**: `[out] float complex *` output address.
   2457 
   2458 Notes:
   2459 
   2460 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2461 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2462 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2463 
   2464 #### stdlib_ndarray_iget_bool( \*arr, idx, \*out )
   2465 
   2466 Returns a boolean ndarray data element located at a specified linear index.
   2467 
   2468 ```c
   2469 int8_t stdlib_ndarray_iget_bool( const struct ndarray *arr, const int64_t idx, bool *out );
   2470 ```
   2471 
   2472 The function accepts the following arguments:
   2473 
   2474 -   **arr**: `[in] struct ndarray*` input ndarray.
   2475 -   **idx**: `[in] int64_t` linear view index.
   2476 -   **out**: `[out] bool *` output address.
   2477 
   2478 Notes:
   2479 
   2480 -   The function does **not** verify that the output address type matches the underlying input ndarray data type and **assumes** that you know what you are doing.
   2481 -   The function returns `-1` if unable to get an element and `0` otherwise.
   2482 -   For zero-dimensional arrays, the function returns the first (and only) indexed element, regardless of the value of `idx`.
   2483 
   2484 * * *
   2485 
   2486 #### stdlib_ndarray_iget_ptr( \*arr, idx )
   2487 
   2488 Returns a pointer in the underlying byte array for an ndarray data element located at a specified linear index.
   2489 
   2490 ```c
   2491 uint8_t * stdlib_ndarray_iget_ptr( const struct ndarray *arr, const int64_t idx );
   2492 ```
   2493 
   2494 The function accepts the following arguments:
   2495 
   2496 -   **arr**: `[in] struct ndarray*` input ndarray.
   2497 -   **idx**: `[in] int64_t` linear view index.
   2498    
   2499 For zero-dimensional arrays, the function returns a pointer to the first (and only) indexed element, regardless of the value of `idx`.
   2500 
   2501 * * *
   2502 
   2503 #### stdlib_ndarray_iset( \*arr, idx, \*v )
   2504 
   2505 Sets an ndarray data element located at a specified linear index.
   2506 
   2507 ```c
   2508 int8_t stdlib_ndarray_iset( const struct ndarray *arr, const int64_t idx, const void *v );
   2509 ```
   2510 
   2511 The function accepts the following arguments:
   2512 
   2513 -   **arr**: `[in] struct ndarray*` input ndarray.
   2514 -   **idx**: `[in] int64_t` linear view index.
   2515 -   **v**: `[in] void*` value to set.
   2516 
   2517 Notes:
   2518 
   2519 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2520 -   The function requires a pointer to a data value `v` in order to provide a generic API supporting ndarrays having different data types.
   2521 -   The function has no way of determining whether `v` actually points to a memory address compatible with the underlying input ndarray data type. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2522 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2523 
   2524 #### stdlib_ndarray_iset_float64( \*arr, idx, v )
   2525 
   2526 Sets a double-precision floating-point ndarray data element located at a specified linear index.
   2527 
   2528 ```c
   2529 int8_t stdlib_ndarray_iset_float64( const struct ndarray *arr, const int64_t idx, const double v );
   2530 ```
   2531 
   2532 The function accepts the following arguments:
   2533 
   2534 -   **arr**: `[in] struct ndarray*` input ndarray.
   2535 -   **idx**: `[in] int64_t` linear view index.
   2536 -   **v**: `[in] double` value to set.
   2537 
   2538 Notes:
   2539 
   2540 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2541 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2542 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2543 
   2544 #### stdlib_ndarray_iset_float32( \*arr, idx, v )
   2545 
   2546 Sets a single-precision floating-point ndarray data element located at a specified linear index.
   2547 
   2548 ```c
   2549 int8_t stdlib_ndarray_iset_float32( const struct ndarray *arr, const int64_t idx, const float v );
   2550 ```
   2551 
   2552 The function accepts the following arguments:
   2553 
   2554 -   **arr**: `[in] struct ndarray*` input ndarray.
   2555 -   **idx**: `[in] int64_t` linear view index.
   2556 -   **v**: `[in] float` value to set.
   2557 
   2558 Notes:
   2559 
   2560 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2561 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2562 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2563 
   2564 #### stdlib_ndarray_iset_uint64( \*arr, idx, v )
   2565 
   2566 Sets an unsigned 64-bit integer ndarray data element located at a specified linear index.
   2567 
   2568 ```c
   2569 int8_t stdlib_ndarray_iset_uint64( const struct ndarray *arr, const int64_t idx, const uint64_t v );
   2570 ```
   2571 
   2572 The function accepts the following arguments:
   2573 
   2574 -   **arr**: `[in] struct ndarray*` input ndarray.
   2575 -   **idx**: `[in] int64_t` linear view index.
   2576 -   **v**: `[in] uint64_t` value to set.
   2577 
   2578 Notes:
   2579 
   2580 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2581 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2582 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2583 
   2584 #### stdlib_ndarray_iset_int64( \*arr, idx, v )
   2585 
   2586 Sets a signed 64-bit integer ndarray data element located at a specified linear index.
   2587 
   2588 ```c
   2589 int8_t stdlib_ndarray_iset_int64( const struct ndarray *arr, const int64_t idx, const int64_t v );
   2590 ```
   2591 
   2592 The function accepts the following arguments:
   2593 
   2594 -   **arr**: `[in] struct ndarray*` input ndarray.
   2595 -   **idx**: `[in] int64_t` linear view index.
   2596 -   **v**: `[in] int64_t` value to set.
   2597 
   2598 Notes:
   2599 
   2600 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2601 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2602 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2603 
   2604 #### stdlib_ndarray_iset_uint32( \*arr, idx, v )
   2605 
   2606 Sets an unsigned 32-bit integer ndarray data element located at a specified linear index.
   2607 
   2608 ```c
   2609 int8_t stdlib_ndarray_iset_uint32( const struct ndarray *arr, const int64_t idx, const uint32_t v );
   2610 ```
   2611 
   2612 The function accepts the following arguments:
   2613 
   2614 -   **arr**: `[in] struct ndarray*` input ndarray.
   2615 -   **idx**: `[in] int64_t` linear view index.
   2616 -   **v**: `[in] uint32_t` value to set.
   2617 
   2618 Notes:
   2619 
   2620 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2621 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2622 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2623 
   2624 #### stdlib_ndarray_iset_int32( \*arr, idx, v )
   2625 
   2626 Sets a signed 32-bit integer ndarray data element located at a specified linear index.
   2627 
   2628 ```c
   2629 int8_t stdlib_ndarray_iset_int32( const struct ndarray *arr, const int64_t idx, const int32_t v );
   2630 ```
   2631 
   2632 The function accepts the following arguments:
   2633 
   2634 -   **arr**: `[in] struct ndarray*` input ndarray.
   2635 -   **idx**: `[in] int64_t` linear view index.
   2636 -   **v**: `[in] int32_t` value to set.
   2637 
   2638 Notes:
   2639 
   2640 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2641 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2642 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2643 
   2644 #### stdlib_ndarray_iset_uint16( \*arr, idx, v )
   2645 
   2646 Sets an unsigned 16-bit integer ndarray data element located at a specified linear index.
   2647 
   2648 ```c
   2649 int8_t stdlib_ndarray_iset_uint16( const struct ndarray *arr, const int64_t idx, const uint16_t v );
   2650 ```
   2651 
   2652 The function accepts the following arguments:
   2653 
   2654 -   **arr**: `[in] struct ndarray*` input ndarray.
   2655 -   **idx**: `[in] int64_t` linear view index.
   2656 -   **v**: `[in] uint16_t` value to set.
   2657 
   2658 Notes:
   2659 
   2660 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2661 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2662 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2663 
   2664 #### stdlib_ndarray_iset_int16( \*arr, idx, v )
   2665 
   2666 Sets a signed 16-bit integer ndarray data element located at a specified linear index.
   2667 
   2668 ```c
   2669 int8_t stdlib_ndarray_iset_int16( const struct ndarray *arr, const int64_t idx, const int16_t v );
   2670 ```
   2671 
   2672 The function accepts the following arguments:
   2673 
   2674 -   **arr**: `[in] struct ndarray*` input ndarray.
   2675 -   **idx**: `[in] int64_t` linear view index.
   2676 -   **v**: `[in] int16_t` value to set.
   2677 
   2678 Notes:
   2679 
   2680 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2681 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2682 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2683 
   2684 #### stdlib_ndarray_iset_uint8( \*arr, idx, v )
   2685 
   2686 Sets an unsigned 8-bit integer ndarray data element located at a specified linear index.
   2687 
   2688 ```c
   2689 int8_t stdlib_ndarray_iset_uint8( const struct ndarray *arr, const int64_t idx, const uint8_t v );
   2690 ```
   2691 
   2692 The function accepts the following arguments:
   2693 
   2694 -   **arr**: `[in] struct ndarray*` input ndarray.
   2695 -   **idx**: `[in] int64_t` linear view index.
   2696 -   **v**: `[in] uint8_t` value to set.
   2697 
   2698 Notes:
   2699 
   2700 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2701 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2702 
   2703 #### stdlib_ndarray_iset_int8( \*arr, idx, v )
   2704 
   2705 Sets a signed 8-bit integer ndarray data element located at a specified linear index.
   2706 
   2707 ```c
   2708 int8_t stdlib_ndarray_iset_int8( const struct ndarray *arr, const int64_t idx, const int8_t v );
   2709 ```
   2710 
   2711 The function accepts the following arguments:
   2712 
   2713 -   **arr**: `[in] struct ndarray*` input ndarray.
   2714 -   **idx**: `[in] int64_t` linear view index.
   2715 -   **v**: `[in] int8_t` value to set.
   2716 
   2717 Notes:
   2718 
   2719 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2720 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2721 
   2722 #### stdlib_ndarray_iset_complex128( \*arr, idx, v )
   2723 
   2724 Sets a double-precision complex floating-point ndarray data element located at a specified linear index.
   2725 
   2726 ```c
   2727 int8_t stdlib_ndarray_iset_complex128( const struct ndarray *arr, const int64_t idx, const double complex v );
   2728 ```
   2729 
   2730 The function accepts the following arguments:
   2731 
   2732 -   **arr**: `[in] struct ndarray*` input ndarray.
   2733 -   **idx**: `[in] int64_t` linear view index.
   2734 -   **v**: `[in] double complex` value to set.
   2735 
   2736 Notes:
   2737 
   2738 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2739 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2740 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2741 
   2742 #### stdlib_ndarray_iset_complex64( \*arr, idx, v )
   2743 
   2744 Sets a single-precision complex floating-point ndarray data element located at a specified linear index.
   2745 
   2746 ```c
   2747 int8_t stdlib_ndarray_iset_complex64( const struct ndarray *arr, const int64_t idx, const float complex v );
   2748 ```
   2749 
   2750 The function accepts the following arguments:
   2751 
   2752 -   **arr**: `[in] struct ndarray*` input ndarray.
   2753 -   **idx**: `[in] int64_t` linear view index.
   2754 -   **v**: `[in] float complex` value to set.
   2755 
   2756 Notes:
   2757 
   2758 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2759 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2760 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2761 
   2762 #### stdlib_ndarray_iset_bool( \*arr, idx, v )
   2763 
   2764 Sets a boolean ndarray data element located at a specified linear index.
   2765 
   2766 ```c
   2767 int8_t stdlib_ndarray_iset_bool( const struct ndarray *arr, const int64_t idx, const bool v );
   2768 ```
   2769 
   2770 The function accepts the following arguments:
   2771 
   2772 -   **arr**: `[in] struct ndarray*` input ndarray.
   2773 -   **idx**: `[in] int64_t` linear view index.
   2774 -   **v**: `[in] bool` value to set.
   2775 
   2776 Notes:
   2777 
   2778 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2779 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2780 -   For zero-dimensional arrays, the function sets the first (and only) indexed element, regardless of the value of `idx`.
   2781 
   2782 * * *
   2783 
   2784 #### stdlib_ndarray_set( \*arr, \*sub, \*v )
   2785 
   2786 Sets an ndarray data element.
   2787 
   2788 ```c
   2789 int8_t stdlib_ndarray_set( const struct ndarray *arr, const int64_t *sub, const void *v );
   2790 ```
   2791 
   2792 The function accepts the following arguments:
   2793 
   2794 -   **arr**: `[in] struct ndarray*` input ndarray.
   2795 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2796 -   **v**: `[in] void*` value to set.
   2797 
   2798 Notes
   2799 
   2800 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2801 -   The function requires a pointer to a data value `v` in order to provide a generic API supporting ndarrays having different data types.
   2802 -   The function has no way of determining whether `v` actually points to a memory address compatible with the underlying input ndarray data type. Accordingly, accessing **unowned** memory is possible, and this function **assumes** you know what you are doing.
   2803 
   2804 #### stdlib_ndarray_set_float64( \*arr, \*sub, v )
   2805 
   2806 Sets a double-precision floating-point ndarray data element.
   2807 
   2808 ```c
   2809 int8_t stdlib_ndarray_set_float64( const struct ndarray *arr, const int64_t *sub, const double v );
   2810 ```
   2811 
   2812 The function accepts the following arguments:
   2813 
   2814 -   **arr**: `[in] struct ndarray*` input ndarray.
   2815 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2816 -   **v**: `[in] double` value to set.
   2817 
   2818 Notes
   2819 
   2820 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2821 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2822 
   2823 #### stdlib_ndarray_set_float32( \*arr, \*sub, v )
   2824 
   2825 Sets a single-precision floating-point ndarray data element.
   2826 
   2827 ```c
   2828 int8_t stdlib_ndarray_set_float32( const struct ndarray *arr, const int64_t *sub, const float v );
   2829 ```
   2830 
   2831 The function accepts the following arguments:
   2832 
   2833 -   **arr**: `[in] struct ndarray*` input ndarray.
   2834 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2835 -   **v**: `[in] float` value to set.
   2836 
   2837 Notes
   2838 
   2839 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2840 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2841 
   2842 #### stdlib_ndarray_set_uint64( \*arr, \*sub, v )
   2843 
   2844 Sets an unsigned 64-bit integer ndarray data element.
   2845 
   2846 ```c
   2847 int8_t stdlib_ndarray_set_uint64( const struct ndarray *arr, const int64_t *sub, const uint64_t v );
   2848 ```
   2849 
   2850 The function accepts the following arguments:
   2851 
   2852 -   **arr**: `[in] struct ndarray*` input ndarray.
   2853 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2854 -   **v**: `[in] uint64_t` value to set.
   2855 
   2856 Notes
   2857 
   2858 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2859 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2860 
   2861 #### stdlib_ndarray_set_int64( \*arr, \*sub, v )
   2862 
   2863 Sets a signed 64-bit integer ndarray data element.
   2864 
   2865 ```c
   2866 int8_t stdlib_ndarray_set_int64( const struct ndarray *arr, const int64_t *sub, const int64_t v );
   2867 ```
   2868 
   2869 The function accepts the following arguments:
   2870 
   2871 -   **arr**: `[in] struct ndarray*` input ndarray.
   2872 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2873 -   **v**: `[in] int64_t` value to set.
   2874 
   2875 Notes
   2876 
   2877 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2878 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2879 
   2880 #### stdlib_ndarray_set_uint32( \*arr, \*sub, v )
   2881 
   2882 Sets an unsigned 32-bit integer ndarray data element.
   2883 
   2884 ```c
   2885 int8_t stdlib_ndarray_set_uint32( const struct ndarray *arr, const int64_t *sub, const uint32_t v );
   2886 ```
   2887 
   2888 The function accepts the following arguments:
   2889 
   2890 -   **arr**: `[in] struct ndarray*` input ndarray.
   2891 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2892 -   **v**: `[in] uint32_t` value to set.
   2893 
   2894 Notes
   2895 
   2896 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2897 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2898 
   2899 #### stdlib_ndarray_set_int32( \*arr, \*sub, v )
   2900 
   2901 Sets a signed 32-bit integer ndarray data element.
   2902 
   2903 ```c
   2904 int8_t stdlib_ndarray_set_int32( const struct ndarray *arr, const int64_t *sub, const int32_t v );
   2905 ```
   2906 
   2907 The function accepts the following arguments:
   2908 
   2909 -   **arr**: `[in] struct ndarray*` input ndarray.
   2910 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2911 -   **v**: `[in] int32_t` value to set.
   2912 
   2913 Notes
   2914 
   2915 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2916 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2917 
   2918 #### stdlib_ndarray_set_uint16( \*arr, \*sub, v )
   2919 
   2920 Sets an unsigned 16-bit integer ndarray data element.
   2921 
   2922 ```c
   2923 int8_t stdlib_ndarray_set_uint16( const struct ndarray *arr, const int64_t *sub, const uint16_t v );
   2924 ```
   2925 
   2926 The function accepts the following arguments:
   2927 
   2928 -   **arr**: `[in] struct ndarray*` input ndarray.
   2929 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2930 -   **v**: `[in] uint16_t` value to set.
   2931 
   2932 Notes
   2933 
   2934 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2935 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2936 
   2937 #### stdlib_ndarray_set_int16( \*arr, \*sub, v )
   2938 
   2939 Sets a signed 16-bit integer ndarray data element.
   2940 
   2941 ```c
   2942 int8_t stdlib_ndarray_set_int16( const struct ndarray *arr, const int64_t *sub, const int16_t v );
   2943 ```
   2944 
   2945 The function accepts the following arguments:
   2946 
   2947 -   **arr**: `[in] struct ndarray*` input ndarray.
   2948 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2949 -   **v**: `[in] int16_t` value to set.
   2950 
   2951 Notes
   2952 
   2953 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   2954 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2955 
   2956 #### stdlib_ndarray_set_uint8( \*arr, \*sub, v )
   2957 
   2958 Sets an unsigned 8-bit integer ndarray data element.
   2959 
   2960 ```c
   2961 int8_t stdlib_ndarray_set_uint8( const struct ndarray *arr, const int64_t *sub, const uint8_t v );
   2962 ```
   2963 
   2964 The function accepts the following arguments:
   2965 
   2966 -   **arr**: `[in] struct ndarray*` input ndarray.
   2967 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2968 -   **v**: `[in] uint8_t` value to set.
   2969 
   2970 Notes
   2971 
   2972 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2973 
   2974 #### stdlib_ndarray_set_int8( \*arr, \*sub, v )
   2975 
   2976 Sets a signed 8-bit integer ndarray data element.
   2977 
   2978 ```c
   2979 int8_t stdlib_ndarray_set_int8( const struct ndarray *arr, const int64_t *sub, const int8_t v );
   2980 ```
   2981 
   2982 The function accepts the following arguments:
   2983 
   2984 -   **arr**: `[in] struct ndarray*` input ndarray.
   2985 -   **sub**: `[in] int64_t*` ndarray subscripts.
   2986 -   **v**: `[in] int8_t` value to set.
   2987 
   2988 Notes
   2989 
   2990 -   The function returns `-1` if unable to set an element and `0` otherwise.
   2991 
   2992 #### stdlib_ndarray_set_complex128( \*arr, \*sub, v )
   2993 
   2994 Sets a double-precision complex floating-point ndarray data element.
   2995 
   2996 ```c
   2997 int8_t stdlib_ndarray_set_complex128( const struct ndarray *arr, const int64_t *sub, const double complex v );
   2998 ```
   2999 
   3000 The function accepts the following arguments:
   3001 
   3002 -   **arr**: `[in] struct ndarray*` input ndarray.
   3003 -   **sub**: `[in] int64_t*` ndarray subscripts.
   3004 -   **v**: `[in] double complex` value to set.
   3005 
   3006 Notes
   3007 
   3008 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   3009 -   The function returns `-1` if unable to set an element and `0` otherwise.
   3010 
   3011 #### stdlib_ndarray_set_complex64( \*arr, \*sub, v )
   3012 
   3013 Sets a single-precision complex floating-point ndarray data element.
   3014 
   3015 ```c
   3016 int8_t stdlib_ndarray_set_complex64( const struct ndarray *arr, const int64_t *sub, const float complex v );
   3017 ```
   3018 
   3019 The function accepts the following arguments:
   3020 
   3021 -   **arr**: `[in] struct ndarray*` input ndarray.
   3022 -   **sub**: `[in] int64_t*` ndarray subscripts.
   3023 -   **v**: `[in] float complex` value to set.
   3024 
   3025 Notes
   3026 
   3027 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   3028 -   The function returns `-1` if unable to set an element and `0` otherwise.
   3029 
   3030 #### stdlib_ndarray_set_bool( \*arr, \*sub, v )
   3031 
   3032 Sets a boolean ndarray data element.
   3033 
   3034 ```c
   3035 int8_t stdlib_ndarray_set_bool( const struct ndarray *arr, const int64_t *sub, const bool v );
   3036 ```
   3037 
   3038 The function accepts the following arguments:
   3039 
   3040 -   **arr**: `[in] struct ndarray*` input ndarray.
   3041 -   **sub**: `[in] int64_t*` ndarray subscripts.
   3042 -   **v**: `[in] bool` value to set.
   3043 
   3044 Notes
   3045 
   3046 -   The function does **not** verify that the type of `v` matches the underlying input ndarray data type, and, thus, overwriting **unowned** memory is possible. The function **assumes** that you know what you are doing.
   3047 -   The function returns `-1` if unable to set an element and `0` otherwise.
   3048 
   3049 * * *
   3050 
   3051 #### stdlib_ndarray_set_ptr_value( \*arr, \*idx, \*v )
   3052 
   3053 Sets an ndarray data element specified by a byte array pointer.
   3054 
   3055 ```c
   3056 int8_t stdlib_ndarray_set_ptr_value( const struct ndarray *arr, uint8_t *idx, const void *v );
   3057 ```
   3058 
   3059 The function accepts the following arguments:
   3060 
   3061 -   **arr**: `[in] struct ndarray*` input ndarray.
   3062 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3063 -   **v**: `[in] void*` value to set.
   3064 
   3065 Notes:
   3066 
   3067 -   The function does **not** perform bounds checking, and, thus, the function does **not** prevent you from overwriting **unowned** memory. Accordingly, the function **assumes** you know what you are doing.
   3068 -   The function returns `-1` if unable to set an element and `0` otherwise.
   3069 -   The function requires a pointer to a data value `v` in order to provide a generic API supporting ndarrays having different data types.
   3070 
   3071 #### stdlib_ndarray_set_ptr_float64( \*idx, v )
   3072 
   3073 Sets a double-precision floating-point ndarray data element specified by a byte array pointer.
   3074 
   3075 ```c
   3076 int8_t stdlib_ndarray_set_ptr_float64( uint8_t *idx, const double v );
   3077 ```
   3078 
   3079 The function accepts the following arguments:
   3080 
   3081 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3082 -   **v**: `[in] double` value to set.
   3083 
   3084 Notes:
   3085 
   3086 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3087 -   The function always returns `0`.
   3088 
   3089 #### stdlib_ndarray_set_ptr_float32( \*idx, v )
   3090 
   3091 Sets a single-precision floating-point ndarray data element specified by a byte array pointer.
   3092 
   3093 ```c
   3094 int8_t stdlib_ndarray_set_ptr_float32( uint8_t *idx, const float v );
   3095 ```
   3096 
   3097 The function accepts the following arguments:
   3098 
   3099 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3100 -   **v**: `[in] float` value to set.
   3101 
   3102 Notes:
   3103 
   3104 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3105 -   The function always returns `0`.
   3106 
   3107 #### stdlib_ndarray_set_ptr_uint64( \*idx, v )
   3108 
   3109 Sets an unsigned 64-bit integer ndarray data element specified by a byte array pointer.
   3110 
   3111 ```c
   3112 int8_t stdlib_ndarray_set_ptr_uint64( uint8_t *idx, const uint64_t v );
   3113 ```
   3114 
   3115 The function accepts the following arguments:
   3116 
   3117 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3118 -   **v**: `[in] uint64_t` value to set.
   3119 
   3120 Notes:
   3121 
   3122 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3123 -   The function always returns `0`.
   3124 
   3125 #### stdlib_ndarray_set_ptr_int64( \*idx, v )
   3126 
   3127 Sets a signed 64-bit integer ndarray data element specified by a byte array pointer.
   3128 
   3129 ```c
   3130 int8_t stdlib_ndarray_set_ptr_int64( uint8_t *idx, const int64_t v );
   3131 ```
   3132 
   3133 The function accepts the following arguments:
   3134 
   3135 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3136 -   **v**: `[in] int64_t` value to set.
   3137 
   3138 Notes:
   3139 
   3140 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3141 -   The function always returns `0`.
   3142 
   3143 #### stdlib_ndarray_set_ptr_uint32( \*idx, v )
   3144 
   3145 Sets an unsigned 32-bit integer ndarray data element specified by a byte array pointer.
   3146 
   3147 ```c
   3148 int8_t stdlib_ndarray_set_ptr_uint32( uint8_t *idx, const uint32_t v );
   3149 ```
   3150 
   3151 The function accepts the following arguments:
   3152 
   3153 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3154 -   **v**: `[in] uint32_t` value to set.
   3155 
   3156 Notes:
   3157 
   3158 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3159 -   The function always returns `0`.
   3160 
   3161 #### stdlib_ndarray_set_ptr_int32( \*idx, v )
   3162 
   3163 Sets a signed 32-bit integer ndarray data element specified by a byte array pointer.
   3164 
   3165 ```c
   3166 int8_t stdlib_ndarray_set_ptr_int32( uint8_t *idx, const int32_t v );
   3167 ```
   3168 
   3169 The function accepts the following arguments:
   3170 
   3171 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3172 -   **v**: `[in] int32_t` value to set.
   3173 
   3174 Notes:
   3175 
   3176 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3177 -   The function always returns `0`.
   3178 
   3179 #### stdlib_ndarray_set_ptr_uint16( \*idx, v )
   3180 
   3181 Sets an unsigned 16-bit integer ndarray data element specified by a byte array pointer.
   3182 
   3183 ```c
   3184 int8_t stdlib_ndarray_set_ptr_uint16( uint8_t *idx, const uint16_t v );
   3185 ```
   3186 
   3187 The function accepts the following arguments:
   3188 
   3189 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3190 -   **v**: `[in] uint16_t` value to set.
   3191 
   3192 Notes:
   3193 
   3194 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3195 -   The function always returns `0`.
   3196 
   3197 #### stdlib_ndarray_set_ptr_int16( \*idx, v )
   3198 
   3199 Sets a signed 16-bit integer ndarray data element specified by a byte array pointer.
   3200 
   3201 ```c
   3202 int8_t stdlib_ndarray_set_ptr_int16( uint8_t *idx, const int16_t v );
   3203 ```
   3204 
   3205 The function accepts the following arguments:
   3206 
   3207 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3208 -   **v**: `[in] int16_t` value to set.
   3209 
   3210 Notes:
   3211 
   3212 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3213 -   The function always returns `0`.
   3214 
   3215 #### stdlib_ndarray_set_ptr_uint8( \*idx, v )
   3216 
   3217 Sets an unsigned 8-bit integer ndarray data element specified by a byte array pointer.
   3218 
   3219 ```c
   3220 int8_t stdlib_ndarray_set_ptr_uint8( uint8_t *idx, const uint8_t v );
   3221 ```
   3222 
   3223 The function accepts the following arguments:
   3224 
   3225 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3226 -   **v**: `[in] uint8_t` value to set.
   3227 
   3228 Notes:
   3229 
   3230 -   The function always returns `0`.
   3231 
   3232 #### stdlib_ndarray_set_ptr_int8( \*idx, v )
   3233 
   3234 Sets a signed 8-bit integer ndarray data element specified by a byte array pointer.
   3235 
   3236 ```c
   3237 int8_t stdlib_ndarray_set_ptr_int8( uint8_t *idx, const int8_t v );
   3238 ```
   3239 
   3240 The function accepts the following arguments:
   3241 
   3242 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3243 -   **v**: `[in] int8_t` value to set.
   3244 
   3245 Notes:
   3246 
   3247 -   The function always returns `0`.
   3248 
   3249 #### stdlib_ndarray_set_ptr_complex128( \*idx, v )
   3250 
   3251 Sets a double-precision complex floating-point ndarray data element specified by a byte array pointer.
   3252 
   3253 ```c
   3254 int8_t stdlib_ndarray_set_ptr_complex128( uint8_t *idx, const double complex v );
   3255 ```
   3256 
   3257 The function accepts the following arguments:
   3258 
   3259 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3260 -   **v**: `[in] double complex` value to set.
   3261 
   3262 Notes:
   3263 
   3264 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3265 -   The function always returns `0`.
   3266 
   3267 #### stdlib_ndarray_set_ptr_complex64( \*idx, v )
   3268 
   3269 Sets a single-precision complex floating-point ndarray data element specified by a byte array pointer.
   3270 
   3271 ```c
   3272 int8_t stdlib_ndarray_set_ptr_complex64( uint8_t *idx, const float complex v );
   3273 ```
   3274 
   3275 The function accepts the following arguments:
   3276 
   3277 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3278 -   **v**: `[in] float complex` value to set.
   3279 
   3280 Notes:
   3281 
   3282 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3283 -   The function always returns `0`.
   3284 
   3285 #### stdlib_ndarray_set_ptr_bool( \*idx, v )
   3286 
   3287 Sets a boolean ndarray data element specified by a byte array pointer.
   3288 
   3289 ```c
   3290 int8_t stdlib_ndarray_set_ptr_bool( uint8_t *idx, const bool v );
   3291 ```
   3292 
   3293 The function accepts the following arguments:
   3294 
   3295 -   **idx**: `[in] uint8_t*` byte array pointer to an ndarray data element.
   3296 -   **v**: `[in] bool` value to set.
   3297 
   3298 Notes:
   3299 
   3300 -   The function has no way of determining whether `idx` actually points to a compatible memory address. Accordingly, overwriting **unowned** memory is possible, and this function **assumes** you know what you are doing.
   3301 -   The function always returns `0`.
   3302 
   3303 </section>
   3304 
   3305 <!-- /.usage -->
   3306 
   3307 <!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
   3308 
   3309 <section class="notes">
   3310 
   3311 </section>
   3312 
   3313 <!-- /.notes -->
   3314 
   3315 <!-- C API usage examples. -->
   3316 
   3317 * * *
   3318 
   3319 <section class="examples">
   3320 
   3321 ### Examples
   3322 
   3323 ```c
   3324 #include "stdlib/ndarray/ctor.h"
   3325 #include "stdlib/ndarray/dtypes.h"
   3326 #include "stdlib/ndarray/index_modes.h"
   3327 #include "stdlib/ndarray/orders.h"
   3328 #include "stdlib/ndarray/base/bytes_per_element.h"
   3329 #include "stdlib/ndarray/base/dtype_char.h"
   3330 #include <stdlib.h>
   3331 #include <stdio.h>
   3332 #include <stdint.h>
   3333 #include <inttypes.h>
   3334 
   3335 void print_ndarray_contents( const struct ndarray *x ) {
   3336     int64_t i;
   3337     double v;
   3338     int8_t s;
   3339 
   3340     for ( i = 0; i < stdlib_ndarray_length( x ); i++ ) {
   3341         s = stdlib_ndarray_iget_float64( x, i, &v ); // WARNING: assumes `x->dtype` is float64
   3342         if ( s != 0 ) {
   3343             printf( "Unable to resolve data element.\n" );
   3344             exit( 1 );
   3345         }
   3346         printf( "data[%"PRId64"] = %f\n", i, v );
   3347     }
   3348 }
   3349 
   3350 int main() {
   3351     // Manually create an ndarray (WARNING: this is for illustration purposes only, as the fields of an ndarray are subject to change; for ABI compatibility, use utility functions for accessing ndarray data)...
   3352     struct ndarray *x1 = malloc( sizeof( struct ndarray ) );
   3353     if ( x1 == NULL ) {
   3354         printf( "Error allocating memory.\n" );
   3355         exit( 1 );
   3356     }
   3357 
   3358     // Specify the underlying data type:
   3359     enum STDLIB_NDARRAY_DTYPE dtype = STDLIB_NDARRAY_FLOAT64;
   3360     x1->dtype = dtype;
   3361 
   3362     // Create an underlying byte array:
   3363     uint8_t buffer[] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
   3364     x1->data = buffer;
   3365 
   3366     // Explicitly specify the number of bytes per element:
   3367     x1->BYTES_PER_ELEMENT = STDLIB_NDARRAY_FLOAT64_BYTES_PER_ELEMENT;
   3368 
   3369     // Specify the array shape:
   3370     int64_t shape[] = { 3 }; // vector consisting of 3 doubles
   3371     x1->shape = shape;
   3372 
   3373     // Specify the array strides:
   3374     int64_t strides[] = { x1->BYTES_PER_ELEMENT };
   3375     x1->strides = strides;
   3376 
   3377     // Specify the byte offset:
   3378     x1->offset = 0;
   3379 
   3380     // Specify the array order (note: this does not matter for a 1-dimensional array):
   3381     enum STDLIB_NDARRAY_ORDER order = STDLIB_NDARRAY_ROW_MAJOR;
   3382     x1->order = order;
   3383 
   3384     // Specify the index mode:
   3385     enum STDLIB_NDARRAY_INDEX_MODE imode = STDLIB_NDARRAY_INDEX_ERROR;
   3386     x1->imode = imode;
   3387 
   3388     // Specify the subscript index modes:
   3389     int8_t submodes[] = { imode };
   3390     x1->submodes = submodes;
   3391     x1->nsubmodes = 1;
   3392 
   3393     // Explicitly specify the number of array dimensions:
   3394     x1->ndims = 1; // vector
   3395 
   3396     // Explicitly specify the number of array elements (doubles):
   3397     x1->length = x1->shape[ 0 ];
   3398 
   3399     // Explicitly specify the number of bytes:
   3400     x1->byteLength = (x1->length) * (x1->BYTES_PER_ELEMENT);
   3401 
   3402     // Explicitly set the array flags:
   3403     x1->flags = stdlib_ndarray_flags( x1 );
   3404 
   3405     printf( "dtype = %u\n", stdlib_ndarray_dtype( x1 ) );
   3406     printf( "length = %"PRId64"\n", stdlib_ndarray_length( x1 ) );
   3407     printf( "byteLength = %"PRId64"\n", stdlib_ndarray_bytelength( x1 ) );
   3408     printf( "ltr = %u\n", stdlib_ndarray_dtype_char( stdlib_ndarray_dtype( x1 ) ) );
   3409     printf( "\n" );
   3410 
   3411     // Use the function interface to create an ndarray (NOTE: for future ABI compatibility, using the following function interface should be preferred)...
   3412     struct ndarray *x2 = stdlib_ndarray_allocate( dtype, buffer, 1, shape, strides, 0, order, imode, 1, submodes );
   3413     if ( x2 == NULL ) {
   3414         printf( "Error allocating memory.\n" );
   3415         exit( 1 );
   3416     }
   3417 
   3418     printf( "dtype = %u\n", stdlib_ndarray_dtype( x2 ) );
   3419     printf( "length = %"PRId64"\n", stdlib_ndarray_length( x2 ) );
   3420     printf( "byteLength = %"PRId64"\n", stdlib_ndarray_bytelength( x2 ) );
   3421     printf( "ltr = %u\n", stdlib_ndarray_dtype_char( stdlib_ndarray_dtype( x2 ) ) );
   3422     printf( "\n" );
   3423 
   3424     // Set values in the underlying byte array using pointers:
   3425     int64_t sub[] = { 0 };
   3426     uint8_t *ptr = stdlib_ndarray_get_ptr( x2, sub );
   3427     if ( ptr == NULL ) {
   3428         printf( "Unable to resolve data pointer.\n" );
   3429         exit( 1 );
   3430     }
   3431     *(double *)ptr = 1.0;
   3432 
   3433     sub[ 0 ] = 1;
   3434     ptr = stdlib_ndarray_get_ptr( x2, sub );
   3435     if ( ptr == NULL ) {
   3436         printf( "Unable to resolve data pointer.\n" );
   3437         exit( 1 );
   3438     }
   3439     *(double *)ptr = 2.0;
   3440 
   3441     sub[ 0 ] = 2;
   3442     ptr = stdlib_ndarray_get_ptr( x2, sub );
   3443     if ( ptr == NULL ) {
   3444         printf( "Unable to resolve data pointer.\n" );
   3445         exit( 1 );
   3446     }
   3447     *(double *)ptr = 3.0;
   3448 
   3449     // Print out the current ndarray elements:
   3450     print_ndarray_contents( x2 );
   3451     printf( "\n" );
   3452 
   3453     // Set values in the underlying byte array using a "generic" function:
   3454     sub[ 0 ] = 0;
   3455     double v = 4.0;
   3456     int8_t status = stdlib_ndarray_set( x2, sub, (void *)&v );
   3457     if ( status != 0 ) {
   3458         printf( "Unable to set data element.\n" );
   3459         exit( 1 );
   3460     }
   3461 
   3462     sub[ 0 ] = 1;
   3463     v = 5.0;
   3464     status = stdlib_ndarray_set( x2, sub, (void *)&v );
   3465     if ( status != 0 ) {
   3466         printf( "Unable to set data element.\n" );
   3467         exit( 1 );
   3468     }
   3469 
   3470     sub[ 0 ] = 2;
   3471     v = 6.0;
   3472     status = stdlib_ndarray_set( x2, sub, (void *)&v );
   3473     if ( status != 0 ) {
   3474         printf( "Unable to set data element.\n" );
   3475         exit( 1 );
   3476     }
   3477 
   3478     // Print out the current ndarray elements:
   3479     print_ndarray_contents( x2 );
   3480     printf( "\n" );
   3481 
   3482     // Set values in the underlying byte array using a specialized function:
   3483     sub[ 0 ] = 0;
   3484     status = stdlib_ndarray_set_float64( x2, sub, 7.0 );
   3485     if ( status != 0 ) {
   3486         printf( "Unable to set data element.\n" );
   3487         exit( 1 );
   3488     }
   3489 
   3490     sub[ 0 ] = 1;
   3491     status = stdlib_ndarray_set_float64( x2, sub, 8.0 );
   3492     if ( status != 0 ) {
   3493         printf( "Unable to set data element.\n" );
   3494         exit( 1 );
   3495     }
   3496 
   3497     sub[ 0 ] = 2;
   3498     status = stdlib_ndarray_set_float64( x2, sub, 9.0 );
   3499     if ( status != 0 ) {
   3500         printf( "Unable to set data element.\n" );
   3501         exit( 1 );
   3502     }
   3503 
   3504     // Print out the current ndarray elements:
   3505     print_ndarray_contents( x2 );
   3506     printf( "\n" );
   3507 
   3508     // Free allocated memory:
   3509     stdlib_ndarray_free( x1 );
   3510     stdlib_ndarray_free( x2 );
   3511 }
   3512 ```
   3513 
   3514 </section>
   3515 
   3516 <!-- /.examples -->
   3517 
   3518 </section>
   3519 
   3520 <!-- /.c -->
   3521 
   3522 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
   3523 
   3524 <section class="references">
   3525 
   3526 </section>
   3527 
   3528 <!-- /.references -->
   3529 
   3530 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
   3531 
   3532 <section class="links">
   3533 
   3534 [json]: http://www.json.org/
   3535 
   3536 [@stdlib/ndarray/dtypes]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/dtypes
   3537 
   3538 [@stdlib/ndarray/orders]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/orders
   3539 
   3540 [@stdlib/ndarray/index-modes]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/index-modes
   3541 
   3542 </section>
   3543 
   3544 <!-- /.links -->
	time-to-botec Benchmark sampling in different programming languages
	Log \| Files \| Refs \| README