time-to-botec

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

README.md (3659B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2019 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 # Open
     22 
     23 > Open a file.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 <!-- eslint-disable stdlib/no-redeclare -->
     30 
     31 ```javascript
     32 var open = require( '@stdlib/fs/open' );
     33 ```
     34 
     35 #### open( path\[, flags\[, mode]], clbk )
     36 
     37 Asynchronously opens a file.
     38 
     39 <!-- eslint-disable stdlib/no-redeclare -->
     40 
     41 ```javascript
     42 var closeSync = require( '@stdlib/fs/close' ).sync;
     43 
     44 open( __filename, onOpen );
     45 
     46 function onOpen( error, fd ) {
     47     if ( error ) {
     48         console.error( error.message );
     49     } else {
     50         closeSync( fd );
     51     }
     52 }
     53 ```
     54 
     55 The function has the same default parameter values as [`fs.open()`][node-fs].
     56 
     57 #### open.sync( file\[, flags\[, mode]] )
     58 
     59 Synchronously opens a `file`.
     60 
     61 <!-- eslint-disable stdlib/no-redeclare -->
     62 
     63 ```javascript
     64 var closeSync = require( '@stdlib/fs/close' ).sync;
     65 
     66 var fd = open.sync( __filename );
     67 if ( fd instanceof Error ) {
     68     console.error( fd.message );
     69 } else {
     70     closeSync( fd );
     71 }
     72 ```
     73 
     74 The function has the same default parameters as [`fs.openSync()`][node-fs].
     75 
     76 </section>
     77 
     78 <!-- /.usage -->
     79 
     80 <section class="notes">
     81 
     82 ## Notes
     83 
     84 -   The difference between this API and [`fs.openSync()`][node-fs] is that [`fs.openSync()`][node-fs] will throw if an `error` is encountered (e.g., if given a non-existent `path`) and this API will return an `error`. Hence, the following anti-pattern
     85 
     86     <!-- eslint-disable stdlib/no-redeclare -->
     87 
     88     ```javascript
     89     var fs = require( 'fs' );
     90 
     91     var fpath = '/path/to/file.js';
     92     var fd;
     93 
     94     // Check for existence to prevent an error being thrown...
     95     if ( fs.existsSync( fpath ) ) {
     96         fd = fs.readFileSync( fpath );
     97     }
     98     ```
     99 
    100     can be replaced by an approach which addresses existence via `error` handling.
    101 
    102     <!-- eslint-disable stdlib/no-redeclare -->
    103 
    104     ```javascript
    105     var open = require( '@stdlib/fs/open' );
    106 
    107     var fpath = '/path/to/file.js';
    108 
    109     // Explicitly handle the error...
    110     var fd = open.sync( fpath );
    111     if ( fd instanceof Error ) {
    112         // You choose what to do...
    113         console.error( fd.message );
    114     }
    115     ```
    116 
    117 </section>
    118 
    119 <!-- /.notes -->
    120 
    121 <section class="examples">
    122 
    123 ## Examples
    124 
    125 <!-- eslint-disable stdlib/no-redeclare -->
    126 
    127 <!-- eslint no-undef: "error" -->
    128 
    129 ```javascript
    130 var join = require( 'path' ).join;
    131 var closeSync = require( '@stdlib/fs/close' ).sync;
    132 var open = require( '@stdlib/fs/open' );
    133 
    134 /* Sync */
    135 
    136 var fd = open.sync( join( __dirname, 'package.json' ), 'r+' );
    137 // returns <number>
    138 
    139 if ( fd instanceof Error ) {
    140     console.error( fd.message );
    141 } else {
    142     closeSync( fd );
    143 }
    144 
    145 fd = open.sync( 'beepboop' );
    146 // returns <Error>
    147 
    148 /* Async */
    149 
    150 open( join( __dirname, 'package.json' ), onOpen );
    151 open( 'beepboop', onOpen );
    152 
    153 function onOpen( error, fd ) {
    154     if ( error ) {
    155         if ( error.code === 'ENOENT' ) {
    156             console.error( 'File does not exist.' );
    157         } else {
    158             console.error( error.message );
    159         }
    160     } else {
    161         closeSync( fd );
    162     }
    163 }
    164 ```
    165 
    166 </section>
    167 
    168 <!-- /.examples -->
    169 
    170 <section class="links">
    171 
    172 [node-fs]: https://nodejs.org/api/fs.html
    173 
    174 </section>
    175 
    176 <!-- /.links -->