time-to-botec

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

README.md (4045B)

      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 # memoize
     22 
     23 > Memoize a function.
     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 memoize = require( '@stdlib/utils/memoize' );
     41 ```
     42 
     43 #### memoize( fcn\[, hashFunction] )
     44 
     45 Memoizes a function.
     46 
     47 ```javascript
     48 var randu = require( '@stdlib/random/base/randu' );
     49 
     50 function rand( n ) {
     51     return n * randu();
     52 }
     53 
     54 var memoized = memoize( rand );
     55 
     56 var v1 = memoized( 5 );
     57 var v2 = memoized( 5 );
     58 
     59 var bool = ( v1 === v2 );
     60 // returns true
     61 ```
     62 
     63 By default, the implementation serializes provided arguments as a `string` and stores results using the `string` as an identifier. To use a custom hash function, provide a hash function argument.
     64 
     65 ```javascript
     66 function add( obj ) {
     67     return obj.x + obj.y + obj.z;
     68 }
     69 
     70 obj = {
     71     'x': 3,
     72     'y': 4,
     73     'z': 5
     74 };
     75 
     76 // Default behavior...
     77 
     78 var memoized = memoize( add );
     79 
     80 var v1 = memoized( obj );
     81 // returns 12
     82 
     83 var str = obj.toString();
     84 // returns '[object Object]'
     85 
     86 var v2 = memoized.cache[ str ];
     87 // returns 12
     88 
     89 obj.x = 1000;
     90 
     91 var v3 = memoized( obj );
     92 // returns 12
     93 
     94 // Custom hash function...
     95 
     96 function hashFunction( args ) {
     97     return JSON.stringify( args );
     98 }
     99 
    100 memoized = memoize( add, hashFunction );
    101 
    102 v1 = memoized( obj );
    103 // returns 1009
    104 
    105 str = hashFunction( [ obj ] );
    106 // returns '[{"x":1000,"y":4,"z":5}]'
    107 
    108 v2 = memoized.cache[ str ];
    109 // returns 1009
    110 
    111 obj.x = 6;
    112 
    113 v3 = memoized( obj );
    114 // returns 15
    115 ```
    116 
    117 #### memoized.cache
    118 
    119 Results cache. Note that, while the property is **read-only**, cache contents may be modified independently of the memoized function.
    120 
    121 ```javascript
    122 function beep( x ) {
    123     throw new Error( 'boop' );
    124 }
    125 
    126 var memoized = memoize( beep );
    127 
    128 var cache = memoized.cache;
    129 // returns {}
    130 
    131 // Modify the cache:
    132 cache[ 'bop' ] = 'bip';
    133 
    134 var str = memoized( 'bop' );
    135 // returns 'bip'
    136 ```
    137 
    138 </section>
    139 
    140 <!-- /.usage -->
    141 
    142 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    143 
    144 <section class="notes">
    145 
    146 ## Notes
    147 
    148 -   The implementation does **not** set the `length` of the returned function. Accordingly, the returned function `length` is **always** `0`.
    149 -   The evaluation context is **always** `null`.
    150 
    151 </section>
    152 
    153 <!-- /.notes -->
    154 
    155 <!-- Package usage examples. -->
    156 
    157 <section class="examples">
    158 
    159 ## Examples
    160 
    161 <!-- eslint no-undef: "error" -->
    162 
    163 ```javascript
    164 var randu = require( '@stdlib/random/base/randu' );
    165 var floor = require( '@stdlib/math/base/special/floor' );
    166 var memoize = require( '@stdlib/utils/memoize' );
    167 
    168 var fcn;
    169 var n;
    170 var v;
    171 var i;
    172 
    173 function rand( n ) {
    174     return n * randu();
    175 }
    176 
    177 fcn = memoize( rand );
    178 
    179 for ( i = 0; i < 100; i++ ) {
    180     n = floor( randu() * 5 );
    181     v = fcn( n );
    182     console.log( 'rand(%d) = %d', n, v );
    183 }
    184 ```
    185 
    186 </section>
    187 
    188 <!-- /.examples -->
    189 
    190 <!-- 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. -->
    191 
    192 <section class="references">
    193 
    194 </section>
    195 
    196 <!-- /.references -->
    197 
    198 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    199 
    200 <section class="links">
    201 
    202 </section>
    203 
    204 <!-- /.links -->