README.md (4959B)
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 # startsWith 22 23 > Test if a string starts with the characters of another string. 24 25 <section class="intro"> 26 27 </section> 28 29 <!-- /.intro --> 30 31 <section class="usage"> 32 33 ## Usage 34 35 ```javascript 36 var startsWith = require( '@stdlib/string/starts-with' ); 37 ``` 38 39 #### startsWith( str, search\[, position] ) 40 41 Tests if a `string` starts with the characters of another `string`. 42 43 ```javascript 44 var str = 'To be, or not to be, that is the question.'; 45 46 var bool = startsWith( str, 'To be' ); 47 // returns true 48 49 bool = startsWith( str, 'to be' ); 50 // returns false 51 ``` 52 53 By default, the function searches from the beginning of the input `string`. To search from a different character index, provide a `position` value (zero-based). If provided a negative `position`, the start index is determined relative to the string end (`pos = str.length + position`). 54 55 ```javascript 56 var str = 'Remember the story I used to tell you when you were a boy?'; 57 58 var bool = startsWith( str, 'the story' ); 59 // returns false 60 61 bool = startsWith( str, 'the story', 9 ); 62 // returns true 63 64 bool = startsWith( str, 'you', -15 ); 65 // returns true 66 ``` 67 68 If provided an empty `search` string, the function **always** returns `true`. 69 70 ```javascript 71 var str = 'beep boop'; 72 73 var bool = startsWith( str, '' ); 74 // returns true 75 ``` 76 77 </section> 78 79 <!-- /.usage --> 80 81 <section class="examples"> 82 83 ## Examples 84 85 <!-- eslint no-undef: "error" --> 86 87 ```javascript 88 var startsWith = require( '@stdlib/string/starts-with' ); 89 90 var bool; 91 var str; 92 93 str = 'Fair is foul, and foul is fair, hover through fog and filthy air'; 94 95 bool = startsWith( str, 'Fair' ); 96 // returns true 97 98 bool = startsWith( str, 'fair' ); 99 // returns false 100 101 bool = startsWith( str, 'foul', 8 ); 102 // returns true 103 104 bool = startsWith( str, 'filthy', -10 ); 105 // returns true 106 ``` 107 108 </section> 109 110 <!-- /.examples --> 111 112 * * * 113 114 <section class="cli"> 115 116 ## CLI 117 118 <section class="usage"> 119 120 ### Usage 121 122 ```text 123 Usage: starts-with [options] --search=<string> [<string>] 124 125 Options: 126 127 -h, --help Print this message. 128 -V, --version Print the package version. 129 --search string Search string. 130 --pos int Search position. 131 --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. 132 ``` 133 134 </section> 135 136 <!-- /.usage --> 137 138 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 139 140 <section class="notes"> 141 142 ### Notes 143 144 - If the split separator is a [regular expression][mdn-regexp], ensure that the `split` option is either properly escaped or enclosed in quotes. 145 146 ```bash 147 # Not escaped... 148 $ echo -n $'Hello, World!\nBeep Boop Baz' | starts-with --search=Beep --split /\r?\n/ 149 150 # Escaped... 151 $ echo -n $'Hello, World!\nBeep Boop Baz' | starts-with --search=Beep --split /\\r?\\n/ 152 ``` 153 154 - The implementation ignores trailing delimiters. 155 156 </section> 157 158 </section> 159 160 <!-- /.notes --> 161 162 <section class="examples"> 163 164 ### Examples 165 166 ```bash 167 $ starts-with --search=be beep 168 true 169 ``` 170 171 To use as a [standard stream][standard-streams], 172 173 ```bash 174 $ echo -n 'boop' | starts-with --search=bo 175 true 176 ``` 177 178 By default, when used as a [standard stream][standard-streams], the implementation assumes newline-delimited data. To specify an alternative delimiter, set the `split` option. 179 180 ```bash 181 $ echo -n 'Hello, World!\tBeep Boop' | starts-with --search=Beep --split '\t' 182 false 183 true 184 ``` 185 186 </section> 187 188 <!-- /.examples --> 189 190 </section> 191 192 <!-- /.cli --> 193 194 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 195 196 <section class="related"> 197 198 * * * 199 200 ## See Also 201 202 - <span class="package-name">[`@stdlib/string/ends-with`][@stdlib/string/ends-with]</span><span class="delimiter">: </span><span class="description">test if a string ends with the characters of another string.</span> 203 204 </section> 205 206 <!-- /.related --> 207 208 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 209 210 <section class="links"> 211 212 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams 213 214 [mdn-regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions 215 216 <!-- <related-links> --> 217 218 [@stdlib/string/ends-with]: https://github.com/stdlib-js/string/tree/main/ends-with 219 220 <!-- </related-links> --> 221 222 </section> 223 224 <!-- /.links -->