time-to-botec

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

README.md (3684B)

      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 # Promotion Rules
     22 
     23 > Return the ndarray [data type][@stdlib/ndarray/dtypes] with the smallest size and closest "kind" to which ndarray [data types][@stdlib/ndarray/dtypes] can be **safely** cast.
     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 promotionRules = require( '@stdlib/ndarray/promotion-rules' );
     41 ```
     42 
     43 #### promotionRules( \[dtype1, dtype2] )
     44 
     45 If provided [data types][@stdlib/ndarray/dtypes], returns the ndarray [data type][@stdlib/ndarray/dtypes] with the smallest size and closest "kind" to which ndarray [data types][@stdlib/ndarray/dtypes] can be **safely** cast.
     46 
     47 ```javascript
     48 var out = promotionRules( 'float32', 'uint32' );
     49 // returns 'float64'
     50 ```
     51 
     52 If a [data type][@stdlib/ndarray/dtypes] to which [data types][@stdlib/ndarray/dtypes] can be safely cast does **not** exist (or is not supported), the function returns `-1`.
     53 
     54 ```javascript
     55 var out = promotionRules( 'binary', 'generic' );
     56 // returns -1
     57 ```
     58 
     59 If not provided [data types][@stdlib/ndarray/dtypes], the function returns a promotion table.
     60 
     61 ```javascript
     62 var out = promotionRules();
     63 // returns {...}
     64 
     65 var f32 = out[ 'float32' ];
     66 // returns {...}
     67 
     68 var rule = f32[ 'uint32' ];
     69 // returns 'float64'
     70 ```
     71 
     72 If provided an unrecognized or unsupported `dtype`, the function returns `null`.
     73 
     74 ```javascript
     75 var out = promotionRules( 'foo', 'generic' );
     76 // returns null
     77 ```
     78 
     79 </section>
     80 
     81 <!-- /.usage -->
     82 
     83 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
     84 
     85 <section class="notes">
     86 
     87 </section>
     88 
     89 <!-- /.notes -->
     90 
     91 <!-- Package usage examples. -->
     92 
     93 <section class="examples">
     94 
     95 ## Examples
     96 
     97 <!-- eslint no-undef: "error" -->
     98 
     99 ```javascript
    100 var dtypes = require( '@stdlib/ndarray/dtypes' );
    101 var promotionRules = require( '@stdlib/ndarray/promotion-rules' );
    102 
    103 var DTYPES;
    104 var dt1;
    105 var dt2;
    106 var dt;
    107 var i;
    108 var j;
    109 
    110 // Get the list of supported ndarray data types:
    111 DTYPES = dtypes();
    112 
    113 // Print the promotion rule for each pair of ndarray data types...
    114 for ( i = 0; i < DTYPES.length; i++ ) {
    115     dt1 = DTYPES[ i ];
    116     for ( j = 0; j < DTYPES.length; j++ ) {
    117         dt2 = DTYPES[ j ];
    118         dt = promotionRules( dt1, dt2 );
    119         console.log( '(%s, %s) => %s', dt1, dt2, dt );
    120     }
    121 }
    122 ```
    123 
    124 </section>
    125 
    126 <!-- /.examples -->
    127 
    128 <!-- 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. -->
    129 
    130 <section class="references">
    131 
    132 </section>
    133 
    134 <!-- /.references -->
    135 
    136 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    137 
    138 <section class="links">
    139 
    140 [@stdlib/ndarray/dtypes]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/dtypes
    141 
    142 </section>
    143 
    144 <!-- /.links -->