polyfill.js (6319B)
1 /** 2 * @license Apache-2.0 3 * 4 * Copyright (c) 2021 The Stdlib Authors. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 'use strict'; 20 21 // MODULES // 22 23 var IS_LITTLE_ENDIAN = require( '@stdlib/assert/is-little-endian' ); 24 var float64ToInt64Bytes = require( '@stdlib/number/float64/base/to-int64-bytes' ).assign; 25 var ArrayBuffer = require( '@stdlib/array/buffer' ); 26 var Uint8Array = require( '@stdlib/array/uint8' ); 27 var DataView = require( '@stdlib/array/dataview' ); 28 var bytesPerElement = require( './../../../base/bytes-per-element' ); 29 var dtypes = require( './../../../dtypes' ).enum; 30 var orders = require( './../../../orders' ).enum; 31 var modes = require( './../../../index-modes' ).enum; 32 33 34 // VARIABLES // 35 36 var DTYPES = dtypes(); 37 var ORDERS = orders(); 38 var MODES = modes(); 39 40 41 // MAIN // 42 43 /** 44 * Serializes ndarray meta data. 45 * 46 * ## Notes 47 * 48 * - This function takes into account ndarray-like objects which may support index modes. 49 * 50 * - Serialization is performed according to host byte order (endianness). 51 * 52 * - Meta data format: 53 * 54 * ```text 55 * | endianness (1 byte) | <dtype> (2 bytes) | <ndims> (8 bytes) | <shape> (ndims*8 bytes) | <strides> (ndims*8 bytes) | <offset> (8 bytes) | <order> (1 byte) | <mode> (1 byte) | <nsubmodes> (8 bytes) | <submodes> (nsubmodes*1 bytes) | 56 * ``` 57 * 58 * which translates to the following `ArrayBuffer` layout: 59 * 60 * ```text 61 * ArrayBuffer[ 62 * <endianness>[int8], 63 * <dtype>[int16], 64 * <ndims>[int64], 65 * <shape>[ndims*int64], 66 * <strides>[ndims*int64], 67 * <offset>[int64], 68 * <order>[int8], 69 * <mode>[int8], 70 * <nsubmodes>[int64], 71 * <submodes>[nsubmodes*int8] 72 * ] 73 * ``` 74 * 75 * where `strides` and `offset` are in units of bytes. 76 * 77 * - If the endianness is `1`, the byte order is little endian. If the endianness is `0`, the byte order is big endian. 78 * 79 * - Buffer length: 80 * 81 * ```text 82 * 1 + 2 + 8 + (ndims*8) + (ndims*8) + 8 + 1 + 1 + 8 + (nsubmodes*1) = 29 + (ndims*16) + nsubmodes 83 * ``` 84 * 85 * For example, consider a three-dimensional ndarray with one subscript index mode (submode): 86 * 87 * ```text 88 * 29 + (3*16) + 1 = 78 bytes 89 * ``` 90 * 91 * - Views: 92 * 93 * - endianness: `Int8Array( buf, 0, 1 )` 94 * - dtype: `Int16Array( buf, 1, 1 )` 95 * - ndims: `Int64Array( buf, 3, 1 )` 96 * - shape: `Int64Array( buf, 11, ndims )` 97 * - strides: `Int64Array( buf, 11+(ndims*8), ndims )` 98 * - offset: `Int64Array( buf, 11+(ndims*16), 1 )` 99 * - order: `Int8Array( buf, 19+(ndims*16), 1 )` 100 * - mode: `Int8Array( buf, 20+(ndims*16), 1 )` 101 * - nsubmodes: `Int64Array( buf, 21+(ndims*16), 1 )` 102 * - submodes: `Int8Array( buf, 29+(ndims*16), nsubmodes )` 103 * 104 * @private 105 * @param {ndarrayLike} x - input array 106 * @param {string} x.dtype - array data type 107 * @param {NonNegativeIntegerArray} x.shape - array shape 108 * @param {IntegerArray} x.strides - array strides 109 * @param {NonNegativeInteger} x.offset - array index offset 110 * @param {string} x.order - array order 111 * @param {string} [x.mode='throw'] - array index mode 112 * @param {StringArray} [x.submode=[x.mode]] - array subscript index modes 113 * @returns {DataView} serialized meta data 114 * 115 * @example 116 * var array = require( '@stdlib/ndarray/array' ); 117 * 118 * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); 119 * 120 * var dv = serialize( x ); 121 * // returns <DataView> 122 */ 123 function serialize( x ) { 124 var nbytes; 125 var bytes; 126 var len; 127 var dt; 128 var sh; 129 var st; 130 var sm; 131 var v; 132 var m; 133 var o; 134 var s; 135 var N; 136 var M; 137 var i; 138 139 // Check for interface which does the work of serializing to a DataView for us... 140 if ( x.__array_meta_dataview__ ) { // eslint-disable-line no-underscore-dangle 141 return x.__array_meta_dataview__(); // eslint-disable-line no-underscore-dangle 142 } 143 // Extract meta data known to be attached to ndarray-like objects: 144 dt = x.dtype; 145 sh = x.shape; 146 st = x.strides; 147 N = sh.length; // ndims 148 149 // Extract meta data which may be available on ndarray-like objects (e.g., stdlib ndarray instances): 150 m = x.mode || 'throw'; 151 sm = x.submode || [ m ]; 152 M = sm.length; 153 154 // Determine number of bytes per element according to the ndarray dtype: 155 nbytes = bytesPerElement( dt ); 156 157 // Compute the amount of memory we need to allocate for storing meta data: 158 len = 29 + (N*16) + M; 159 160 // Allocate raw memory and create a view for interfacing with the allocated memory: 161 v = new DataView( new ArrayBuffer( len ) ); 162 bytes = new Uint8Array( v.buffer ); 163 164 // Endianness: (byteoffset: 0; bytelength: 1) 165 o = 0; 166 v.setInt8( o, ( IS_LITTLE_ENDIAN ) ? 1 : 0 ); 167 168 // Data type: (byteoffset: 1; bytelength: 2) 169 o += 1; 170 v.setInt16( o, DTYPES[ dt ], IS_LITTLE_ENDIAN ); 171 172 // Number of dimensions: (byteoffset: 3; bytelength: 8) 173 o += 2; 174 float64ToInt64Bytes( N, bytes, 1, o ); 175 176 // Shape and strides: (byteoffset: 11 and 11+(ndims*8), respectively; bytelength: ndims*8 for both shape and strides, and, thus, ndims*16 total) 177 s = N * 8; // stride length between a dimension (shape[i]) and its associated stride 178 o += 8; 179 for ( i = 0; i < N; i++ ) { 180 float64ToInt64Bytes( sh[i], bytes, 1, o ); 181 float64ToInt64Bytes( st[i]*nbytes, bytes, 1, o+s ); 182 o += 8; 183 } 184 // Offset: (byteoffset: 11+(ndims*16); bytelength: 8) 185 o += s; 186 float64ToInt64Bytes( x.offset*nbytes, bytes, 1, o ); 187 188 // Order: (byteoffset: 19+(ndims*16); bytelength: 1) 189 o += 8; 190 v.setInt8( o, ORDERS[ x.order ] ); 191 192 // Index mode: (byteoffset: 20+(ndims*16); bytelength: 1) 193 o += 1; 194 v.setInt8( o, MODES[ m ] ); 195 196 // Number of index submodes: (byteoffset: 21+(ndims*16); bytelength: 8) 197 o += 1; 198 float64ToInt64Bytes( M, bytes, 1, o ); 199 200 // Submodes: (byteoffset: 29+(ndims*16); bytelength: nsubmodes*1) 201 o += 8; 202 for ( i = 0; i < M; i++ ) { 203 v.setInt8( o, MODES[ sm[i] ] ); 204 o += 1; 205 } 206 return v; 207 } 208 209 210 // EXPORTS // 211 212 module.exports = serialize;