README.md (5297B)
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 API for registering a Node-API module exporting a strided array interface for applying a unary callback to an input strided 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/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/strided/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/strided/napi/unary.h" 105 ``` 106 107 #### stdlib_strided_napi_unary( env, info, \*obj ) 108 109 Invokes a strided array interface which applies a unary callback to an input strided array based on provided JavaScript arguments. 110 111 ```c 112 #include "stdlib/strided/base/function_object.h" 113 #include <node_api.h> 114 115 // ... 116 117 static const struct StridedFunctionObject obj = {...}; 118 119 // ... 120 121 /** 122 * Receives JavaScript callback invocation data. 123 * 124 * @param env environment under which the function is invoked 125 * @param info callback data 126 * @return Node-API value 127 */ 128 napi_value addon( napi_env env, napi_callback_info info ) { 129 stdlib_strided_napi_unary( env, info, &obj ); 130 return NULL; 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 - **obj**: `[in] struct StridedFunctionObject*` strided array [function object][@stdlib/strided/base/function-object]. 141 142 ```c 143 void stdlib_strided_napi_unary( napi_env env, napi_callback_info info, const struct StridedFunctionObject *obj ); 144 ``` 145 146 #### STDLIB_STRIDED_NAPI_MODULE_UNARY( obj ) 147 148 Macro for registering a Node-API module exporting a strided array interface for applying a unary callback to an input strided array. 149 150 ```c 151 #include "stdlib/strided/base/function_object.h" 152 153 // ... 154 155 // Create a strided function object: 156 static const struct StridedFunctionObject obj = {...}; 157 158 // ... 159 160 // Register a Node-API module: 161 STDLIB_STRIDED_NAPI_MODULE_UNARY( obj ); 162 ``` 163 164 The macro expects the following arguments: 165 166 - **obj**: `struct StridedFunctionObject` strided array [function object][@stdlib/strided/base/function-object]. 167 168 When used, this macro should be used **instead of** `NAPI_MODULE`. The macro includes `NAPI_MODULE`, thus ensuring Node-API module registration. 169 170 </section> 171 172 <!-- /.usage --> 173 174 <!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 175 176 <section class="notes"> 177 178 ### Notes 179 180 - The function expects that the callback `info` argument provides access to the following JavaScript arguments: 181 182 - `N`: number of indexed elements. 183 - `X`: input [typed array][mdn-typed-array]. 184 - `strideX`: `X` stride length. 185 - `Y`: destination [typed array][mdn-typed-array]. 186 - `strideY`: `Y` stride length. 187 188 </section> 189 190 <!-- /.notes --> 191 192 <!-- C API usage examples. --> 193 194 <section class="examples"> 195 196 </section> 197 198 <!-- /.examples --> 199 200 </section> 201 202 <!-- /.c --> 203 204 <!-- 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. --> 205 206 <section class="references"> 207 208 </section> 209 210 <!-- /.references --> 211 212 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 213 214 <section class="links"> 215 216 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 217 218 [@stdlib/strided/base/function-object]: https://www.npmjs.com/package/@stdlib/strided/tree/main/base/function-object 219 220 </section> 221 222 <!-- /.links -->