time-to-botec

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

README.md (4361B)

      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 # Join Stream
     22 
     23 > [Transform stream][transform-stream] which joins streamed data.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var joinStream = require( '@stdlib/streams/node/join' );
     31 ```
     32 
     33 <a name="join-stream"></a>
     34 
     35 #### joinStream( \[options] )
     36 
     37 Creates a [transform stream][transform-stream] which joins streamed data.
     38 
     39 ```javascript
     40 var stdout = require( '@stdlib/streams/node/stdout' );
     41 
     42 var stream = joinStream();
     43 
     44 stream.pipe( stdout );
     45 
     46 stream.write( '1' );
     47 stream.write( '2' );
     48 stream.write( '3' );
     49 
     50 stream.end();
     51 
     52 // prints: 1\n2\n3
     53 ```
     54 
     55 The function accepts the following `options`:
     56 
     57 -   **sep**: separator used to join streamed data. Default: `'\n'`.
     58 -   **objectMode**: specifies whether a [stream][stream] should operate in object mode. Default: `false`.
     59 -   **encoding**: specifies how `Buffer` objects should be decoded to `strings`. Default: `null`.
     60 -   **highWaterMark**: specifies the `Buffer` level at which `write()` calls start returning `false`.
     61 -   **allowHalfOpen**: specifies whether a [stream][stream] should remain open even if one side ends. Default: `false`.
     62 -   **readableObjectMode**: specifies whether the readable side should be in object mode. Default: `false`.
     63 
     64 To set [stream][stream] `options`,
     65 
     66 ```javascript
     67 var opts = {
     68     'sep': ',',
     69     'objectMode': true,
     70     'encoding': 'utf8',
     71     'highWaterMark': 64,
     72     'allowHalfOpen': true,
     73     'readableObjectMode': false // overridden by `objectMode` option when `objectMode=true`
     74 };
     75 
     76 var stream = joinStream( opts );
     77 ```
     78 
     79 #### joinStream.factory( \[options] )
     80 
     81 Returns a `function` for creating [streams][transform-stream] which are identically configured according to provided `options`.
     82 
     83 ```javascript
     84 var opts = {
     85     'sep': '\t',
     86     'objectMode': true,
     87     'encoding': 'utf8',
     88     'highWaterMark': 64
     89 };
     90 
     91 var factory = joinStream.factory( opts );
     92 
     93 // Create 10 identically configured streams...
     94 var streams = [];
     95 var i;
     96 for ( i = 0; i < 10; i++ ) {
     97     streams.push( factory() );
     98 }
     99 ```
    100 
    101 This method accepts the same `options` as [`joinStream()`](#join-stream).
    102 
    103 #### joinStream.objectMode( \[options] )
    104 
    105 This method is a convenience function to create [streams][stream] which **always** operate in `objectMode`.
    106 
    107 ```javascript
    108 var stdout = require( '@stdlib/streams/node/stdout' );
    109 
    110 var stream = joinStream.objectMode({
    111     'sep': ','
    112 });
    113 
    114 stream.pipe( stdout );
    115 
    116 stream.write( 'a' );
    117 stream.write( 'b' );
    118 stream.write( 'c' );
    119 
    120 stream.end();
    121 
    122 // prints: a,b,c
    123 ```
    124 
    125 This method accepts the same `options` as [`joinStream()`](#join-stream); however, the method will **always** override the [objectMode][object-mode] option in `options`.
    126 
    127 </section>
    128 
    129 <!-- /.usage -->
    130 
    131 <section class="examples">
    132 
    133 ## Examples
    134 
    135 <!-- eslint no-undef: "error" -->
    136 
    137 ```javascript
    138 var splitStream = require( '@stdlib/streams/node/split' );
    139 var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
    140 var joinStream = require( '@stdlib/streams/node/join' );
    141 
    142 var inspect;
    143 var split;
    144 var join;
    145 var i;
    146 
    147 function log( chunk ) {
    148     console.log( chunk.toString() );
    149 }
    150 
    151 // Create a split stream for tab delimited data:
    152 split = splitStream({
    153     'sep': /\t/
    154 });
    155 
    156 // Create a stream to make newline delimited data:
    157 join = joinStream({
    158     'sep': '\n'
    159 });
    160 
    161 // Create a stream to inspect joined output:
    162 inspect = inspectStream( log );
    163 
    164 // Create a stream pipeline:
    165 split
    166     .pipe( join )
    167     .pipe( inspect );
    168 
    169 // Write values to the split stream...
    170 for ( i = 0; i < 10; i++ ) {
    171     split.write( i+'\t', 'utf8' );
    172 }
    173 split.end();
    174 ```
    175 
    176 </section>
    177 
    178 <!-- /.examples -->
    179 
    180 <section class="links">
    181 
    182 [stream]: https://nodejs.org/api/stream.html
    183 
    184 [transform-stream]: https://nodejs.org/api/stream.html
    185 
    186 [object-mode]: https://nodejs.org/api/stream.html#stream_object_mode
    187 
    188 </section>
    189 
    190 <!-- /.links -->