time-to-botec

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

README.md (3730B)

      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 # isSafeInteger
     22 
     23 > Test if a value is a number having a safe integer value.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var isSafeInteger = require( '@stdlib/assert/is-safe-integer' );
     31 ```
     32 
     33 #### isSafeInteger( value )
     34 
     35 Tests if a value is a `number` having a safe `integer` value.
     36 
     37 <!-- eslint-disable no-new-wrappers -->
     38 
     39 ```javascript
     40 var Number = require( '@stdlib/number/ctor' );
     41 
     42 var bool = isSafeInteger( 5.0 );
     43 // returns true
     44 
     45 bool = isSafeInteger( new Number( 5.0 ) );
     46 // returns true
     47 
     48 bool = isSafeInteger( 2.0e200 );
     49 // returns false
     50 
     51 bool = isSafeInteger( -3.14 );
     52 // returns false
     53 
     54 bool = isSafeInteger( null );
     55 // returns false
     56 ```
     57 
     58 #### isSafeInteger.isPrimitive( value )
     59 
     60 Tests if a `value` is a primitive `number` having a safe `integer` value.
     61 
     62 <!-- eslint-disable no-new-wrappers -->
     63 
     64 ```javascript
     65 var Number = require( '@stdlib/number/ctor' );
     66 
     67 var bool = isSafeInteger.isPrimitive( -3.0 );
     68 // returns true
     69 
     70 bool = isSafeInteger.isPrimitive( new Number( -3.0 ) );
     71 // returns false
     72 ```
     73 
     74 #### isSafeInteger.isObject( value )
     75 
     76 Tests if a `value` is a `Number` object having a safe `integer` value.
     77 
     78 <!-- eslint-disable no-new-wrappers -->
     79 
     80 ```javascript
     81 var Number = require( '@stdlib/number/ctor' );
     82 
     83 var bool = isSafeInteger.isObject( 3.0 );
     84 // returns false
     85 
     86 bool = isSafeInteger.isObject( new Number( 3.0 ) );
     87 // returns true
     88 ```
     89 
     90 </section>
     91 
     92 <!-- /.usage -->
     93 
     94 <section class="notes">
     95 
     96 ## Notes
     97 
     98 -   An integer valued number is "safe" when the number can be exactly represented as a [double-precision floating-point number][ieee754]. For example,
     99 
    100     ```javascript
    101     var MAX_SAFE_INTEGER = require( '@stdlib/constants/float64/max-safe-integer' );
    102     // returns 9007199254740991
    103 
    104     var x = 9007199254740992;
    105     // returns 9007199254740992
    106 
    107     var y = 9007199254740993;
    108     // returns 9007199254740992
    109 
    110     var bool = ( x === y );
    111     // returns true
    112     ```
    113 
    114     In this example, `x` and `y` should be distinct, but they are not due to constraints imposed by storing numeric values in [double-precision floating-point format][ieee754]. "Safe" integers are thus [double-precision floating-point numbers][ieee754] having integer values with unequivocal binary representations.
    115 
    116 </section>
    117 
    118 <!-- /.notes -->
    119 
    120 <section class="examples">
    121 
    122 ## Examples
    123 
    124 <!-- eslint-disable no-new-wrappers -->
    125 
    126 <!-- eslint no-undef: "error" -->
    127 
    128 ```javascript
    129 var Number = require( '@stdlib/number/ctor' );
    130 var isSafeInteger = require( '@stdlib/assert/is-safe-integer' );
    131 
    132 var bool = isSafeInteger( -5.0 );
    133 // returns true
    134 
    135 bool = isSafeInteger( 0.0 );
    136 // returns true
    137 
    138 bool = isSafeInteger( new Number( 5.0 ) );
    139 // returns true
    140 
    141 bool = isSafeInteger( 2.0e200 );
    142 // returns false
    143 
    144 bool = isSafeInteger( 5.256 );
    145 // returns false
    146 
    147 bool = isSafeInteger( 1.0/0.0 );
    148 // returns false
    149 
    150 bool = isSafeInteger( -1.0/0.0 );
    151 // returns false
    152 
    153 bool = isSafeInteger( NaN );
    154 // returns false
    155 
    156 bool = isSafeInteger( '5' );
    157 // returns false
    158 
    159 bool = isSafeInteger( null );
    160 // returns false
    161 ```
    162 
    163 </section>
    164 
    165 <!-- /.examples -->
    166 
    167 <section class="links">
    168 
    169 [ieee754]: https://en.wikipedia.org/wiki/IEEE_754-1985
    170 
    171 </section>
    172 
    173 <!-- /.links -->