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