time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (3222B)

      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 # roundn
     22 
     23 > Round a complex number to the nearest multiple of `10^n`.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var croundn = require( '@stdlib/math/base/special/croundn' );
     31 ```
     32 
     33 #### croundn( \[out,] re, im, n )
     34 
     35 Rounds a `complex` number comprised of a **real** component `re` and an **imaginary** component `im` to the nearest multiple of `10^n`.
     36 
     37 ```javascript
     38 // Round components to 2 decimal places:
     39 var v = croundn( -3.141592653589793, 3.141592653589793, -2 );
     40 // returns [ -3.14, 3.14 ]
     41 
     42 // If n = 0, `croundn` behaves like `cround`:
     43 v = croundn( -3.141592653589793, 3.141592653589793, 0 );
     44 // returns [ -3.0, 3.0 ]
     45 
     46 // Round components to the nearest thousand:
     47 v = croundn( -12368.0, 12368.0, 3 );
     48 // returns [ -12000.0, 12000.0 ]
     49 
     50 v = croundn( NaN, NaN, 0 );
     51 // returns [ NaN, NaN ]
     52 ```
     53 
     54 By default, the function returns real and imaginary components as a two-element `array`. To avoid unnecessary memory allocation, the function supports providing an output (destination) object.
     55 
     56 ```javascript
     57 var Float32Array = require( '@stdlib/array/float32' );
     58 
     59 var out = new Float32Array( 2 );
     60 
     61 var v = croundn( out, -4.6, 5.5, 0 );
     62 // returns <Float32Array>[ -5.0, 6.0 ]
     63 
     64 var bool = ( v === out );
     65 // returns true
     66 ```
     67 
     68 </section>
     69 
     70 <!-- /.usage -->
     71 
     72 <section class="notes">
     73 
     74 ## Notes
     75 
     76 -   When operating on [floating-point numbers][ieee754] in bases other than `2`, rounding to specified digits can be **inexact**. For example,
     77 
     78     ```javascript
     79     var x = 0.2 + 0.1;
     80     // returns 0.30000000000000004
     81 
     82     // Should round components to 0.3:
     83     var v = croundn( x, x, -16 );
     84     // returns [ 0.3000000000000001, 0.3000000000000001 ]
     85     ```
     86 
     87 </section>
     88 
     89 <!-- /.notes -->
     90 
     91 <section class="examples">
     92 
     93 ## Examples
     94 
     95 <!-- eslint no-undef: "error" -->
     96 
     97 ```javascript
     98 var Complex128 = require( '@stdlib/complex/float64' );
     99 var randu = require( '@stdlib/random/base/randu' );
    100 var ceil = require( '@stdlib/math/base/special/ceil' );
    101 var real = require( '@stdlib/complex/real' );
    102 var imag = require( '@stdlib/complex/imag' );
    103 var croundn = require( '@stdlib/math/base/special/croundn' );
    104 
    105 var re;
    106 var im;
    107 var z;
    108 var o;
    109 var w;
    110 var n;
    111 var i;
    112 
    113 for ( i = 0; i < 100; i++ ) {
    114     re = ( randu()*100.0 ) - 50.0;
    115     im = ( randu()*100.0 ) - 50.0;
    116     z = new Complex128( re, im );
    117 
    118     n = ceil( randu()*5.0 );
    119     o = croundn( real(z), imag(z), -n );
    120     w = new Complex128( o[ 0 ], o[ 1 ] );
    121 
    122     console.log( 'roundn(%s,%s) = %s', z.toString(), n.toString(), w.toString() );
    123 }
    124 ```
    125 
    126 </section>
    127 
    128 <!-- /.examples -->
    129 
    130 <section class="links">
    131 
    132 [ieee754]: https://en.wikipedia.org/wiki/IEEE_754-1985
    133 
    134 </section>
    135 
    136 <!-- /.links -->