README.md (7604B)
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 # unary 22 23 > C APIs for registering a Node-API module exporting interfaces for invoking unary numerical functions. 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/math/base/napi/unary' ); 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/math/base/napi/unary' ); 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/math/base/napi/unary.h" 105 ``` 106 107 #### stdlib_math_base_napi_d_d( env, info, fcn ) 108 109 Invokes a unary function accepting and returning double-precision floating-point numbers. 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 return stdlib_math_base_napi_d_d( env, info, identity ); 131 } 132 133 // ... 134 ``` 135 136 The function accepts the following arguments: 137 138 - **env**: `[in] napi_env` environment under which the function is invoked. 139 - **info**: `[in] napi_callback_info` callback data. 140 - **fcn**: `[in] double (*fcn)( double )` unary function. 141 142 ```c 143 void stdlib_math_base_napi_d_d( napi_env env, napi_callback_info info, double (*fcn)( double ) ); 144 ``` 145 146 #### stdlib_math_base_napi_f_f( env, info, fcn ) 147 148 Invokes a unary function accepting and returning single-precision floating-point numbers. 149 150 ```c 151 #include <node_api.h> 152 153 // ... 154 155 static float identityf( const float x ) { 156 return x; 157 } 158 159 // ... 160 161 /** 162 * Receives JavaScript callback invocation data. 163 * 164 * @param env environment under which the function is invoked 165 * @param info callback data 166 * @return Node-API value 167 */ 168 napi_value addon( napi_env env, napi_callback_info info ) { 169 return stdlib_math_base_napi_f_f( env, info, identityf ); 170 } 171 172 // ... 173 ``` 174 175 The function accepts the following arguments: 176 177 - **env**: `[in] napi_env` environment under which the function is invoked. 178 - **info**: `[in] napi_callback_info` callback data. 179 - **fcn**: `[in] float (*fcn)( float )` unary function. 180 181 ```c 182 void stdlib_math_base_napi_f_f( napi_env env, napi_callback_info info, float (*fcn)( float ) ); 183 ``` 184 185 #### stdlib_math_base_napi_i_i( env, info, fcn ) 186 187 Invokes a unary function accepting and returning 32-bit signed integers. 188 189 ```c 190 #include <node_api.h> 191 #include <stdint.h> 192 193 // ... 194 195 static int32_t identity( const int32_t x ) { 196 return x; 197 } 198 199 // ... 200 201 /** 202 * Receives JavaScript callback invocation data. 203 * 204 * @param env environment under which the function is invoked 205 * @param info callback data 206 * @return Node-API value 207 */ 208 napi_value addon( napi_env env, napi_callback_info info ) { 209 return stdlib_math_base_napi_i_i( env, info, identity ); 210 } 211 212 // ... 213 ``` 214 215 The function accepts the following arguments: 216 217 - **env**: `[in] napi_env` environment under which the function is invoked. 218 - **info**: `[in] napi_callback_info` callback data. 219 - **fcn**: `[in] int32_t (*fcn)( int32_t )` unary function. 220 221 ```c 222 void stdlib_math_base_napi_i_i( napi_env env, napi_callback_info info, int32_t (*fcn)( int32_t ) ); 223 ``` 224 225 #### STDLIB_MATH_BASE_NAPI_MODULE_D_D( fcn ) 226 227 Macro for registering a Node-API module exporting an interface for invoking a unary function accepting and returning double-precision floating-point numbers. 228 229 ```c 230 static double scale( const double x ) { 231 return x * 10.0; 232 } 233 234 // ... 235 236 // Register a Node-API module: 237 STDLIB_MATH_BASE_NAPI_MODULE_D_D( scale ); 238 ``` 239 240 The macro expects the following arguments: 241 242 - **fcn**: `double (*fcn)( double )` unary function. 243 244 When used, this macro should be used **instead of** `NAPI_MODULE`. The macro includes `NAPI_MODULE`, thus ensuring Node-API module registration. 245 246 #### STDLIB_MATH_BASE_NAPI_MODULE_F_F( fcn ) 247 248 Macro for registering a Node-API module exporting an interface for invoking a unary function accepting and returning single-precision floating-point numbers. 249 250 ```c 251 static float scale( const float x ) { 252 return x * 10.0f; 253 } 254 255 // ... 256 257 // Register a Node-API module: 258 STDLIB_MATH_BASE_NAPI_MODULE_F_F( scale ); 259 ``` 260 261 The macro expects the following arguments: 262 263 - **fcn**: `float (*fcn)( float )` unary function. 264 265 When used, this macro should be used **instead of** `NAPI_MODULE`. The macro includes `NAPI_MODULE`, thus ensuring Node-API module registration. 266 267 #### STDLIB_MATH_BASE_NAPI_MODULE_I_I( fcn ) 268 269 Macro for registering a Node-API module exporting an interface for invoking a unary function accepting and returning 32-bit signed integers. 270 271 ```c 272 #include <stdint.h> 273 274 static int32_t scale( const int32_t x ) { 275 return x * 10; 276 } 277 278 // ... 279 280 // Register a Node-API module: 281 STDLIB_MATH_BASE_NAPI_MODULE_I_I( scale ); 282 ``` 283 284 The macro expects the following arguments: 285 286 - **fcn**: `int32_t (*fcn)( int32_t )` unary function. 287 288 When used, this macro should be used **instead of** `NAPI_MODULE`. The macro includes `NAPI_MODULE`, thus ensuring Node-API module registration. 289 290 </section> 291 292 <!-- /.usage --> 293 294 <!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 295 296 <section class="notes"> 297 298 ### Notes 299 300 - The C-API functions expect that the callback `info` argument provides access to the following JavaScript arguments: 301 302 - `x`: input value. 303 304 </section> 305 306 <!-- /.notes --> 307 308 <!-- C API usage examples. --> 309 310 <section class="examples"> 311 312 </section> 313 314 <!-- /.examples --> 315 316 </section> 317 318 <!-- /.c --> 319 320 <!-- 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. --> 321 322 <section class="references"> 323 324 </section> 325 326 <!-- /.references --> 327 328 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 329 330 <section class="links"> 331 332 </section> 333 334 <!-- /.links -->