README.md (5456B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2020 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 # dmap 22 23 > C API for registering a Node-API module exporting a strided array interface for applying a unary callback accepting and returning double-precision floating-point numbers to each element in a double-precision floating-point strided input array and assigning results to elements in a double-precision floating-point strided output array. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var headerDir = require( '@stdlib/strided/napi/dmap' ); 41 ``` 42 43 #### headerDir 44 45 Absolute file path for the directory containing header files for C APIs. 46 47 ```javascript 48 var dir = headerDir; 49 // returns <string> 50 ``` 51 52 </section> 53 54 <!-- /.usage --> 55 56 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 57 58 <section class="notes"> 59 60 </section> 61 62 <!-- /.notes --> 63 64 <!-- Package usage examples. --> 65 66 <section class="examples"> 67 68 ## Examples 69 70 ```javascript 71 var headerDir = require( '@stdlib/strided/napi/dmap' ); 72 73 console.log( headerDir ); 74 // => <string> 75 ``` 76 77 </section> 78 79 <!-- /.examples --> 80 81 <!-- C interface documentation. --> 82 83 * * * 84 85 <section class="c"> 86 87 ## C APIs 88 89 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 90 91 <section class="intro"> 92 93 </section> 94 95 <!-- /.intro --> 96 97 <!-- C usage documentation. --> 98 99 <section class="usage"> 100 101 ### Usage 102 103 ```c 104 #include "stdlib/strided/napi/dmap.h" 105 ``` 106 107 #### stdlib_strided_napi_dmap( env, info, fcn ) 108 109 Invokes a strided array interface which applies a unary callback accepting and returning double-precision floating-point numbers to each element in a double-precision floating-point strided input array and assigns results to elements in a double-precision floating-point strided output array. 110 111 ```c 112 #include <node_api.h> 113 114 // ... 115 116 static double identity( const double x ) { 117 return x; 118 } 119 120 // ... 121 122 /** 123 * Receives JavaScript callback invocation data. 124 * 125 * @param env environment under which the function is invoked 126 * @param info callback data 127 * @return Node-API value 128 */ 129 napi_value addon( napi_env env, napi_callback_info info ) { 130 stdlib_strided_napi_dmap( env, info, identity ); 131 return NULL; 132 } 133 134 // ... 135 ``` 136 137 The function accepts the following arguments: 138 139 - **env**: `[in] napi_env` environment under which the function is invoked. 140 - **info**: `[in] napi_callback_info` callback data. 141 - **fcn**: `[in] double (*fcn)( double )` unary callback. 142 143 ```c 144 void stdlib_strided_napi_dmap( napi_env env, napi_callback_info info, double (*fcn)( double ) ); 145 ``` 146 147 #### STDLIB_STRIDED_NAPI_MODULE_DMAP( clbk ) 148 149 Macro for registering a Node-API module exporting a strided array interface for applying a unary callback accepting and return double-precision floating-point numbers to each element in a double-precision floating-point strided input array and assigning results to elements in a double-precision floating-point strided output array. 150 151 ```c 152 static double scale( const double x ) { 153 return x * 10.0; 154 } 155 156 // ... 157 158 // Register a Node-API module: 159 STDLIB_STRIDED_NAPI_MODULE_DMAP( scale ); 160 ``` 161 162 The macro expects the following arguments: 163 164 - **clbk**: `double (*fcn)( double )` unary callback. 165 166 When used, this macro should be used **instead of** `NAPI_MODULE`. The macro includes `NAPI_MODULE`, thus ensuring Node-API module registration. 167 168 </section> 169 170 <!-- /.usage --> 171 172 <!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 173 174 <section class="notes"> 175 176 ### Notes 177 178 - The function expects that the callback `info` argument provides access to the following JavaScript arguments: 179 180 - `N`: number of indexed elements. 181 - `X`: input [`Float64Array`][@stdlib/array/float64]. 182 - `strideX`: `X` stride length. 183 - `Y`: destination [`Float64Array`][@stdlib/array/float64]. 184 - `strideY`: `Y` stride length. 185 186 </section> 187 188 <!-- /.notes --> 189 190 <!-- C API usage examples. --> 191 192 <section class="examples"> 193 194 </section> 195 196 <!-- /.examples --> 197 198 </section> 199 200 <!-- /.c --> 201 202 <!-- 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. --> 203 204 <section class="references"> 205 206 </section> 207 208 <!-- /.references --> 209 210 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 211 212 <section class="links"> 213 214 [@stdlib/array/float64]: https://www.npmjs.com/package/@stdlib/array-float64 215 216 </section> 217 218 <!-- /.links -->