time-to-botec

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

README.md (3681B)

      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 # forIn
     22 
     23 > Invoke a function for each own and inherited enumerable property of an object.
     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 forIn = require( '@stdlib/utils/for-in' );
     41 ```
     42 
     43 #### forIn( obj, fcn\[, thisArg ] )
     44 
     45 Invokes a `function` for each own and inherited enumerable property of an `object`.
     46 
     47 ```javascript
     48 function log( value, key ) {
     49     console.log( '%s: %d', key, value );
     50 }
     51 
     52 function Foo() {
     53     this.a = 1;
     54     this.b = 2;
     55     return this;
     56 }
     57 
     58 Foo.prototype.c = 3;
     59 Foo.prototype.d = 4;
     60 
     61 var obj = new Foo();
     62 
     63 forIn( obj, log );
     64 /* e.g., =>
     65     a: 1
     66     b: 2
     67     c: 3
     68     d: 4
     69 */
     70 ```
     71 
     72 The invoked `function` is provided three arguments:
     73 
     74 -   `value`: object property value
     75 -   `key`: object property
     76 -   `obj`: the input object
     77 
     78 To terminate iteration before visiting all properties, the provided function must explicitly return `false`.
     79 
     80 ```javascript
     81 function log( value, key ) {
     82     console.log( '%s: %d', key, value );
     83     return false;
     84 }
     85 
     86 var obj = {
     87     'a': 1,
     88     'b': 2,
     89     'c': 3,
     90     'd': 4
     91 };
     92 
     93 forIn( obj, log );
     94 // e.g., => a: 1
     95 ```
     96 
     97 To set the function execution context, provide a `thisArg`.
     98 
     99 ```javascript
    100 function sum( value ) {
    101     this.sum += value;
    102     this.count += 1;
    103 }
    104 
    105 var obj = {
    106     'a': 1,
    107     'b': 2,
    108     'c': 3,
    109     'd': 4
    110 };
    111 
    112 var context = {
    113     'sum': 0,
    114     'count': 0
    115 };
    116 
    117 forIn( obj, sum, context );
    118 
    119 var mean = context.sum / context.count;
    120 // returns 2.5
    121 ```
    122 
    123 </section>
    124 
    125 <!-- /.usage -->
    126 
    127 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    128 
    129 <section class="notes">
    130 
    131 ## Notes
    132 
    133 -   The function returns the input `object`.
    134 -   Property iteration order is **not** guaranteed.
    135 
    136 </section>
    137 
    138 <!-- /.notes -->
    139 
    140 <!-- Package usage examples. -->
    141 
    142 <section class="examples">
    143 
    144 ## Examples
    145 
    146 <!-- eslint no-undef: "error" -->
    147 
    148 ```javascript
    149 var fromCodePoint = require( '@stdlib/string/from-code-point' );
    150 var forIn = require( '@stdlib/utils/for-in' );
    151 
    152 function update( value, key, obj ) {
    153     console.log( '%s: %d', key, value );
    154     obj[ key ] *= value;
    155 }
    156 
    157 function Foo() {
    158     return this;
    159 }
    160 
    161 Foo.prototype.beep = 3.14;
    162 
    163 var obj;
    164 var key;
    165 var i;
    166 
    167 obj = new Foo();
    168 for ( i = 0; i < 26; i++ ) {
    169     key = fromCodePoint( 97 + i );
    170     obj[ key ] = i;
    171 }
    172 
    173 forIn( obj, update );
    174 console.log( obj );
    175 ```
    176 
    177 </section>
    178 
    179 <!-- /.examples -->
    180 
    181 <!-- 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. -->
    182 
    183 <section class="references">
    184 
    185 </section>
    186 
    187 <!-- /.references -->
    188 
    189 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    190 
    191 <section class="links">
    192 
    193 </section>
    194 
    195 <!-- /.links -->