README.md (17158B)
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 # String Manipulation 22 23 [![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] --> 24 25 > String manipulation functions. 26 27 <section class="installation"> 28 29 ## Installation 30 31 ```bash 32 npm install @stdlib/string 33 ``` 34 35 </section> 36 37 <section class="usage"> 38 39 ## Usage 40 41 ```javascript 42 var string = require( '@stdlib/string' ); 43 ``` 44 45 #### string 46 47 Namespace containing string manipulation functions. 48 49 ```javascript 50 var str = string; 51 // returns {...} 52 ``` 53 54 The namespace exposes the following string manipulation functions: 55 56 <!-- <toc pattern="*"> --> 57 58 <div class="namespace-toc"> 59 60 - <span class="signature">[`acronym( str[, options] )`][@stdlib/string/acronym]</span><span class="delimiter">: </span><span class="description">generate an acronym for a given string.</span> 61 - <span class="signature">[`camelcase( str )`][@stdlib/string/camelcase]</span><span class="delimiter">: </span><span class="description">convert a string to camel case.</span> 62 - <span class="signature">[`capitalize( str )`][@stdlib/string/capitalize]</span><span class="delimiter">: </span><span class="description">capitalize the first character in a string.</span> 63 - <span class="signature">[`codePointAt( string, position[, backward] )`][@stdlib/string/code-point-at]</span><span class="delimiter">: </span><span class="description">return a Unicode code point from a string at a specified position.</span> 64 - <span class="signature">[`constantcase( str )`][@stdlib/string/constantcase]</span><span class="delimiter">: </span><span class="description">returns a string converted to a constant case.</span> 65 - <span class="signature">[`endsWith( str, search[, len] )`][@stdlib/string/ends-with]</span><span class="delimiter">: </span><span class="description">test if a string ends with the characters of another string.</span> 66 - <span class="signature">[`fromCodePoint( pt1[, pt2[, pt3[, ...]]] )`][@stdlib/string/from-code-point]</span><span class="delimiter">: </span><span class="description">create a string from a sequence of Unicode code points.</span> 67 - <span class="signature">[`kebabcase( str )`][@stdlib/string/kebabcase]</span><span class="delimiter">: </span><span class="description">convert a string to kebab case.</span> 68 - <span class="signature">[`lpad( str, len[, pad] )`][@stdlib/string/left-pad]</span><span class="delimiter">: </span><span class="description">left pad a string.</span> 69 - <span class="signature">[`ltrimN( str, n[, chars] )`][@stdlib/string/left-trim-n]</span><span class="delimiter">: </span><span class="description">trim `n` characters from the end of a string.</span> 70 - <span class="signature">[`ltrim( str )`][@stdlib/string/left-trim]</span><span class="delimiter">: </span><span class="description">trim whitespace characters from the beginning of a string.</span> 71 - <span class="signature">[`lowercase( str )`][@stdlib/string/lowercase]</span><span class="delimiter">: </span><span class="description">convert a string to lowercase.</span> 72 - <span class="signature">[`nextGraphemeClusterBreak( string[, fromIndex] )`][@stdlib/string/next-grapheme-cluster-break]</span><span class="delimiter">: </span><span class="description">return the next extended grapheme cluster break in a string after a specified position.</span> 73 - <span class="signature">[`numGraphemeClusters( str )`][@stdlib/string/num-grapheme-clusters]</span><span class="delimiter">: </span><span class="description">return the number of grapheme clusters in a string.</span> 74 - <span class="signature">[`pad( str, len[, options] )`][@stdlib/string/pad]</span><span class="delimiter">: </span><span class="description">pad a string.</span> 75 - <span class="signature">[`pascalcase( str )`][@stdlib/string/pascalcase]</span><span class="delimiter">: </span><span class="description">convert a string to Pascal case.</span> 76 - <span class="signature">[`percentEncode( str )`][@stdlib/string/percent-encode]</span><span class="delimiter">: </span><span class="description">percent-encode a UTF-16 encoded string according to RFC 3986.</span> 77 - <span class="signature">[`prevGraphemeClusterBreak( string[, fromIndex] )`][@stdlib/string/prev-grapheme-cluster-break]</span><span class="delimiter">: </span><span class="description">return the previous extended grapheme cluster break in a string before a specified position.</span> 78 - <span class="signature">[`removeFirst( str[, n] )`][@stdlib/string/remove-first]</span><span class="delimiter">: </span><span class="description">remove the first character(s) of a string.</span> 79 - <span class="signature">[`removeLast( str[, n] )`][@stdlib/string/remove-last]</span><span class="delimiter">: </span><span class="description">remove the last character(s) of a string.</span> 80 - <span class="signature">[`removePunctuation( str )`][@stdlib/string/remove-punctuation]</span><span class="delimiter">: </span><span class="description">remove punctuation characters from a string.</span> 81 - <span class="signature">[`removeUTF8BOM( str )`][@stdlib/string/remove-utf8-bom]</span><span class="delimiter">: </span><span class="description">remove a UTF-8 byte order mark (BOM) from the beginning of a string.</span> 82 - <span class="signature">[`removeWords( str, words[, ignoreCase] )`][@stdlib/string/remove-words]</span><span class="delimiter">: </span><span class="description">remove a list of words from a string.</span> 83 - <span class="signature">[`repeat( str, n )`][@stdlib/string/repeat]</span><span class="delimiter">: </span><span class="description">repeat a string a specified number of times and return the concatenated result.</span> 84 - <span class="signature">[`replace( str, search, newval )`][@stdlib/string/replace]</span><span class="delimiter">: </span><span class="description">replace search occurrences with a replacement string.</span> 85 - <span class="signature">[`reverseString( str )`][@stdlib/string/reverse]</span><span class="delimiter">: </span><span class="description">reverse a string.</span> 86 - <span class="signature">[`rpad( str, len[, pad] )`][@stdlib/string/right-pad]</span><span class="delimiter">: </span><span class="description">right pad a string.</span> 87 - <span class="signature">[`rtrimN( str, n[, chars] )`][@stdlib/string/right-trim-n]</span><span class="delimiter">: </span><span class="description">trim `n` characters from the end of a string.</span> 88 - <span class="signature">[`rtrim( str )`][@stdlib/string/right-trim]</span><span class="delimiter">: </span><span class="description">trim whitespace characters from the end of a string.</span> 89 - <span class="signature">[`snakecase( str )`][@stdlib/string/snakecase]</span><span class="delimiter">: </span><span class="description">convert a string to snake case.</span> 90 - <span class="signature">[`splitGraphemeClusters( str )`][@stdlib/string/split-grapheme-clusters]</span><span class="delimiter">: </span><span class="description">split a string by its grapheme cluster breaks.</span> 91 - <span class="signature">[`startcase( str )`][@stdlib/string/startcase]</span><span class="delimiter">: </span><span class="description">capitalize the first letter of each word in a string.</span> 92 - <span class="signature">[`startsWith( str, search[, position] )`][@stdlib/string/starts-with]</span><span class="delimiter">: </span><span class="description">test if a string starts with the characters of another string.</span> 93 - <span class="signature">[`substringAfterLast`][@stdlib/string/substring-after-last]</span><span class="delimiter">: </span><span class="description">return the part of a string after the last occurrence of a specified substring.</span> 94 - <span class="signature">[`substringAfter( str, search[, fromIndex] )`][@stdlib/string/substring-after]</span><span class="delimiter">: </span><span class="description">return the part of a string after a specified substring.</span> 95 - <span class="signature">[`substringBeforeLast( str, search )`][@stdlib/string/substring-before-last]</span><span class="delimiter">: </span><span class="description">return the part of a string before the last occurrence of a specified substring.</span> 96 - <span class="signature">[`substringBefore( str, search )`][@stdlib/string/substring-before]</span><span class="delimiter">: </span><span class="description">return the part of a string before a specified substring.</span> 97 - <span class="signature">[`trim( str )`][@stdlib/string/trim]</span><span class="delimiter">: </span><span class="description">trim whitespace characters from the beginning and end of a string.</span> 98 - <span class="signature">[`truncateMiddle( str, len[, seq] )`][@stdlib/string/truncate-middle]</span><span class="delimiter">: </span><span class="description">truncate a string in the middle to a specified length.</span> 99 - <span class="signature">[`truncate( str, len[, ending] )`][@stdlib/string/truncate]</span><span class="delimiter">: </span><span class="description">truncate a string to a specified length.</span> 100 - <span class="signature">[`uncapitalize( str )`][@stdlib/string/uncapitalize]</span><span class="delimiter">: </span><span class="description">uncapitalize the first character of a string.</span> 101 - <span class="signature">[`uppercase( str )`][@stdlib/string/uppercase]</span><span class="delimiter">: </span><span class="description">convert a string to uppercase.</span> 102 - <span class="signature">[`utf16ToUTF8Array( str )`][@stdlib/string/utf16-to-utf8-array]</span><span class="delimiter">: </span><span class="description">convert a UTF-16 encoded string to an array of integers using UTF-8 encoding.</span> 103 104 </div> 105 106 <!-- </toc> --> 107 108 </section> 109 110 <!-- /.usage --> 111 112 <section class="examples"> 113 114 ## Examples 115 116 <!-- TODO: better examples --> 117 118 <!-- eslint no-undef: "error" --> 119 120 ```javascript 121 var getKeys = require( '@stdlib/utils/keys' ); 122 var string = require( '@stdlib/string' ); 123 124 console.log( getKeys( string ) ); 125 ``` 126 127 </section> 128 129 <!-- /.examples --> 130 131 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 132 133 <section class="related"> 134 135 </section> 136 137 <!-- /.related --> 138 139 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 140 141 142 <section class="main-repo" > 143 144 * * * 145 146 ## Notice 147 148 This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. 149 150 For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. 151 152 #### Community 153 154 [![Chat][chat-image]][chat-url] 155 156 --- 157 158 ## License 159 160 See [LICENSE][stdlib-license]. 161 162 163 ## Copyright 164 165 Copyright © 2016-2022. The Stdlib [Authors][stdlib-authors]. 166 167 </section> 168 169 <!-- /.stdlib --> 170 171 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 172 173 <section class="links"> 174 175 [npm-image]: http://img.shields.io/npm/v/@stdlib/string.svg 176 [npm-url]: https://npmjs.org/package/@stdlib/string 177 178 [test-image]: https://github.com/stdlib-js/string/actions/workflows/test.yml/badge.svg?branch=v0.0.14 179 [test-url]: https://github.com/stdlib-js/string/actions/workflows/test.yml?query=branch:v0.0.14 180 181 [coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/string/main.svg 182 [coverage-url]: https://codecov.io/github/stdlib-js/string?branch=main 183 184 <!-- 185 186 [dependencies-image]: https://img.shields.io/david/stdlib-js/string.svg 187 [dependencies-url]: https://david-dm.org/stdlib-js/string/main 188 189 --> 190 191 [chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg 192 [chat-url]: https://gitter.im/stdlib-js/stdlib/ 193 194 [stdlib]: https://github.com/stdlib-js/stdlib 195 196 [stdlib-authors]: https://github.com/stdlib-js/stdlib/graphs/contributors 197 198 [umd]: https://github.com/umdjs/umd 199 [es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules 200 201 [deno-url]: https://github.com/stdlib-js/string/tree/deno 202 [umd-url]: https://github.com/stdlib-js/string/tree/umd 203 [esm-url]: https://github.com/stdlib-js/string/tree/esm 204 [branches-url]: https://github.com/stdlib-js/string/blob/main/branches.md 205 206 [stdlib-license]: https://raw.githubusercontent.com/stdlib-js/string/main/LICENSE 207 208 <!-- <toc-links> --> 209 210 [@stdlib/string/acronym]: https://github.com/stdlib-js/string/tree/main/acronym 211 212 [@stdlib/string/camelcase]: https://github.com/stdlib-js/string/tree/main/camelcase 213 214 [@stdlib/string/capitalize]: https://github.com/stdlib-js/string/tree/main/capitalize 215 216 [@stdlib/string/code-point-at]: https://github.com/stdlib-js/string/tree/main/code-point-at 217 218 [@stdlib/string/constantcase]: https://github.com/stdlib-js/string/tree/main/constantcase 219 220 [@stdlib/string/ends-with]: https://github.com/stdlib-js/string/tree/main/ends-with 221 222 [@stdlib/string/from-code-point]: https://github.com/stdlib-js/string/tree/main/from-code-point 223 224 [@stdlib/string/kebabcase]: https://github.com/stdlib-js/string/tree/main/kebabcase 225 226 [@stdlib/string/left-pad]: https://github.com/stdlib-js/string/tree/main/left-pad 227 228 [@stdlib/string/left-trim-n]: https://github.com/stdlib-js/string/tree/main/left-trim-n 229 230 [@stdlib/string/left-trim]: https://github.com/stdlib-js/string/tree/main/left-trim 231 232 [@stdlib/string/lowercase]: https://github.com/stdlib-js/string/tree/main/lowercase 233 234 [@stdlib/string/next-grapheme-cluster-break]: https://github.com/stdlib-js/string/tree/main/next-grapheme-cluster-break 235 236 [@stdlib/string/num-grapheme-clusters]: https://github.com/stdlib-js/string/tree/main/num-grapheme-clusters 237 238 [@stdlib/string/pad]: https://github.com/stdlib-js/string/tree/main/pad 239 240 [@stdlib/string/pascalcase]: https://github.com/stdlib-js/string/tree/main/pascalcase 241 242 [@stdlib/string/percent-encode]: https://github.com/stdlib-js/string/tree/main/percent-encode 243 244 [@stdlib/string/prev-grapheme-cluster-break]: https://github.com/stdlib-js/string/tree/main/prev-grapheme-cluster-break 245 246 [@stdlib/string/remove-first]: https://github.com/stdlib-js/string/tree/main/remove-first 247 248 [@stdlib/string/remove-last]: https://github.com/stdlib-js/string/tree/main/remove-last 249 250 [@stdlib/string/remove-punctuation]: https://github.com/stdlib-js/string/tree/main/remove-punctuation 251 252 [@stdlib/string/remove-utf8-bom]: https://github.com/stdlib-js/string/tree/main/remove-utf8-bom 253 254 [@stdlib/string/remove-words]: https://github.com/stdlib-js/string/tree/main/remove-words 255 256 [@stdlib/string/repeat]: https://github.com/stdlib-js/string/tree/main/repeat 257 258 [@stdlib/string/replace]: https://github.com/stdlib-js/string/tree/main/replace 259 260 [@stdlib/string/reverse]: https://github.com/stdlib-js/string/tree/main/reverse 261 262 [@stdlib/string/right-pad]: https://github.com/stdlib-js/string/tree/main/right-pad 263 264 [@stdlib/string/right-trim-n]: https://github.com/stdlib-js/string/tree/main/right-trim-n 265 266 [@stdlib/string/right-trim]: https://github.com/stdlib-js/string/tree/main/right-trim 267 268 [@stdlib/string/snakecase]: https://github.com/stdlib-js/string/tree/main/snakecase 269 270 [@stdlib/string/split-grapheme-clusters]: https://github.com/stdlib-js/string/tree/main/split-grapheme-clusters 271 272 [@stdlib/string/startcase]: https://github.com/stdlib-js/string/tree/main/startcase 273 274 [@stdlib/string/starts-with]: https://github.com/stdlib-js/string/tree/main/starts-with 275 276 [@stdlib/string/substring-after-last]: https://github.com/stdlib-js/string/tree/main/substring-after-last 277 278 [@stdlib/string/substring-after]: https://github.com/stdlib-js/string/tree/main/substring-after 279 280 [@stdlib/string/substring-before-last]: https://github.com/stdlib-js/string/tree/main/substring-before-last 281 282 [@stdlib/string/substring-before]: https://github.com/stdlib-js/string/tree/main/substring-before 283 284 [@stdlib/string/trim]: https://github.com/stdlib-js/string/tree/main/trim 285 286 [@stdlib/string/truncate-middle]: https://github.com/stdlib-js/string/tree/main/truncate-middle 287 288 [@stdlib/string/truncate]: https://github.com/stdlib-js/string/tree/main/truncate 289 290 [@stdlib/string/uncapitalize]: https://github.com/stdlib-js/string/tree/main/uncapitalize 291 292 [@stdlib/string/uppercase]: https://github.com/stdlib-js/string/tree/main/uppercase 293 294 [@stdlib/string/utf16-to-utf8-array]: https://github.com/stdlib-js/string/tree/main/utf16-to-utf8-array 295 296 <!-- </toc-links> --> 297 298 </section> 299 300 <!-- /.links -->