README.md (5507B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2021 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 an ndarray interface for applying a unary callback to an input ndarray. 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/ndarray/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/ndarray/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/ndarray/base/napi/unary.h" 105 ``` 106 107 #### stdlib_ndarray_napi_unary( env, info, \*obj ) 108 109 Invokes an ndarray interface which applies a unary callback to an input ndarray based on provided JavaScript arguments. 110 111 ```c 112 #include "stdlib/ndarray/base/function_object.h" 113 #include <node_api.h> 114 115 // ... 116 117 static const struct ndarrayFunctionObject 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_ndarray_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 ndarrayFunctionObject*` ndarray [function object][@stdlib/ndarray/base/function-object]. 141 142 ```c 143 void stdlib_ndarray_napi_unary( napi_env env, napi_callback_info info, const struct ndarrayFunctionObject *obj ); 144 ``` 145 146 #### STDLIB_NDARRAY_NAPI_MODULE_UNARY( obj ) 147 148 Macro for registering a Node-API module exporting an ndarray interface for applying a unary callback to an input ndarray. 149 150 ```c 151 #include "stdlib/ndarray/base/function_object.h" 152 153 // ... 154 155 // Create an ndarray function object: 156 static const struct ndarrayFunctionObject obj = {...}; 157 158 // ... 159 160 // Register a Node-API module: 161 STDLIB_NDARRAY_NAPI_MODULE_UNARY( obj ); 162 ``` 163 164 The macro expects the following arguments: 165 166 - **obj**: `struct ndarrayFunctionObject` ndarray [function object][@stdlib/ndarray/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 - `X`: input ndarray data buffer (i.e., [typed array][mdn-typed-array]). 183 - `metaX`: `X` [serialized meta data][@stdlib/ndarray/base/serialize-meta-data]. 184 - `Y`: destination ndarray data buffer (i.e., [typed array][mdn-typed-array]). 185 - `metaY`: `Y` [serialized meta data][@stdlib/ndarray/base/serialize-meta-data]. 186 187 </section> 188 189 <!-- /.notes --> 190 191 <!-- C API usage examples. --> 192 193 <section class="examples"> 194 195 </section> 196 197 <!-- /.examples --> 198 199 </section> 200 201 <!-- /.c --> 202 203 <!-- 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. --> 204 205 <section class="references"> 206 207 </section> 208 209 <!-- /.references --> 210 211 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 212 213 <section class="links"> 214 215 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 216 217 [@stdlib/ndarray/base/function-object]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/base/function-object 218 219 [@stdlib/ndarray/base/serialize-meta-data]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/base/serialize-meta-data 220 221 </section> 222 223 <!-- /.links -->