README.md (5008B)
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 # cbrt 22 23 > Compute the [cube root][cube-root] of each element in a strided array. 24 25 <section class="intro"> 26 27 </section> 28 29 <!-- /.intro --> 30 31 <section class="usage"> 32 33 ## Usage 34 35 ```javascript 36 var cbrt = require( '@stdlib/math/strided/special/cbrt' ); 37 ``` 38 39 #### cbrt( N, x, strideX, y, strideY ) 40 41 Computes the [cube root][cube-root] of each element in a strided array `x` and assigns the results to elements in a strided array `y`. 42 43 ```javascript 44 var Float64Array = require( '@stdlib/array/float64' ); 45 46 var x = new Float64Array( [ 0.0, 1.0, 8.0, 27.0, 64.0 ] ); 47 48 // Perform operation in-place: 49 cbrt( x.length, x, 1, x, 1 ); 50 // x => <Float64Array>[ 0.0, 1.0, 2.0, 3.0, 4.0 ] 51 ``` 52 53 The function accepts the following arguments: 54 55 - **N**: number of indexed elements. 56 - **x**: input array-like object. 57 - **strideX**: index increment for `x`. 58 - **y**: output array-like object. 59 - **strideY**: index increment for `y`. 60 61 The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to index every other value in `x` and the first `N` elements of `y` in reverse order, 62 63 ```javascript 64 var Float64Array = require( '@stdlib/array/float64' ); 65 66 var x = new Float64Array( [ 0.0, 1.0, 8.0, 27.0, 64.0, 125.0 ] ); 67 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 68 69 cbrt( 3, x, 2, y, -1 ); 70 // y => <Float64Array>[ 4.0, 2.0, 0.0, 0.0, 0.0, 0.0 ] 71 ``` 72 73 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 74 75 ```javascript 76 var Float64Array = require( '@stdlib/array/float64' ); 77 78 // Initial arrays... 79 var x0 = new Float64Array( [ 0.0, 1.0, 8.0, 27.0, 64.0, 125.0 ] ); 80 var y0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 81 82 // Create offset views... 83 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 84 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 85 86 cbrt( 3, x1, -2, y1, 1 ); 87 // y0 => <Float64Array>[ 0.0, 0.0, 0.0, 5.0, 3.0, 1.0 ] 88 ``` 89 90 #### cbrt.ndarray( N, x, strideX, offsetX, y, strideY, offsetY ) 91 92 Computes the [cube root][cube-root] of each element in a strided array `x` and assigns the results to elements in a strided array `y` using alternative indexing semantics. 93 94 ```javascript 95 var Float64Array = require( '@stdlib/array/float64' ); 96 97 var x = new Float64Array( [ 0.0, 1.0, 8.0, 27.0, 64.0 ] ); 98 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 99 100 cbrt.ndarray( x.length, x, 1, 0, y, 1, 0 ); 101 // y => <Float64Array>[ 0.0, 1.0, 2.0, 3.0, 4.0 ] 102 ``` 103 104 The function accepts the following additional arguments: 105 106 - **offsetX**: starting index for `x`. 107 - **offsetY**: starting index for `y`. 108 109 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offsetX` and `offsetY` parameters support indexing semantics based on starting indices. For example, to index every other value in `x` starting from the second value and to index the last `N` elements in `y`, 110 111 ```javascript 112 var Float64Array = require( '@stdlib/array/float64' ); 113 114 var x = new Float64Array( [ 0.0, 1.0, 8.0, 27.0, 64.0, 125.0 ] ); 115 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 116 117 cbrt.ndarray( 3, x, 2, 1, y, -1, y.length-1 ); 118 // y => <Float64Array>[ 0.0, 0.0, 0.0, 5.0, 3.0, 1.0 ] 119 ``` 120 121 </section> 122 123 <!-- /.usage --> 124 125 <section class="notes"> 126 127 </section> 128 129 <!-- /.notes --> 130 131 <section class="examples"> 132 133 ## Examples 134 135 <!-- eslint no-undef: "error" --> 136 137 ```javascript 138 var uniform = require( '@stdlib/random/base/uniform' ).factory; 139 var filledarray = require( '@stdlib/array/filled' ); 140 var dtypes = require( '@stdlib/array/dtypes' ); 141 var gfillBy = require( '@stdlib/blas/ext/base/gfill-by' ); 142 var cbrt = require( '@stdlib/math/strided/special/cbrt' ); 143 144 var dt; 145 var x; 146 var y; 147 var i; 148 149 dt = dtypes(); 150 for ( i = 0; i < dt.length; i++ ) { 151 x = filledarray( 0.0, 10, dt[ i ] ); 152 gfillBy( x.length, x, 1, uniform( -100.0, 100.0 ) ); 153 console.log( x ); 154 155 y = filledarray( 0.0, x.length, 'generic' ); 156 console.log( y ); 157 158 cbrt.ndarray( x.length, x, 1, 0, y, -1, y.length-1 ); 159 console.log( y ); 160 console.log( '' ); 161 } 162 ``` 163 164 </section> 165 166 <!-- /.examples --> 167 168 <section class="links"> 169 170 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 171 172 [cube-root]: https://en.wikipedia.org/wiki/Cube_root 173 174 </section> 175 176 <!-- /.links -->