time-to-botec

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

README.md (3361B)

      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 # Object Inverse
     22 
     23 > Invert an object, such that keys become values and values become keys.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var invert = require( '@stdlib/utils/object-inverse' );
     31 ```
     32 
     33 #### invert( obj\[, options] )
     34 
     35 Inverts an `object`, such that keys become values and values become keys.
     36 
     37 ```javascript
     38 var out = invert({
     39     'a': 'beep',
     40     'b': 'boop'
     41 });
     42 // returns { 'beep': 'a', 'boop': 'b' }
     43 ```
     44 
     45 The function accepts the following `options`:
     46 
     47 -   **duplicates**: `boolean` indicating whether to store keys mapped to duplicate values in `arrays`. Default: `true`.
     48 
     49 By default, keys mapped to duplicate values are stored in `arrays`.
     50 
     51 ```javascript
     52 var out = invert({
     53     'a': 'beep',
     54     'b': 'beep'
     55 });
     56 // returns { 'beep': [ 'a', 'b' ] }
     57 ```
     58 
     59 To **not** allow duplicates, set the `duplicates` option to `false`. The output `key-value` pair will be the `key` most recently inserted into the input `object`.
     60 
     61 ```javascript
     62 var obj = {};
     63 obj.a = 'beep';
     64 obj.b = 'boop';
     65 obj.c = 'beep'; // inserted after `a`
     66 
     67 var out = invert( obj, {
     68     'duplicates': false
     69 });
     70 // returns { 'beep': 'c', 'boop': 'b' }
     71 ```
     72 
     73 </section>
     74 
     75 <!-- /.usage -->
     76 
     77 <section class="notes">
     78 
     79 ## Notes
     80 
     81 -   Beware when providing `objects` having values which are themselves `objects`. This implementation relies on native `object` serialization (`#toString`) when converting values to keys.
     82 
     83     ```javascript
     84     var obj = {
     85         'a': [ 1, 2, 3 ],
     86         'b': {
     87             'c': 'd'
     88         }
     89     };
     90 
     91     var out = invert( obj );
     92     // returns { '1,2,3': 'a', '[object Object]': 'b' }
     93     ```
     94 
     95 -   Insertion order is not guaranteed, as `object` key enumeration is not specified according to the [ECMAScript specification][ecma-262-for-in]. In practice, however, most engines use insertion order to sort an `object`'s keys, thus allowing for deterministic inversion.
     96 
     97 </section>
     98 
     99 <!-- /.notes -->
    100 
    101 <section class="examples">
    102 
    103 ## Examples
    104 
    105 <!-- eslint no-undef: "error" -->
    106 
    107 ```javascript
    108 var randu = require( '@stdlib/random/base/randu' );
    109 var round = require( '@stdlib/math/base/special/round' );
    110 var invert = require( '@stdlib/utils/object-inverse' );
    111 
    112 var keys;
    113 var arr;
    114 var out;
    115 var i;
    116 
    117 // Create an array of random integers...
    118 arr = new Array( 1000 );
    119 for ( i = 0; i < arr.length; i++ ) {
    120     arr[ i ] = round( randu()*100.0 );
    121 }
    122 // Invert the array to determine value frequency...
    123 out = invert( arr );
    124 keys = Object.keys( out );
    125 for ( i = 0; i < keys.length; i++ ) {
    126     if ( out[ i ] ) {
    127         out[ i ] = out[ i ].length;
    128     } else {
    129         out[ i ] = 0;
    130     }
    131 }
    132 console.dir( out );
    133 ```
    134 
    135 </section>
    136 
    137 <!-- /.examples -->
    138 
    139 <section class="links">
    140 
    141 [ecma-262-for-in]: http://www.ecma-international.org/ecma-262/5.1/#sec-12.6.4
    142 
    143 </section>
    144 
    145 <!-- /.links -->