README.md (4909B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2020 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 # nextGraphemeClusterBreak 22 23 > Return the next extended grapheme cluster break in a string after a specified position. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var nextGraphemeClusterBreak = require( '@stdlib/string/next-grapheme-cluster-break' ); 41 ``` 42 43 #### nextGraphemeClusterBreak( string\[, fromIndex] ) 44 45 Returns the next extended grapheme cluster break in a string after a specified position. 46 47 ```javascript 48 var out = nextGraphemeClusterBreak( 'last man standing' ); 49 // returns 1 50 ``` 51 52 By default, the function searches for a grapheme cluster break starting from the first index. To specify an alternative starting search index, provide a `fromIndex` argument. 53 54 ```javascript 55 var out = nextGraphemeClusterBreak( 'last man standing', 4 ); 56 // returns 5 57 ``` 58 59 </section> 60 61 <!-- /.usage --> 62 63 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 64 65 <section class="notes"> 66 67 ## Notes 68 69 - If `string` is an empty string, the function returns `-1` irrespective of `fromIndex`. 70 - If an extended grapheme cluster break does not exist after `fromIndex`, the function returns `-1`. 71 - Note that `fromIndex` does **not** refer to a visual character position, but to an index in the ordered sequence of [UTF-16][utf-16] code units. 72 73 </section> 74 75 <!-- /.notes --> 76 77 <!-- Package usage examples. --> 78 79 <section class="examples"> 80 81 ## Examples 82 83 <!-- eslint no-undef: "error" --> 84 85 ```javascript 86 var nextGraphemeClusterBreak = require( '@stdlib/string/next-grapheme-cluster-break' ); 87 88 var out = nextGraphemeClusterBreak( 'last man standing', 4 ); 89 // returns 5 90 91 out = nextGraphemeClusterBreak( 'presidential election', 8 ); 92 // returns 9 93 94 out = nextGraphemeClusterBreak( 'अनुच्छेद', 1 ); 95 // returns 3 96 97 out = nextGraphemeClusterBreak( '🌷', 0 ); 98 // returns -1 99 ``` 100 101 </section> 102 103 <!-- /.examples --> 104 105 <!-- Section for describing a command-line interface. --> 106 107 * * * 108 109 <section class="cli"> 110 111 ## CLI 112 113 <!-- CLI usage documentation. --> 114 115 <section class="usage"> 116 117 ### Usage 118 119 ```text 120 Usage: next-grapheme-cluster-break [options] [<string>] 121 122 Options: 123 124 -h, --help Print this message. 125 -V, --version Print the package version. 126 --from index Starting search position in string. Default: 0. 127 ``` 128 129 </section> 130 131 <!-- /.usage --> 132 133 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 134 135 <section class="notes"> 136 137 </section> 138 139 <!-- /.notes --> 140 141 <!-- CLI usage examples. --> 142 143 <section class="examples"> 144 145 ### Examples 146 147 ```bash 148 $ next-grapheme-cluster-break --from=1 अनुच्छेद 149 3 150 ``` 151 152 To use as a [standard stream][standard-streams], 153 154 ```bash 155 $ echo -n 'अनुच्छेद' | next-grapheme-cluster-break --from=1 156 3 157 ``` 158 159 </section> 160 161 <!-- /.examples --> 162 163 </section> 164 165 <!-- /.cli --> 166 167 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 168 169 <section class="references"> 170 171 </section> 172 173 <!-- /.references --> 174 175 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 176 177 <section class="related"> 178 179 * * * 180 181 ## See Also 182 183 - <span class="package-name">[`@stdlib/string/num-grapheme-clusters`][@stdlib/string/num-grapheme-clusters]</span><span class="delimiter">: </span><span class="description">return the number of grapheme clusters in a string.</span> 184 185 </section> 186 187 <!-- /.related --> 188 189 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 190 191 <section class="links"> 192 193 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams 194 195 [utf-16]: https://en.wikipedia.org/wiki/UTF-16 196 197 <!-- <related-links> --> 198 199 [@stdlib/string/num-grapheme-clusters]: https://github.com/stdlib-js/string/tree/main/num-grapheme-clusters 200 201 <!-- </related-links> --> 202 203 </section> 204 205 <!-- /.links -->