README.md (5146B)
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 # codePointAt 22 23 > Return a Unicode [code point][code-point] from a string at 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 codePointAt = require( '@stdlib/string/code-point-at' ); 41 ``` 42 43 #### codePointAt( string, position\[, backward] ) 44 45 Returns a Unicode [code point][code-point] from a string at a specified position. 46 47 ```javascript 48 var out = codePointAt( 'last man standing', 4 ); 49 // returns 32 50 ``` 51 52 The function supports providing a `boolean` argument for performing backward iteration for low surrogates. 53 54 ```javascript 55 var out = codePointAt( '๐ท', 1, true ); 56 // returns 127799 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 This function differs from [`String.prototype.codePointAt`][mdn-string-codepointat] in the following ways: 70 71 - The function supports providing a `boolean` argument for performing backward iteration for low surrogates. [`String.prototype.codePointAt`][mdn-string-codepointat] simply returns the low surrogate value if no [UTF-16][utf-16] surrogate pair begins at the specified position. If invoked with `backward` set to `true`, this function will return the code point after aggregating with the preceding high surrogate, if the specified position does not mark the start of a surrogate pair. 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 codePointAt = require( '@stdlib/string/code-point-at' ); 87 88 console.log( codePointAt( 'last man standing', 4 ) ); 89 // => 32 90 91 console.log( codePointAt( 'presidential election', 8, true ) ); 92 // => 116 93 94 console.log( codePointAt( 'เค เคจเฅเคเฅเคเฅเคฆ', 2 ) ); 95 // => 2369 96 97 console.log( codePointAt( '๐ท', 1, true ) ); 98 // => 127799 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: code-point-at [options] [<string>] --pos=<index> 121 122 Options: 123 124 -h, --help Print this message. 125 -V, --version Print the package version. 126 -b, --backward Backward iteration for low surrogates. 127 --pos index Position in string. 128 ``` 129 130 </section> 131 132 <!-- /.usage --> 133 134 <!-- CLI usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 135 136 <section class="notes"> 137 138 </section> 139 140 <!-- /.notes --> 141 142 <!-- CLI usage examples. --> 143 144 <section class="examples"> 145 146 ### Examples 147 148 ```bash 149 $ code-point-at --pos=2 เค เคจเฅเคเฅเคเฅเคฆ 150 2369 151 ``` 152 153 To use as a [standard stream][standard-streams], 154 155 ```bash 156 $ echo -n 'เค เคจเฅเคเฅเคเฅเคฆ' | code-point-at --pos=2 157 2369 158 ``` 159 160 </section> 161 162 <!-- /.examples --> 163 164 </section> 165 166 <!-- /.cli --> 167 168 <!-- 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. --> 169 170 <section class="references"> 171 172 </section> 173 174 <!-- /.references --> 175 176 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> 177 178 <section class="related"> 179 180 * * * 181 182 ## See Also 183 184 - <span class="package-name">[`@stdlib/string/from-code-point`][@stdlib/string/from-code-point]</span><span class="delimiter">: </span><span class="description">create a string from a sequence of Unicode code points.</span> 185 186 </section> 187 188 <!-- /.related --> 189 190 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 191 192 <section class="links"> 193 194 [code-point]: https://en.wikipedia.org/wiki/Code_point 195 196 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams 197 198 [mdn-string-codepointat]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt 199 200 [utf-16]: https://en.wikipedia.org/wiki/UTF-16 201 202 <!-- <related-links> --> 203 204 [@stdlib/string/from-code-point]: https://github.com/stdlib-js/string/tree/main/from-code-point 205 206 <!-- </related-links> --> 207 208 </section> 209 210 <!-- /.links -->