README.md (31861B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 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 # Float64Array 22 23 > [Typed array][mdn-typed-array] constructor which returns a [typed array][mdn-typed-array] representing an array of double-precision floating-point numbers in the platform byte order. 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 Float64Array = require( '@stdlib/array/float64' ); 41 ``` 42 43 #### Float64Array() 44 45 A [typed array][mdn-typed-array] constructor which returns a [typed array][mdn-typed-array] representing an array of double-precision floating-point numbers in the platform byte order. 46 47 <!-- eslint-disable stdlib/require-globals --> 48 49 ```javascript 50 var arr = new Float64Array(); 51 // returns <Float64Array> 52 ``` 53 54 #### Float64Array( length ) 55 56 Returns a [typed array][mdn-typed-array] having a specified length. 57 58 <!-- eslint-disable stdlib/require-globals --> 59 60 ```javascript 61 var arr = new Float64Array( 5 ); 62 // returns <Float64Array>[ 0.0, 0.0, 0.0, 0.0, 0.0 ] 63 ``` 64 65 #### Float64Array( typedarray ) 66 67 Creates a [typed array][mdn-typed-array] from another [typed array][mdn-typed-array]. 68 69 <!-- eslint-disable stdlib/require-globals --> 70 71 ```javascript 72 var Float32Array = require( '@stdlib/array/float32' ); 73 74 var arr1 = new Float32Array( [ 0.5, 0.5, 0.5 ] ); 75 var arr2 = new Float64Array( arr1 ); 76 // returns <Float64Array>[ 0.5, 0.5, 0.5 ] 77 ``` 78 79 #### Float64Array( obj ) 80 81 Creates a [typed array][mdn-typed-array] from an array-like `object` or iterable. 82 83 <!-- eslint-disable stdlib/require-globals --> 84 85 ```javascript 86 var arr = new Float64Array( [ 0.5, 0.5, 0.5 ] ); 87 // returns <Float64Array>[ 0.5, 0.5, 0.5 ] 88 ``` 89 90 #### Float64Array( buffer\[, byteOffset\[, length]] ) 91 92 Returns a [typed array][mdn-typed-array] view of an [`ArrayBuffer`][@stdlib/array/buffer]. 93 94 <!-- eslint-disable stdlib/require-globals --> 95 96 ```javascript 97 var ArrayBuffer = require( '@stdlib/array/buffer' ); 98 99 var buf = new ArrayBuffer( 32 ); 100 var arr = new Float64Array( buf, 0, 4 ); 101 // returns <Float64Array>[ 0.0, 0.0, 0.0, 0.0 ] 102 ``` 103 104 * * * 105 106 ### Properties 107 108 <a name="static-prop-bytes-per-element"></a> 109 110 #### Float64Array.BYTES_PER_ELEMENT 111 112 Number of bytes per view element. 113 114 <!-- eslint-disable stdlib/require-globals --> 115 116 ```javascript 117 var nbytes = Float64Array.BYTES_PER_ELEMENT; 118 // returns 8 119 ``` 120 121 <a name="static-prop-name"></a> 122 123 #### Float64Array.name 124 125 [Typed array][mdn-typed-array] constructor name. 126 127 <!-- eslint-disable stdlib/require-globals --> 128 129 ```javascript 130 var str = Float64Array.name; 131 // returns 'Float64Array' 132 ``` 133 134 <a name="prop-buffer"></a> 135 136 #### Float64Array.prototype.buffer 137 138 **Read-only** property which returns the [`ArrayBuffer`][@stdlib/array/buffer] referenced by the [typed array][mdn-typed-array]. 139 140 <!-- eslint-disable stdlib/require-globals --> 141 142 ```javascript 143 var arr = new Float64Array( 5 ); 144 var buf = arr.buffer; 145 // returns <ArrayBuffer> 146 ``` 147 148 <a name="prop-byte-length"></a> 149 150 #### Float64Array.prototype.byteLength 151 152 **Read-only** property which returns the length (in bytes) of the [typed array][mdn-typed-array]. 153 154 <!-- eslint-disable stdlib/require-globals --> 155 156 ```javascript 157 var arr = new Float64Array( 5 ); 158 var byteLength = arr.byteLength; 159 // returns 40 160 ``` 161 162 <a name="prop-byte-offset"></a> 163 164 #### Float64Array.prototype.byteOffset 165 166 **Read-only** property which returns the offset (in bytes) of the [typed array][mdn-typed-array] from the start of its [`ArrayBuffer`][@stdlib/array/buffer]. 167 168 <!-- eslint-disable stdlib/require-globals --> 169 170 ```javascript 171 var arr = new Float64Array( 5 ); 172 var byteOffset = arr.byteOffset; 173 // returns 0 174 ``` 175 176 <a name="prop-bytes-per-element"></a> 177 178 #### Float64Array.prototype.BYTES_PER_ELEMENT 179 180 Number of bytes per view element. 181 182 <!-- eslint-disable stdlib/require-globals --> 183 184 ```javascript 185 var arr = new Float64Array( 5 ); 186 var nbytes = arr.BYTES_PER_ELEMENT; 187 // returns 8 188 ``` 189 190 <a name="prop-length"></a> 191 192 #### Float64Array.prototype.length 193 194 **Read-only** property which returns the number of view elements. 195 196 <!-- eslint-disable stdlib/require-globals --> 197 198 ```javascript 199 var arr = new Float64Array( 5 ); 200 var len = arr.length; 201 // returns 5 202 ``` 203 204 * * * 205 206 ### Methods 207 208 <a name="static-method-from"></a> 209 210 #### Float64Array.from( src\[, map\[, thisArg]] ) 211 212 Creates a new typed array from an array-like `object` or an iterable. 213 214 ```javascript 215 var arr = Float64Array.from( [ 1.0, -1.0 ] ); 216 // returns <Float64Array>[ 1.0, -1.0 ] 217 ``` 218 219 To invoke a function for each `src` value, provide a callback function. 220 221 ```javascript 222 function mapFcn( v ) { 223 return v * 2.0; 224 } 225 226 var arr = Float64Array.from( [ 1.0, -1.0 ], mapFcn ); 227 // returns <Float64Array>[ 2.0, -2.0 ] 228 ``` 229 230 A callback function is provided two arguments: 231 232 - `value`: source value 233 - `index`: source index 234 235 To set the callback execution context, provide a `thisArg`. 236 237 ```javascript 238 function mapFcn( v ) { 239 this.count += 1; 240 return v * 2.0; 241 } 242 243 var ctx = { 244 'count': 0 245 }; 246 247 var arr = Float64Array.from( [ 1.0, -1.0 ], mapFcn, ctx ); 248 // returns <Float64Array>[ 2.0, -2.0 ] 249 250 var n = ctx.count; 251 // returns 2 252 ``` 253 254 <a name="static-method-of"></a> 255 256 #### Float64Array.of( element0\[, element1\[, ...elementN]] ) 257 258 Creates a new typed array from a variable number of arguments. 259 260 ```javascript 261 var arr = Float64Array.of( 1.0, -1.0 ); 262 // returns <Float64Array>[ 1.0, -1.0 ] 263 ``` 264 265 <a name="method-copy-within"></a> 266 267 #### Float64Array.prototype.copyWithin( target, start\[, end] ) 268 269 Copies a sequence of elements within an array starting at `start` and ending at `end` (non-inclusive) to the position starting at `target`. 270 271 <!-- eslint-disable stdlib/require-globals --> 272 273 ```javascript 274 var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 275 276 // Copy the last two elements to the first two elements: 277 arr.copyWithin( 0, 3 ); 278 279 var v = arr[ 0 ]; 280 // returns 4.0 281 282 v = arr[ 1 ]; 283 // returns 5.0 284 ``` 285 286 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. 287 288 <!-- eslint-disable stdlib/require-globals --> 289 290 ```javascript 291 var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 292 293 // Copy the first two elements to the last two elements: 294 arr.copyWithin( 3, 0, 2 ); 295 296 var v = arr[ 3 ]; 297 // returns 1.0 298 299 v = arr[ 4 ]; 300 // returns 2.0 301 ``` 302 303 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: 304 305 <!-- eslint-disable stdlib/require-globals --> 306 307 ```javascript 308 var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 309 310 // Copy the first two elements to the last two elements: 311 arr.copyWithin( -2, -5, -3 ); 312 313 var v = arr[ 3 ]; 314 // returns 1.0 315 316 v = arr[ 4 ]; 317 // returns 2.0 318 ``` 319 320 <a name="method-entries"></a> 321 322 #### Float64Array.prototype.entries() 323 324 Returns an iterator for iterating over array key-value pairs. 325 326 <!-- eslint-disable stdlib/require-globals --> 327 328 ```javascript 329 var arr = new Float64Array( [ 1.0, 2.0 ] ); 330 331 // Create an iterator: 332 var it = arr.entries(); 333 334 // Iterate over key-value pairs... 335 var v = it.next().value; 336 // returns [ 0, 1.0 ] 337 338 v = it.next().value; 339 // returns [ 1, 2.0 ] 340 341 var bool = it.next().done; 342 // returns true 343 ``` 344 345 <a name="method-every"></a> 346 347 #### Float64Array.prototype.every( predicate\[, thisArg] ) 348 349 Tests whether all array elements pass a test implemented by a `predicate` function. 350 351 <!-- eslint-disable stdlib/require-globals --> 352 353 ```javascript 354 function predicate( v ) { 355 return ( v <= 1.0 ); 356 } 357 358 var arr = new Float64Array( [ 1.0, 2.0 ] ); 359 360 var bool = arr.every( predicate ); 361 // returns false 362 ``` 363 364 A `predicate` function is provided three arguments: 365 366 - `value`: array element 367 - `index`: array index 368 - `arr`: array on which the method is invoked 369 370 To set the callback execution context, provide a `thisArg`. 371 372 <!-- eslint-disable stdlib/require-globals --> 373 374 ```javascript 375 function predicate( v ) { 376 this.count += 1; 377 return ( v >= 1.0 ); 378 } 379 380 var ctx = { 381 'count': 0 382 }; 383 384 var arr = new Float64Array( [ 1.0, 2.0 ] ); 385 386 var bool = arr.every( predicate, ctx ); 387 // returns true 388 389 var n = ctx.count; 390 // returns 2 391 ``` 392 393 <a name="method-fill"></a> 394 395 #### Float64Array.prototype.fill( value\[, start\[, end]] ) 396 397 Fills an array from a `start` index to an `end` index (non-inclusive) with a provided `value`. 398 399 <!-- eslint-disable stdlib/require-globals --> 400 401 ```javascript 402 var arr = new Float64Array( 2 ); 403 404 // Set all array elements to the same value: 405 arr.fill( 2.0 ); 406 407 var v = arr[ 0 ]; 408 // returns 2.0 409 410 v = arr[ 1 ]; 411 // returns 2.0 412 413 // Set all array elements starting from the first index to the same value: 414 arr.fill( 3.0, 1 ); 415 416 v = arr[ 0 ]; 417 // returns 2.0 418 419 v = arr[ 1 ]; 420 // returns 3.0 421 422 // Set all array elements, except the last element, to the same value: 423 arr.fill( 4.0, 0, arr.length-1 ); 424 425 v = arr[ 0 ]; 426 // returns 4.0 427 428 v = arr[ 1 ]; 429 // returns 3.0 430 ``` 431 432 When a `start` and/or `end` index is negative, the respective index is determined relative to the last array element. 433 434 <!-- eslint-disable stdlib/require-globals --> 435 436 ```javascript 437 var arr = new Float64Array( 2 ); 438 439 // Set all array elements, except the last element, to the same value: 440 arr.fill( 2.0, -arr.length, -1 ); 441 442 var v = arr[ 0 ]; 443 // returns 2.0 444 445 v = arr[ 1 ]; 446 // returns 0.0 447 ``` 448 449 <a name="method-filter"></a> 450 451 #### Float64Array.prototype.filter( predicate\[, thisArg] ) 452 453 Creates a new array (of the same data type as the host array) which includes those elements for which a `predicate` function returns a truthy value. 454 455 <!-- eslint-disable stdlib/require-globals --> 456 457 ```javascript 458 function predicate( v ) { 459 return ( v >= 2.0 ); 460 } 461 462 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 463 464 var arr2 = arr1.filter( predicate ); 465 // returns <Float64Array>[ 2.0, 3.0 ] 466 ``` 467 468 If a `predicate` function does not return a truthy value for any array element, the method returns an empty array. 469 470 <!-- eslint-disable stdlib/require-globals --> 471 472 ```javascript 473 function predicate( v ) { 474 return ( v >= 10.0 ); 475 } 476 477 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 478 479 var arr2 = arr1.filter( predicate ); 480 // returns <Float64Array>[] 481 ``` 482 483 A `predicate` function is provided three arguments: 484 485 - `value`: array element 486 - `index`: array index 487 - `arr`: array on which the method is invoked 488 489 To set the callback execution context, provide a `thisArg`. 490 491 <!-- eslint-disable stdlib/require-globals --> 492 493 ```javascript 494 function predicate( v ) { 495 this.count += 1; 496 return ( v >= 2.0 ); 497 } 498 499 var ctx = { 500 'count': 0 501 }; 502 503 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 504 505 var arr2 = arr1.filter( predicate, ctx ); 506 507 var n = ctx.count; 508 // returns 3 509 ``` 510 511 <a name="method-find"></a> 512 513 #### Float64Array.prototype.find( predicate\[, thisArg] ) 514 515 Returns the first array element for which a provided `predicate` function returns a truthy value. 516 517 <!-- eslint-disable stdlib/require-globals --> 518 519 ```javascript 520 function predicate( v ) { 521 return ( v > 2.0 ); 522 } 523 524 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 525 526 var v = arr.find( predicate ); 527 // returns 3.0 528 ``` 529 530 If a `predicate` function does not return a truthy value for any array element, the method returns `undefined`. 531 532 <!-- eslint-disable stdlib/require-globals --> 533 534 ```javascript 535 function predicate( v ) { 536 return ( v < 1.0 ); 537 } 538 539 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 540 541 var v = arr.find( predicate ); 542 // returns undefined 543 ``` 544 545 A `predicate` function is provided three arguments: 546 547 - `value`: array element 548 - `index`: array index 549 - `arr`: array on which the method is invoked 550 551 To set the callback execution context, provide a `thisArg`. 552 553 <!-- eslint-disable stdlib/require-globals --> 554 555 ```javascript 556 function predicate( v ) { 557 this.count += 1; 558 return ( v > 2.0 ); 559 } 560 561 var ctx = { 562 'count': 0 563 }; 564 565 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 566 567 var v = arr.find( predicate, ctx ); 568 // returns 3.0 569 570 var n = ctx.count; 571 // returns 3 572 ``` 573 574 <a name="method-find-index"></a> 575 576 #### Float64Array.prototype.findIndex( predicate\[, thisArg] ) 577 578 Returns the index of the first array element for which a provided `predicate` function returns a truthy value. 579 580 <!-- eslint-disable stdlib/require-globals --> 581 582 ```javascript 583 function predicate( v ) { 584 return ( v >= 3.0 ); 585 } 586 587 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 588 589 var idx = arr.findIndex( predicate ); 590 // returns 2 591 ``` 592 593 If a `predicate` function does not return a truthy value for any array element, the method returns `-1`. 594 595 <!-- eslint-disable stdlib/require-globals --> 596 597 ```javascript 598 function predicate( v ) { 599 return ( v < 1.0 ); 600 } 601 602 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 603 604 var idx = arr.findIndex( predicate ); 605 // returns -1 606 ``` 607 608 A `predicate` function is provided three arguments: 609 610 - `value`: array element 611 - `index`: array index 612 - `arr`: array on which the method is invoked 613 614 To set the callback execution context, provide a `thisArg`. 615 616 <!-- eslint-disable stdlib/require-globals --> 617 618 ```javascript 619 function predicate( v ) { 620 this.count += 1; 621 return ( v >= 3.0 ); 622 } 623 624 var ctx = { 625 'count': 0 626 }; 627 628 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 629 630 var idx = arr.findIndex( predicate, ctx ); 631 // returns 2 632 633 var n = ctx.count; 634 // returns 3 635 ``` 636 637 <a name="method-for-each"></a> 638 639 #### Float64Array.prototype.forEach( fcn\[, thisArg] ) 640 641 Invokes a callback for each array element. 642 643 <!-- eslint-disable stdlib/require-globals --> 644 645 ```javascript 646 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 647 648 var str = ''; 649 650 function fcn( v, i ) { 651 str += i + ':' + v; 652 if ( i < arr.length-1 ) { 653 str += ' '; 654 } 655 } 656 657 arr.forEach( fcn ); 658 659 console.log( str ); 660 // => '0:1 1:2 2:3' 661 ``` 662 663 The callback is provided three arguments: 664 665 - `value`: array element 666 - `index`: array index 667 - `arr`: array on which the method is invoked 668 669 To set the callback execution context, provide a `thisArg`. 670 671 <!-- eslint-disable stdlib/require-globals --> 672 673 ```javascript 674 function fcn() { 675 this.count += 1; 676 } 677 678 var ctx = { 679 'count': 0 680 }; 681 682 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 683 684 arr.forEach( fcn, ctx ); 685 686 var n = ctx.count; 687 // returns 3 688 ``` 689 690 <a name="method-includes"></a> 691 692 #### Float64Array.prototype.includes( searchElement\[, fromIndex] ) 693 694 Returns a `boolean` indicating whether an array includes a search element. 695 696 <!-- eslint-disable stdlib/require-globals --> 697 698 ```javascript 699 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 700 701 var bool = arr.includes( 3.0 ); 702 // returns true 703 704 bool = arr.includes( 0.0 ); 705 // returns false 706 ``` 707 708 By default, the method searches the entire array (`fromIndex = 0`). To begin searching from a specific array index, provide a `fromIndex`. 709 710 <!-- eslint-disable stdlib/require-globals --> 711 712 ```javascript 713 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 714 715 var bool = arr.includes( 1.0, 1 ); 716 // returns false 717 ``` 718 719 When a `fromIndex` is negative, the starting index is resolved relative to the last array element. 720 721 <!-- eslint-disable stdlib/require-globals --> 722 723 ```javascript 724 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 725 726 bool = arr.includes( 1.0, -2 ); 727 // returns false 728 ``` 729 730 The method does **not** distinguish between signed and unsigned zero. 731 732 <a name="method-index-of"></a> 733 734 #### Float64Array.prototype.indexOf( searchElement\[, fromIndex] ) 735 736 Returns the index of the first array element strictly equal to a search element. 737 738 <!-- eslint-disable stdlib/require-globals --> 739 740 ```javascript 741 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 742 743 var idx = arr.indexOf( 3.0 ); 744 // returns 2 745 746 idx = arr.indexOf( 0.0 ); 747 // returns -1 748 ``` 749 750 By default, the method searches the entire array (`fromIndex = 0`). To begin searching from a specific array index, provide a `fromIndex`. 751 752 <!-- eslint-disable stdlib/require-globals --> 753 754 ```javascript 755 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 756 757 var idx = arr.indexOf( 1.0, 1 ); 758 // returns -1 759 ``` 760 761 When a `fromIndex` is negative, the starting index is resolved relative to the last array element. 762 763 <!-- eslint-disable stdlib/require-globals --> 764 765 ```javascript 766 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 767 768 var idx = arr.indexOf( 1.0, -2 ); 769 // returns -1 770 ``` 771 772 The method does **not** distinguish between signed and unsigned zero. 773 774 <a name="method-join"></a> 775 776 #### Float64Array.prototype.join( \[separator] ) 777 778 Serializes an array by joining all array elements as a string. 779 780 <!-- eslint-disable stdlib/require-globals --> 781 782 ```javascript 783 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 784 785 var str = arr.join(); 786 // returns '1,2,3' 787 ``` 788 789 By default, the method delineates array elements using a comma `,`. To specify a custom separator, provide a `separator` string. 790 791 <!-- eslint-disable stdlib/require-globals --> 792 793 ```javascript 794 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 795 796 var str = arr.join( '|' ); 797 // returns '1|2|3' 798 ``` 799 800 <a name="method-keys"></a> 801 802 #### Float64Array.prototype.keys() 803 804 Returns an iterator for iterating over array keys. 805 806 <!-- eslint-disable stdlib/require-globals --> 807 808 ```javascript 809 var arr = new Float64Array( [ 1.0, 2.0 ] ); 810 811 // Create an iterator: 812 var it = arr.keys(); 813 814 // Iterate over keys... 815 var v = it.next().value; 816 // returns 0 817 818 v = it.next().value; 819 // returns 1 820 821 var bool = it.next().done; 822 // returns true 823 ``` 824 825 <a name="method-last-index-of"></a> 826 827 #### Float64Array.prototype.lastIndexOf( searchElement\[, fromIndex] ) 828 829 Returns the index of the last array element strictly equal to a search element, iterating from right to left. 830 831 <!-- eslint-disable stdlib/require-globals --> 832 833 ```javascript 834 var arr = new Float64Array( [ 1.0, 0.0, 2.0, 0.0, 1.0 ] ); 835 836 var idx = arr.lastIndexOf( 0.0 ); 837 // returns 3 838 839 idx = arr.lastIndexOf( 3.0 ); 840 // returns -1 841 ``` 842 843 By default, the method searches the entire array (`fromIndex = -1`). To begin searching from a specific array index, provide a `fromIndex`. 844 845 <!-- eslint-disable stdlib/require-globals --> 846 847 ```javascript 848 var arr = new Float64Array( [ 1.0, 0.0, 2.0, 0.0, 1.0 ] ); 849 850 var idx = arr.lastIndexOf( 0.0, 2 ); 851 // returns 1 852 ``` 853 854 When a `fromIndex` is negative, the starting index is resolved relative to the last array element. 855 856 <!-- eslint-disable stdlib/require-globals --> 857 858 ```javascript 859 var arr = new Float64Array( [ 1.0, 0.0, 2.0, 0.0, 1.0 ] ); 860 861 var idx = arr.lastIndexOf( 0.0, -3 ); 862 // returns 1 863 ``` 864 865 The method does **not** distinguish between signed and unsigned zero. 866 867 <a name="method-map"></a> 868 869 #### Float64Array.prototype.map( fcn\[, thisArg] ) 870 871 Maps each array element to an element in a new array having the same data type as the host array. 872 873 <!-- eslint-disable stdlib/require-globals --> 874 875 ```javascript 876 function fcn( v ) { 877 return v * 2.0; 878 } 879 880 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 881 882 var arr2 = arr1.map( fcn ); 883 // returns <Float64Array>[ 2.0, 4.0, 6.0 ] 884 ``` 885 886 A callback is provided three arguments: 887 888 - `value`: array element 889 - `index`: array index 890 - `arr`: array on which the method is invoked 891 892 To set the callback execution context, provide a `thisArg`. 893 894 <!-- eslint-disable stdlib/require-globals --> 895 896 ```javascript 897 function fcn( v ) { 898 this.count += 1; 899 return v * 2.0; 900 } 901 902 var ctx = { 903 'count': 0 904 }; 905 906 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 907 908 var arr2 = arr1.map( fcn, ctx ); 909 910 var n = ctx.count; 911 // returns 3 912 ``` 913 914 <a name="method-reduce"></a> 915 916 #### Float64Array.prototype.reduce( fcn\[, initialValue] ) 917 918 Applies a function against an accumulator and each element in an array and returns the accumulated result. 919 920 <!-- eslint-disable stdlib/require-globals --> 921 922 ```javascript 923 function fcn( acc, v ) { 924 return acc + ( v*v ); 925 } 926 927 var arr = new Float64Array( [ 2.0, 1.0, 3.0 ] ); 928 929 var v = arr.reduce( fcn ); 930 // returns 12.0 931 ``` 932 933 If not provided an initial value, the method invokes a provided function with the first array element as the first argument and the second array element as the second argument. 934 935 If provided an initial value, the method invokes a provided function with the initial value as the first argument and the first array element as the second argument. 936 937 <!-- eslint-disable stdlib/require-globals --> 938 939 ```javascript 940 function fcn( acc, v ) { 941 return acc + ( v*v ); 942 } 943 944 var arr = new Float64Array( [ 2.0, 1.0, 3.0 ] ); 945 946 var v = arr.reduce( fcn, 0.0 ); 947 // returns 14.0 948 ``` 949 950 A callback is provided four arguments: 951 952 - `acc`: accumulated result 953 - `value`: array element 954 - `index`: array index 955 - `arr`: array on which the method is invoked 956 957 <a name="method-reduce-right"></a> 958 959 #### Float64Array.prototype.reduceRight( fcn\[, initialValue] ) 960 961 Applies a function against an accumulator and each element in an array and returns the accumulated result, iterating from right to left. 962 963 <!-- eslint-disable stdlib/require-globals --> 964 965 ```javascript 966 function fcn( acc, v ) { 967 return acc + ( v*v ); 968 } 969 970 var arr = new Float64Array( [ 2.0, 1.0, 3.0 ] ); 971 972 var v = arr.reduceRight( fcn ); 973 // returns 8.0 974 ``` 975 976 If not provided an initial value, the method invokes a provided function with the last array element as the first argument and the second-to-last array element as the second argument. 977 978 If provided an initial value, the method invokes a provided function with the initial value as the first argument and the last array element as the second argument. 979 980 <!-- eslint-disable stdlib/require-globals --> 981 982 ```javascript 983 function fcn( acc, v ) { 984 return acc + ( v*v ); 985 } 986 987 var arr = new Float64Array( [ 2.0, 1.0, 3.0 ] ); 988 989 var v = arr.reduce( fcn, 0.0 ); 990 // returns 14.0 991 ``` 992 993 A callback is provided four arguments: 994 995 - `acc`: accumulated result 996 - `value`: array element 997 - `index`: array index 998 - `arr`: array on which the method is invoked 999 1000 <a name="method-reverse"></a> 1001 1002 #### Float64Array.prototype.reverse() 1003 1004 Reverses an array **in-place** (thus mutating the array on which the method is invoked). 1005 1006 <!-- eslint-disable stdlib/require-globals --> 1007 1008 ```javascript 1009 var arr = new Float64Array( [ 2.0, 0.0, 3.0 ] ); 1010 1011 // Reverse the array: 1012 arr.reverse(); 1013 1014 var v = arr[ 0 ]; 1015 // returns 3.0 1016 1017 v = arr[ 1 ]; 1018 // returns 0.0 1019 1020 v = arr[ 2 ]; 1021 // returns 2.0 1022 ``` 1023 1024 <a name="method-set"></a> 1025 1026 #### Float64Array.prototype.set( arr\[, offset] ) 1027 1028 Sets array elements. 1029 1030 <!-- eslint-disable stdlib/require-globals --> 1031 1032 ```javascript 1033 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1034 // returns <Float64Array>[ 1.0, 2.0, 3.0 ] 1035 1036 // Set the first two array elements: 1037 arr.set( [ 4.0, 5.0 ] ); 1038 1039 var v = arr[ 0 ]; 1040 // returns 4.0 1041 1042 v = arr[ 1 ]; 1043 // returns 5.0 1044 ``` 1045 1046 By default, the method starts writing values at the first array index. To specify an alternative index, provide an index `offset`. 1047 1048 <!-- eslint-disable stdlib/require-globals --> 1049 1050 ```javascript 1051 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1052 // returns <Float64Array>[ 1.0, 2.0, 3.0 ] 1053 1054 // Set the last two array elements: 1055 arr.set( [ 4.0, 5.0 ], 1 ); 1056 1057 var v = arr[ 1 ]; 1058 // returns 4.0 1059 1060 v = arr[ 2 ]; 1061 // returns 5.0 1062 ``` 1063 1064 <a name="method-slice"></a> 1065 1066 #### Float64Array.prototype.slice( \[begin\[, end]] ) 1067 1068 Copies array elements to a new array with the same underlying data type as the host array. 1069 1070 <!-- eslint-disable stdlib/require-globals --> 1071 1072 ```javascript 1073 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1074 1075 var arr2 = arr1.slice(); 1076 1077 var bool = ( arr1 === arr2 ); 1078 // returns false 1079 1080 bool = ( arr1.buffer === arr2.buffer ); 1081 // returns false 1082 1083 var v = arr2[ 0 ]; 1084 // returns 1.0 1085 1086 v = arr2[ 1 ]; 1087 // returns 2.0 1088 1089 v = arr2[ 2 ]; 1090 // returns 3.0 1091 ``` 1092 1093 By default, the method copies elements beginning with the first array element. To specify an alternative array index at which to begin copying, provide a `begin` index (inclusive). 1094 1095 <!-- eslint-disable stdlib/require-globals --> 1096 1097 ```javascript 1098 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1099 1100 var arr2 = arr1.slice( 1 ); 1101 1102 var len = arr2.length; 1103 // returns 2 1104 1105 var v = arr2[ 0 ]; 1106 // returns 2.0 1107 1108 v = arr2[ 1 ]; 1109 // returns 3.0 1110 ``` 1111 1112 By default, the method copies all array elements after `begin`. To specify an alternative array index at which to end copying, provide an `end` index (exclusive). 1113 1114 <!-- eslint-disable stdlib/require-globals --> 1115 1116 ```javascript 1117 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1118 1119 var arr2 = arr1.slice( 0, 2 ); 1120 1121 var len = arr2.length; 1122 // returns 2 1123 1124 var v = arr2[ 0 ]; 1125 // returns 1.0 1126 1127 v = arr2[ 1 ]; 1128 // returns 2.0 1129 ``` 1130 1131 When a `begin` and/or `end` index is negative, the respective index is determined relative to the last array element. 1132 1133 <!-- eslint-disable stdlib/require-globals --> 1134 1135 ```javascript 1136 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1137 1138 var arr2 = arr1.slice( -arr1.length, -1 ); 1139 1140 var len = arr2.length; 1141 // returns 2 1142 1143 var v = arr2[ 0 ]; 1144 // returns 1.0 1145 1146 v = arr2[ 1 ]; 1147 // returns 2.0 1148 ``` 1149 1150 <a name="method-some"></a> 1151 1152 #### Float64Array.prototype.some( predicate\[, thisArg] ) 1153 1154 Tests whether at least one array element passes a test implemented by a `predicate` function. 1155 1156 <!-- eslint-disable stdlib/require-globals --> 1157 1158 ```javascript 1159 function predicate( v ) { 1160 return ( v >= 2.0 ); 1161 } 1162 1163 var arr = new Float64Array( [ 1.0, 2.0 ] ); 1164 1165 var bool = arr.some( predicate ); 1166 // returns true 1167 ``` 1168 1169 A `predicate` function is provided three arguments: 1170 1171 - `value`: array element 1172 - `index`: array index 1173 - `arr`: array on which the method is invoked 1174 1175 To set the callback execution context, provide a `thisArg`. 1176 1177 <!-- eslint-disable stdlib/require-globals --> 1178 1179 ```javascript 1180 function predicate( v ) { 1181 this.count += 1; 1182 return ( v >= 2.0 ); 1183 } 1184 1185 var ctx = { 1186 'count': 0 1187 }; 1188 1189 var arr = new Float64Array( [ 1.0, 1.0 ] ); 1190 1191 var bool = arr.some( predicate, ctx ); 1192 // returns false 1193 1194 var n = ctx.count; 1195 // returns 2 1196 ``` 1197 1198 <a name="method-sort"></a> 1199 1200 #### Float64Array.prototype.sort( \[compareFunction] ) 1201 1202 Sorts an array **in-place** (thus mutating the array on which the method is invoked). 1203 1204 <!-- eslint-disable stdlib/require-globals --> 1205 1206 ```javascript 1207 var arr = new Float64Array( [ 2.0, 3.0, 0.0 ] ); 1208 1209 // Sort the array (in ascending order): 1210 arr.sort(); 1211 1212 var v = arr[ 0 ]; 1213 // returns 0.0 1214 1215 v = arr[ 1 ]; 1216 // returns 2.0 1217 1218 v = arr[ 2 ]; 1219 // returns 3.0 1220 ``` 1221 1222 By default, the method sorts array elements in ascending order. To impose a custom order, provide a `compareFunction`. 1223 1224 <!-- eslint-disable stdlib/require-globals --> 1225 1226 ```javascript 1227 function descending( a, b ) { 1228 return b - a; 1229 } 1230 1231 var arr = new Float64Array( [ 2.0, 3.0, 0.0 ] ); 1232 1233 // Sort the array (in descending order): 1234 arr.sort( descending ); 1235 1236 var v = arr[ 0 ]; 1237 // returns 3.0 1238 1239 v = arr[ 1 ]; 1240 // returns 2.0 1241 1242 v = arr[ 2 ]; 1243 // returns 0.0 1244 ``` 1245 1246 The comparison function is provided two array elements, `a` and `b`, per invocation, and its return value determines the sort order as follows: 1247 1248 - If the comparison function returns a value **less** than zero, then the method sorts `a` to an index lower than `b` (i.e., `a` should come **before** `b`). 1249 - If the comparison function returns a value **greater** than zero, then the method sorts `a` to an index higher than `b` (i.e., `b` should come **before** `a`). 1250 - If the comparison function returns **zero**, then the relative order of `a` and `b` _should_ remain unchanged. 1251 1252 <a name="method-subarray"></a> 1253 1254 #### Float64Array.prototype.subarray( \[begin\[, end]] ) 1255 1256 Creates a new typed array view over the same underlying [`ArrayBuffer`][@stdlib/array/buffer] and with the same underlying data type as the host array. 1257 1258 <!-- eslint-disable stdlib/require-globals --> 1259 1260 ```javascript 1261 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1262 1263 var arr2 = arr1.subarray(); 1264 // returns <Float64Array>[ 1.0, 2.0, 3.0 ] 1265 1266 var bool = ( arr1.buffer === arr2.buffer ); 1267 // returns true 1268 ``` 1269 1270 By default, the method creates a typed array view beginning with the first array element. To specify an alternative array index at which to begin, provide a `begin` index (inclusive). 1271 1272 <!-- eslint-disable stdlib/require-globals --> 1273 1274 ```javascript 1275 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1276 1277 var arr2 = arr1.subarray( 1 ); 1278 // returns <Float64Array>[ 2.0, 3.0 ] 1279 1280 var bool = ( arr1.buffer === arr2.buffer ); 1281 // returns true 1282 ``` 1283 1284 By default, the method creates a typed array view which includes all array elements after `begin`. To limit the number of array elements after `begin`, provide an `end` index (exclusive). 1285 1286 <!-- eslint-disable stdlib/require-globals --> 1287 1288 ```javascript 1289 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1290 1291 var arr2 = arr1.subarray( 0, 2 ); 1292 // returns <Float64Array>[ 1.0, 2.0 ] 1293 1294 var bool = ( arr1.buffer === arr2.buffer ); 1295 // returns true 1296 ``` 1297 1298 When a `begin` and/or `end` index is negative, the respective index is determined relative to the last array element. 1299 1300 <!-- eslint-disable stdlib/require-globals --> 1301 1302 ```javascript 1303 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1304 1305 var arr2 = arr1.subarray( -arr1.length, -1 ); 1306 // returns <Float64Array>[ 1.0, 2.0 ] 1307 1308 var bool = ( arr1.buffer === arr2.buffer ); 1309 // returns true 1310 ``` 1311 1312 If the method is unable to resolve indices to a non-empty array subsequence, the method returns an empty typed array. 1313 1314 <!-- eslint-disable stdlib/require-globals --> 1315 1316 ```javascript 1317 var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1318 1319 var arr2 = arr1.subarray( 10, -1 ); 1320 // returns <Float64Array>[] 1321 ``` 1322 1323 <a name="method-to-locale-string"></a> 1324 1325 #### Float64Array.prototype.toLocaleString( \[locales\[, options]] ) 1326 1327 Serializes an array as a locale-specific `string`. 1328 1329 <!-- eslint-disable stdlib/require-globals --> 1330 1331 ```javascript 1332 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1333 1334 var str = arr.toLocaleString(); 1335 // returns '1,2,3' 1336 ``` 1337 1338 <a name="method-to-string"></a> 1339 1340 #### Float64Array.prototype.toString() 1341 1342 Serializes an array as a `string`. 1343 1344 <!-- eslint-disable stdlib/require-globals --> 1345 1346 ```javascript 1347 var arr = new Float64Array( [ 1.0, 2.0, 3.0 ] ); 1348 1349 var str = arr.toString(); 1350 // returns '1,2,3' 1351 ``` 1352 1353 <a name="method-values"></a> 1354 1355 #### Float64Array.prototype.values() 1356 1357 Returns an iterator for iterating over array elements. 1358 1359 <!-- eslint-disable stdlib/require-globals --> 1360 1361 ```javascript 1362 var arr = new Float64Array( [ 1.0, 2.0 ] ); 1363 1364 // Create an iterator: 1365 var it = arr.values(); 1366 1367 // Iterate over array elements... 1368 var v = it.next().value; 1369 // returns 1.0 1370 1371 v = it.next().value; 1372 // returns 2.0 1373 1374 var bool = it.next().done; 1375 // returns true 1376 ``` 1377 1378 </section> 1379 1380 <!-- /.usage --> 1381 1382 * * * 1383 1384 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 1385 1386 <section class="notes"> 1387 1388 </section> 1389 1390 <!-- /.notes --> 1391 1392 <!-- Package usage examples. --> 1393 1394 <section class="examples"> 1395 1396 ## Examples 1397 1398 <!-- eslint no-undef: "error" --> 1399 1400 ```javascript 1401 var randu = require( '@stdlib/random/base/randu' ); 1402 var ctor = require( '@stdlib/array/float64' ); 1403 1404 var arr; 1405 var i; 1406 1407 arr = new ctor( 10 ); 1408 for ( i = 0; i < arr.length; i++ ) { 1409 arr[ i ] = randu() * 100.0; 1410 } 1411 console.log( arr ); 1412 ``` 1413 1414 </section> 1415 1416 <!-- /.examples --> 1417 1418 <!-- 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. --> 1419 1420 <section class="references"> 1421 1422 </section> 1423 1424 <!-- /.references --> 1425 1426 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 1427 1428 <section class="links"> 1429 1430 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 1431 1432 [@stdlib/array/buffer]: https://www.npmjs.com/package/@stdlib/array/tree/main/buffer 1433 1434 </section> 1435 1436 <!-- /.links -->