@stdlib/array-complex64 0.0.2 → 0.0.6

package/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # Complex64Array
 
-[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] [![dependencies][dependencies-image]][dependencies-url]
+[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
 
 > 64-bit complex number array.
 
@@ -75,9 +75,24 @@ var len = arr.length;
 // returns 10
 ```
 
+#### Complex64Array( complexarray )
+
+Creates a 64-bit complex number array from another complex number array.
+
+```javascript
+var arr1 = new Complex64Array( [ 1.0, -1.0, 2.0, -2.0 ] ); // [ re, im, re, im ]
+// returns <Complex64Array>
+
+var arr2 = new Complex64Array( arr1 );
+// returns <Complex64Array>
+
+var len = arr2.length;
+// returns 2
+```
+
 #### Complex64Array( typedarray )
 
-Creates a 64-bit complex number array from a [typed array][@stdlib/array/typed] containing interleaves real and imaginary components.
+Creates a 64-bit complex number array from a [typed array][@stdlib/array/typed] containing interleaved real and imaginary components.
 
 ```javascript
 var Float32Array = require( '@stdlib/array-float32' );
@@ -94,7 +109,7 @@ var len = arr.length;
 
 #### Complex64Array( obj )
 
-Creates a 64-bit complex number array from an array-like `object` or iterable.
+Creates a 64-bit complex number array from an array-like object or iterable.
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
@@ -254,7 +269,7 @@ var len = arr.length;
 
 #### Complex64Array.from( src\[, clbk\[, thisArg]] )
 
-Creates a new 64-bit complex number array from an array-like `object` or an iterable.
+Creates a new 64-bit complex number array from an array-like object or an iterable.
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
@@ -274,13 +289,13 @@ len = arr.length;
 // returns 1
 ```
 
-The iterator returned by an iterable must return either a complex number or an array-like `object` containing a real and imaginary component.
+The iterator returned by an iterable must return either a complex number or an array-like object containing a real and imaginary component.
 
 ```javascript
 var ITERATOR_SYMBOL = require( '@stdlib/symbol-iterator' );
 var Float32Array = require( '@stdlib/array-float32' );
-var real = require( '@stdlib/complex-real' );
-var imag = require( '@stdlib/complex-imag' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var iter;
 var arr;
@@ -330,23 +345,23 @@ if ( ITERATOR_SYMBOL === null ) {
     z = arr.get( 0 );
     // returns <Complex64>
 
-    re = real( z );
+    re = realf( z );
     // returns 1.0
 
-    im = imag( z );
+    im = imagf( z );
     // returns -1.0
 }
 ```
 
-To invoke a function for each `src` value, provide a callback function. If `src` is an iterable or an array-like `object` containing complex numbers, the callback must return either a complex number
+To invoke a function for each `src` value, provide a callback function. If `src` is an iterable or an array-like object containing complex numbers, the callback must return either a complex number
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
-var real = require( '@stdlib/complex-real' );
-var imag = require( '@stdlib/complex-imag' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 function map( z ) {
-    return new Complex64( real(z)*2.0, imag(z)*2.0 );
+    return new Complex64( realf(z)*2.0, imagf(z)*2.0 );
 }
 
 // Create a source array:
@@ -362,20 +377,20 @@ var len = arr.length;
 var z = arr.get( 0 );
 // returns <Complex64>
 
-var re = real( z );
+var re = realf( z );
 // returns 2.0
 
-var im = imag( z );
+var im = imagf( z );
 // returns -2.0
 ```
 
-or an array-like `object` containing real and imaginary components
+or an array-like object containing real and imaginary components
 
 ```javascript
 var Float32Array = require( '@stdlib/array-float32' );
 var Complex64 = require( '@stdlib/complex-float32' );
-var real = require( '@stdlib/complex-real' );
-var imag = require( '@stdlib/complex-imag' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 // Return a callback which reuses allocated memory...
 function mapFcn() {
@@ -383,8 +398,8 @@ function mapFcn() {
     return map;
 
     function map( z ) {
-        buf[ 0 ] = real( z ) * 2.0;
-        buf[ 1 ] = imag( z ) * 2.0;
+        buf[ 0 ] = realf( z ) * 2.0;
+        buf[ 1 ] = imagf( z ) * 2.0;
         return buf;
     }
 }
@@ -402,29 +417,29 @@ var len = arr.length;
 var z = arr.get( 0 );
 // returns <Complex64>
 
-var re = real( z );
+var re = realf( z );
 // returns 2.0
 
-var im = imag( z );
+var im = imagf( z );
 // returns -2.0
 
 z = arr.get( 1 );
 // returns <Complex64>
 
-re = real( z );
+re = realf( z );
 // returns 4.0
 
-im = imag( z );
+im = imagf( z );
 // returns -4.0
 ```
 
-If `src` is an array-like `object` containing interleaved real and imaginary components, the callback is invoked for each component and should return the transformed component value.
+If `src` is an array-like object containing interleaved real and imaginary components, the callback is invoked for each component and should return the transformed component value.
 
 ```javascript
 var Float32Array = require( '@stdlib/array-float32' );
 var Complex64 = require( '@stdlib/complex-float32' );
-var real = require( '@stdlib/complex-real' );
-var imag = require( '@stdlib/complex-imag' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 function map( v ) {
     return v * 2.0;
@@ -443,28 +458,28 @@ var len = arr.length;
 var z = arr.get( 0 );
 // returns <Complex64>
 
-var re = real( z );
+var re = realf( z );
 // returns 2.0
 
-var im = imag( z );
+var im = imagf( z );
 // returns -2.0
 ```
 
 A callback function is provided two arguments:
 
--   `value`: source value
--   `index`: source index
+-   **value**: source value.
+-   **index**: source index.
 
 To set the callback execution context, provide a `thisArg`.
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
-var real = require( '@stdlib/complex-real' );
-var imag = require( '@stdlib/complex-imag' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 function map( z ) {
     this.count += 1;
-    return new Complex64( real(z)*2.0, imag(z)*2.0 );
+    return new Complex64( realf(z)*2.0, imagf(z)*2.0 );
 }
 
 // Create a source array:
@@ -519,6 +534,8 @@ Copies a sequence of elements within the array starting at `start` and ending at
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 4 );
 
@@ -529,29 +546,55 @@ arr.set( new Complex64( 3.0, -3.0 ), 2 );
 arr.set( new Complex64( 4.0, -4.0 ), 3 );
 
 // Get the first array element:
-var z = arr.get( [ 0.0, 0.0 ], 0 );
-// returns [ 1.0, -1.0 ]
+var z = arr.get( 0 );
+// returns <Complex64>
+
+var re = realf( z );
+// returns 1.0
+
+var im = imagf( z );
+// returns -1.0
 
 // Get the second array element:
-z = arr.get( [ 0.0, 0.0 ], 1 );
-// returns [ 2.0, -2.0 ]
+z = arr.get( 1 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 2.0
+
+im = imagf( z );
+// returns -2.0
 
 // Copy the last two elements to the first two elements:
 arr.copyWithin( 0, 2 );
 
 // Get the first array element:
-z = arr.get( [ 0.0, 0.0 ], 0 );
-// returns [ 3.0, -3.0 ]
+z = arr.get( 0 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 3.0
+
+im = imagf( z );
+// returns -3.0
 
 // Get the second array element:
-z = arr.get( [ 0.0, 0.0 ], 1 );
-// returns [ 4.0, -4.0 ]
+z = arr.get( 1 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 4.0
+
+im = imagf( z );
+// returns -4.0
 ```
 
 By default, `end` equals the number of array elements (i.e., one more than the last array index). To limit the sequence length, provide an `end` argument.
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 4 );
 
@@ -562,29 +605,55 @@ arr.set( new Complex64( 3.0, -3.0 ), 2 );
 arr.set( new Complex64( 4.0, -4.0 ), 3 );
 
 // Get the third array element:
-var z = arr.get( [ 0.0, 0.0 ], 2 );
-// returns [ 3.0, -3.0 ]
+var z = arr.get( 2 );
+// returns <Complex64>
+
+var re = realf( z );
+// returns 3.0
+
+var im = imagf( z );
+// returns -3.0
 
 // Get the last array element:
-z = arr.get( [ 0.0, 0.0 ], 3 );
-// returns [ 4.0, -4.0 ]
+z = arr.get( 3 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 4.0
+
+im = imagf( z );
+// returns -4.0
 
 // Copy the first two elements to the last two elements:
 arr.copyWithin( 2, 0, 2 );
 
 // Get the third array element:
-z = arr.get( [ 0.0, 0.0 ], 2 );
-// returns [ 1.0, -1.0 ]
+z = arr.get( 2 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 1.0
+
+im = imagf( z );
+// returns -1.0
 
 // Get the last array element:
-z = arr.get( [ 0.0, 0.0 ], 3 );
-// returns [ 2.0, -2.0 ]
+z = arr.get( 3 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 2.0
+
+im = imagf( z );
+// returns -2.0
 ```
 
 When a `target`, `start`, and/or `end` index is negative, the respective index is determined relative to the last array element. The following example achieves the same behavior as the previous example:
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 4 );
 
@@ -595,23 +664,47 @@ arr.set( new Complex64( 3.0, -3.0 ), 2 );
 arr.set( new Complex64( 4.0, -4.0 ), 3 );
 
 // Get the third array element:
-var z = arr.get( [ 0.0, 0.0 ], 2 );
-// returns [ 3.0, -3.0 ]
+var z = arr.get( 2 );
+// returns <Complex64>
+
+var re = realf( z );
+// returns 3.0
+
+var im = imagf( z );
+// returns -3.0
 
 // Get the last array element:
-z = arr.get( [ 0.0, 0.0 ], 3 );
-// returns [ 4.0, -4.0 ]
+z = arr.get( 3 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 4.0
+
+im = imagf( z );
+// returns -4.0
 
 // Copy the first two elements to the last two elements using negative indices:
 arr.copyWithin( -2, -4, -2 );
 
 // Get the third array element:
-z = arr.get( [ 0.0, 0.0 ], 2 );
-// returns [ 1.0, -1.0 ]
+z = arr.get( 2 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 1.0
+
+im = imagf( z );
+// returns -1.0
 
 // Get the last array element:
-z = arr.get( [ 0.0, 0.0 ], 3 );
-// returns [ 2.0, -2.0 ]
+z = arr.get( 3 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 2.0
+
+im = imagf( z );
+// returns -2.0
 ```
 
 <a name="method-entries"></a>
@@ -622,8 +715,8 @@ Returns an iterator for iterating over array key-value pairs.
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
-var real = require( '@stdlib/complex-real' );
-var imag = require( '@stdlib/complex-imag' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = [
     new Complex64( 1.0, -1.0 ),
@@ -639,28 +732,28 @@ var it = arr.entries();
 var v = it.next().value;
 // returns [ 0, <Complex64> ]
 
-var re = real( v[ 1 ] );
+var re = realf( v[ 1 ] );
 // returns 1.0
 
-var im = imag( v[ 1 ] );
+var im = imagf( v[ 1 ] );
 // returns -1.0
 
 v = it.next().value;
 // returns [ 1, <Complex64> ]
 
-re = real( v[ 1 ] );
+re = realf( v[ 1 ] );
 // returns 2.0
 
-im = imag( v[ 1 ] );
+im = imagf( v[ 1 ] );
 // returns -2.0
 
 v = it.next().value;
 // returns [ 2, <Complex64> ]
 
-re = real( v[ 1 ] );
+re = realf( v[ 1 ] );
 // returns 3.0
 
-im = imag( v[ 1 ] );
+im = imagf( v[ 1 ] );
 // returns -3.0
 
 var bool = it.next().done;
@@ -669,13 +762,13 @@ var bool = it.next().done;
 
 <a name="method-get"></a>
 
-#### Complex64Array.prototype.get( \[out,] i )
+#### Complex64Array.prototype.get( i )
 
 Returns an array element located at position (index) `i`.
 
 ```javascript
-var real = require( '@stdlib/complex-real' );
-var imag = require( '@stdlib/complex-imag' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 10 );
 
@@ -686,32 +779,13 @@ arr.set( [ 1.0, -1.0 ], 0 );
 var z = arr.get( 0 );
 // returns <Complex64>
 
-var re = real( z );
+var re = realf( z );
 // returns 1.0
 
-var im = imag( z );
+var im = imagf( z );
 // returns -1.0
 ```
 
-By default, the method returns a [64-bit complex number][@stdlib/complex/float32]. To return real and imaginary components separately, provide an array-like `object` as the first argument.
-
-```javascript
-var arr = new Complex64Array( 10 );
-
-// Set the first element:
-arr.set( [ 1.0, -1.0 ], 0 );
-
-// Define an output array:
-var out = [ 0.0, 0.0 ];
-
-// Get the first element:
-var z = arr.get( out, 0 );
-// returns [ 1.0, -1.0 ]
-
-var bool = ( out === z );
-// returns true
-```
-
 If provided an out-of-bounds index, the method returns `undefined`.
 
 ```javascript
@@ -719,14 +793,6 @@ var arr = new Complex64Array( 10 );
 
 var z = arr.get( 100 );
 // returns undefined
-
-var out = [ 0.0, 0.0 ];
-
-z = arr.get( out, 100 );
-// returns undefined
-
-var bool = ( out === z );
-// returns false
 ```
 
 <a name="method-set"></a>
@@ -737,44 +803,74 @@ Sets one or more array elements.
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 10 );
 
 // Get the first element:
-var z = arr.get( [ 0.0, 0.0 ], 0 );
-// returns [ 0.0, 0.0 ]
+var z = arr.get( 0 );
+// returns <Complex64>
+
+var re = realf( z );
+// returns 0.0
+
+var im = imagf( z );
+// returns 0.0
 
 // Set the first element:
 arr.set( new Complex64( 1.0, -1.0 ) );
 
 // Get the first element:
-z = arr.get( [ 0.0, 0.0 ], 0 );
-// returns [ 1.0, -1.0 ]
+z = arr.get( 0 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 1.0
+
+im = imagf( z );
+// returns -1.0
 ```
 
 By default, the method sets array elements starting at position (index) `i = 0`. To set elements starting elsewhere in the array, provide an index argument `i`.
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 10 );
 
 // Get the fifth element:
-var z = arr.get( [ 0.0, 0.0 ], 4 );
-// returns [ 0.0, 0.0 ]
+var z = arr.get( 4 );
+// returns <Complex64>
+
+var re = realf( z );
+// returns 0.0
+
+var im = imagf( z );
+// returns 0.0
 
 // Set the fifth element:
 arr.set( new Complex64( 1.0, -1.0 ), 4 );
 
 // Get the fifth element:
-z = arr.get( [ 0.0, 0.0 ], 4 );
-// returns [ 1.0, -1.0 ]
+z = arr.get( 4 );
+// returns <Complex64>
+
+re = realf( z );
+// returns 1.0
+
+im = imagf( z );
+// returns -1.0
 ```
 
-In addition to providing a complex number, to set one or more array elements, provide an array-like `object` containing either complex numbers
+In addition to providing a complex number, to set one or more array elements, provide an array-like object containing either complex numbers
 
 ```javascript
 var Complex64 = require( '@stdlib/complex-float32' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 10 );
 
@@ -789,14 +885,22 @@ var buf = [
 arr.set( buf, 4 );
 
 // Get the sixth element:
-var z = arr.get( [ 0.0, 0.0 ], 5 );
-// returns [ 2.0, -2.0 ]
+var z = arr.get( 5 );
+// returns <Complex64>
+
+var re = realf( z );
+// returns 2.0
+
+var im = imagf( z );
+// returns -2.0
 ```
 
 or interleaved real and imaginary components
 
 ```javascript
 var Float32Array = require( '@stdlib/array-float32' );
+var realf = require( '@stdlib/complex-realf' );
+var imagf = require( '@stdlib/complex-imagf' );
 
 var arr = new Complex64Array( 10 );
 
@@ -807,8 +911,14 @@ var buf = new Float32Array( [ 1.0, -1.0, 2.0, -2.0, 3.0, -3.0 ] );
 arr.set( buf, 4 );
 
 // Get the sixth element:
-var z = arr.get( [ 0.0, 0.0 ], 5 );
-// returns [ 2.0, -2.0 ]
+var z = arr.get( 5 );
+// returns <Complex64>
+
+var re = realf( z );
+// returns 2.0
+
+var im = imagf( z );
+// returns -2.0
 ```
 
 A few notes:
@@ -855,15 +965,12 @@ var Complex64 = require( '@stdlib/complex-float32' );
 var Float32Array = require( '@stdlib/array-float32' );
 var Complex64Array = require( '@stdlib/array-complex64' );
 
-var arr;
-var out;
-
 // Create a complex array by specifying a length:
-out = new Complex64Array( 3 );
+var out = new Complex64Array( 3 );
 console.log( out );
 
 // Create a complex array from an array of complex numbers:
-arr = [
+var arr = [
     new Complex64( 1.0, -1.0 ),
     new Complex64( -3.14, 3.14 ),
     new Complex64( 0.5, 0.5 )
@@ -899,6 +1006,22 @@ console.log( out );
 
 <!-- /.references -->
 
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+* * *
+
+## See Also
+
+-   <span class="package-name">[`@stdlib/array/complex128`][@stdlib/array/complex128]</span><span class="delimiter">: </span><span class="description">Complex128Array.</span>
+-   <span class="package-name">[`@stdlib/complex/cmplx`][@stdlib/complex/cmplx]</span><span class="delimiter">: </span><span class="description">create a complex number.</span>
+-   <span class="package-name">[`@stdlib/complex/float32`][@stdlib/complex/float32]</span><span class="delimiter">: </span><span class="description">64-bit complex number.</span>
+
+</section>
+
+<!-- /.related -->
+
 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
 
 
@@ -912,6 +1035,10 @@ This package is part of [stdlib][stdlib], a standard library for JavaScript and
 
 For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib].
 
+#### Community
+
+[![Chat][chat-image]][chat-url]
+
 ---
 
 ## License
@@ -921,7 +1048,7 @@ See [LICENSE][stdlib-license].
 
 ## Copyright
 
-Copyright &copy; 2016-2021. The Stdlib [Authors][stdlib-authors].
+Copyright &copy; 2016-2022. The Stdlib [Authors][stdlib-authors].
 
 </section>
 
@@ -940,20 +1067,42 @@ Copyright &copy; 2016-2021. The Stdlib [Authors][stdlib-authors].
 [coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/array-complex64/main.svg
 [coverage-url]: https://codecov.io/github/stdlib-js/array-complex64?branch=main
 
-[dependencies-image]: https://img.shields.io/david/stdlib-js/array-complex64
+<!--
+
+[dependencies-image]: https://img.shields.io/david/stdlib-js/array-complex64.svg
 [dependencies-url]: https://david-dm.org/stdlib-js/array-complex64/main
 
+-->
+
+[umd]: https://github.com/umdjs/umd
+[es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+
+[deno-url]: https://github.com/stdlib-js/array-complex64/tree/deno
+[umd-url]: https://github.com/stdlib-js/array-complex64/tree/umd
+[esm-url]: https://github.com/stdlib-js/array-complex64/tree/esm
+
+[chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg
+[chat-url]: https://gitter.im/stdlib-js/stdlib/
+
 [stdlib]: https://github.com/stdlib-js/stdlib
 
 [stdlib-authors]: https://github.com/stdlib-js/stdlib/graphs/contributors
 
 [stdlib-license]: https://raw.githubusercontent.com/stdlib-js/array-complex64/main/LICENSE
 
-[@stdlib/array/typed]: https://github.com/stdlib-js/array-typed
+[@stdlib/array/typed]: https://www.npmjs.com/package/@stdlib/array-typed
+
+[@stdlib/array/buffer]: https://www.npmjs.com/package/@stdlib/array-buffer
+
+[@stdlib/complex/float32]: https://www.npmjs.com/package/@stdlib/complex-float32
+
+<!-- <related-links> -->
+
+[@stdlib/array/complex128]: https://www.npmjs.com/package/@stdlib/array-complex128
 
-[@stdlib/array/buffer]: https://github.com/stdlib-js/array-buffer
+[@stdlib/complex/cmplx]: https://www.npmjs.com/package/@stdlib/complex-cmplx
 
-[@stdlib/complex/float32]: https://github.com/stdlib-js/complex-float32
+<!-- </related-links> -->
 
 </section>