time-to-botec

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

README.md (3743B)

      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 # Replace
     22 
     23 > Replace search occurrences with a replacement string.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var replace = require( '@stdlib/string/replace' );
     31 ```
     32 
     33 #### replace( str, search, newval )
     34 
     35 Replaces search occurrences with a replacement `string`.
     36 
     37 ```javascript
     38 var out = replace( 'beep', 'e', 'o' );
     39 // returns 'boop'
     40 ```
     41 
     42 If provided a `function` as the [third argument][replacer], the function is invoked for each match, and the function's return value is used as the replacement `string`.
     43 
     44 ```javascript
     45 function replacer( match, p1 ) {
     46     return '/' + p1 + '/';
     47 }
     48 var str = 'Oranges and lemons';
     49 var out = replace( str, /([^\s]+)/gi, replacer );
     50 // returns '/Oranges/ /and/ /lemons/'
     51 ```
     52 
     53 </section>
     54 
     55 <!-- /.usage -->
     56 
     57 <section class="notes">
     58 
     59 ## Notes
     60 
     61 -   The function has one notable difference from [`String.prototype.replace`][mdn]. When provided a `string` as the `search` value, the function replaces **all** occurrences. To remove only the first match, use a regular expression.
     62 
     63     ```javascript
     64     var out = replace( 'beep', /e/, 'o' );
     65     // returns 'boep'
     66     ```
     67 
     68 </section>
     69 
     70 <!-- /.notes -->
     71 
     72 <section class="examples">
     73 
     74 ## Examples
     75 
     76 <!-- eslint no-undef: "error" -->
     77 
     78 ```javascript
     79 var capitalize = require( '@stdlib/string/capitalize' );
     80 var replace = require( '@stdlib/string/replace' );
     81 
     82 var out;
     83 var str;
     84 
     85 out = replace( 'beep', 'e', 'o' );
     86 // returns 'boop'
     87 
     88 out = replace( 'Hello World', /world/i, 'Mr. President' );
     89 // returns 'Hello Mr. President'
     90 
     91 str = 'Oranges and lemons say the bells of St. Clement\'s';
     92 out = replace( str, /([^\s]*)/gi, replacer );
     93 // returns 'Oranges And Lemons Say The Bells Of St. Clement\'s'
     94 
     95 function replacer( match, p1 ) {
     96     return capitalize( p1 );
     97 }
     98 ```
     99 
    100 </section>
    101 
    102 <!-- /.examples -->
    103 
    104 * * *
    105 
    106 <section class="cli">
    107 
    108 ## CLI
    109 
    110 <section class="usage">
    111 
    112 ### Usage
    113 
    114 ```text
    115 Usage: replace [options] [<string>] --search=<string> --newval=<string>
    116 
    117 Options:
    118 
    119   -h,    --help                Print this message.
    120   -V,    --version             Print the package version.
    121          --search string       Search string.
    122          --newval string       Replacement string.
    123 ```
    124 
    125 </section>
    126 
    127 <!-- /.usage -->
    128 
    129 <section class="examples">
    130 
    131 ### Examples
    132 
    133 ```bash
    134 $ replace --search='/[eo]/' --newval=a beep
    135 baap
    136 ```
    137 
    138 To use as a [standard stream][standard-streams],
    139 
    140 ```bash
    141 $ echo -n 'boop' | replace --search='o' newval='e'
    142 beep
    143 ```
    144 
    145 </section>
    146 
    147 <!-- /.examples -->
    148 
    149 </section>
    150 
    151 <!-- /.cli -->
    152 
    153 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
    154 
    155 <section class="related">
    156 
    157 </section>
    158 
    159 <!-- /.related -->
    160 
    161 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    162 
    163 <section class="links">
    164 
    165 [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
    166 
    167 [replacer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_function_as_a_parameter
    168 
    169 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams
    170 
    171 </section>
    172 
    173 <!-- /.links -->