@stdlib/string-to-grapheme-cluster-iterator 0.0.1 → 0.1.0

package/CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+title: stdlib
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+
+type: software
+
+authors:
+  - name: The Stdlib Authors
+    url: https://github.com/stdlib-js/stdlib/graphs/contributors
+
+repository-code: https://github.com/stdlib-js/stdlib
+url: https://stdlib.io
+
+abstract: |
+  Standard library for JavaScript and Node.js.
+
+keywords:
+  - JavaScript
+  - Node.js
+  - TypeScript
+  - standard library
+  - scientific computing
+  - numerical computing
+  - statistical computing
+
+license: Apache-2.0 AND BSL-1.0
+
+date-released: 2016

package/README.md

@@ -18,6 +18,17 @@ limitations under the License.
 
 -->
 
+
+<details>
+  <summary>
+    About stdlib...
+  </summary>
+  <p>We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.</p>
+  <p>The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.</p>
+  <p>When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.</p>
+  <p>To join us in bringing numerical computing to the web, get started by checking us out on <a href="https://github.com/stdlib-js/stdlib">GitHub</a>, and please consider <a href="https://opencollective.com/stdlib">financially supporting stdlib</a>. We greatly appreciate your continued support!</p>
+</details>
+
 # graphemeClusters2iterator
 
 [![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
@@ -252,8 +263,8 @@ Copyright &copy; 2016-2023. The Stdlib [Authors][stdlib-authors].
 [npm-image]: http://img.shields.io/npm/v/@stdlib/string-to-grapheme-cluster-iterator.svg
 [npm-url]: https://npmjs.org/package/@stdlib/string-to-grapheme-cluster-iterator
 
-[test-image]: https://github.com/stdlib-js/string-to-grapheme-cluster-iterator/actions/workflows/test.yml/badge.svg?branch=v0.0.1
-[test-url]: https://github.com/stdlib-js/string-to-grapheme-cluster-iterator/actions/workflows/test.yml?query=branch:v0.0.1
+[test-image]: https://github.com/stdlib-js/string-to-grapheme-cluster-iterator/actions/workflows/test.yml/badge.svg?branch=v0.1.0
+[test-url]: https://github.com/stdlib-js/string-to-grapheme-cluster-iterator/actions/workflows/test.yml?query=branch:v0.1.0
 
 [coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/string-to-grapheme-cluster-iterator/main.svg
 [coverage-url]: https://codecov.io/github/stdlib-js/string-to-grapheme-cluster-iterator?branch=main
@@ -266,7 +277,7 @@ Copyright &copy; 2016-2023. The Stdlib [Authors][stdlib-authors].
 -->
 
 [chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg
-[chat-url]: https://gitter.im/stdlib-js/stdlib/
+[chat-url]: https://app.gitter.im/#/room/#stdlib-js_stdlib:gitter.im
 
 [stdlib]: https://github.com/stdlib-js/stdlib
 

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="../docs/types/index.d.ts" />
+import graphemeClusters2iterator from '../docs/types/index';
+export = graphemeClusters2iterator;

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";var p=function(e,t){return function(){return t||e((t={exports:{}}).exports,t),t.exports}};var d=p(function(j,m){
+var f=require('@stdlib/utils-define-nonenumerable-read-only-property/dist'),y=require('@stdlib/assert-is-function/dist'),w=require('@stdlib/assert-is-string/dist').isPrimitive,v=require('@stdlib/symbol-iterator/dist'),s=require('@stdlib/string-next-grapheme-cluster-break/dist'),g=require('@stdlib/error-tools-fmtprodmsg/dist');function l(e){var t,a,o,u,r;if(!w(e))throw new TypeError(g('1h1E6',e));if(arguments.length>1){if(u=arguments[1],!y(u))throw new TypeError(g('1h12H',u));t=arguments[2]}return r=0,a={},u?f(a,"next",h):f(a,"next",b),f(a,"return",q),v&&f(a,v,x),a;function h(){var i,n;return o?{done:!0}:(n=s(e,r),n===-1?(o=!0,e.length?{value:u.call(t,e.substring(r),r,e),done:!1}:{done:!0}):(i=u.call(t,e.substring(r,n),r,e),r=n,{value:i,done:!1}))}function b(){var i,n;return o?{done:!0}:(n=s(e,r),n===-1?(o=!0,e.length?{value:e.substring(r),done:!1}:{done:!0}):(i=e.substring(r,n),r=n,{value:i,done:!1}))}function q(i){return o=!0,arguments.length?{value:i,done:!0}:{done:!0}}function x(){return u?l(e,u,t):l(e)}}m.exports=l
+});var F=d();module.exports=F;
+/** @license Apache-2.0 */
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../lib/main.js", "../lib/index.js"],
+  "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2022 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n*    http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );\nvar isFunction = require( '@stdlib/assert-is-function' );\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar iteratorSymbol = require( '@stdlib/symbol-iterator' );\nvar nextGraphemeClusterBreak = require( '@stdlib/string-next-grapheme-cluster-break' );\nvar format = require( '@stdlib/string-format' );\n\n\n// MAIN //\n\n/**\n* Returns an iterator which iterates over each grapheme cluster in a string.\n*\n* @param {string} src - input value\n* @param {Function} [mapFcn] - function to invoke for each iterated value\n* @param {*} [thisArg] - execution context\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a function\n* @returns {Iterator} iterator\n*\n* @example\n* var iter = graphemeClusters2iterator( '\uD83C\uDF37\uD83C\uDF55' );\n*\n* var v = iter.next().value;\n* // returns '\uD83C\uDF37'\n*\n* v = iter.next().value;\n* // returns '\uD83C\uDF55'\n*\n* var bool = iter.next().done;\n* // returns true\n*/\nfunction graphemeClusters2iterator( src ) {\n\tvar thisArg;\n\tvar iter;\n\tvar FLG;\n\tvar fcn;\n\tvar i;\n\tif ( !isString( src ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be astring. Value: `%s`.', src ) );\n\t}\n\tif ( arguments.length > 1 ) {\n\t\tfcn = arguments[ 1 ];\n\t\tif ( !isFunction( fcn ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a function. Value: `%s`.', fcn ) );\n\t\t}\n\t\tthisArg = arguments[ 2 ];\n\t}\n\ti = 0;\n\n\t// Create an iterator protocol-compliant object:\n\titer = {};\n\tif ( fcn ) {\n\t\tsetReadOnly( iter, 'next', next1 );\n\t} else {\n\t\tsetReadOnly( iter, 'next', next2 );\n\t}\n\tsetReadOnly( iter, 'return', end );\n\n\t// If an environment supports `Symbol.iterator`, make the iterator iterable:\n\tif ( iteratorSymbol ) {\n\t\tsetReadOnly( iter, iteratorSymbol, factory );\n\t}\n\treturn iter;\n\n\t/**\n\t* Returns an iterator protocol-compliant object containing the next iterated value.\n\t*\n\t* @private\n\t* @returns {Object} iterator protocol-compliant object\n\t*/\n\tfunction next1() {\n\t\tvar v;\n\t\tvar j;\n\t\tif ( FLG ) {\n\t\t\treturn {\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\tj = nextGraphemeClusterBreak( src, i );\n\t\tif ( j === -1 ) {\n\t\t\tFLG = true;\n\t\t\tif ( src.length ) {\n\t\t\t\treturn {\n\t\t\t\t\t'value': fcn.call( thisArg, src.substring( i ), i, src ),\n\t\t\t\t\t'done': false\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn {\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\tv = fcn.call( thisArg, src.substring( i, j ), i, src );\n\t\ti = j;\n\t\treturn {\n\t\t\t'value': v,\n\t\t\t'done': false\n\t\t};\n\t}\n\n\t/**\n\t* Returns an iterator protocol-compliant object containing the next iterated value.\n\t*\n\t* @private\n\t* @returns {Object} iterator protocol-compliant object\n\t*/\n\tfunction next2() {\n\t\tvar v;\n\t\tvar j;\n\t\tif ( FLG ) {\n\t\t\treturn {\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\tj = nextGraphemeClusterBreak( src, i );\n\t\tif ( j === -1 ) {\n\t\t\tFLG = true;\n\t\t\tif ( src.length ) {\n\t\t\t\treturn {\n\t\t\t\t\t'value': src.substring( i ),\n\t\t\t\t\t'done': false\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn {\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\tv = src.substring( i, j );\n\t\ti = j;\n\t\treturn {\n\t\t\t'value': v,\n\t\t\t'done': false\n\t\t};\n\t}\n\n\t/**\n\t* Finishes an iterator.\n\t*\n\t* @private\n\t* @param {*} [value] - value to return\n\t* @returns {Object} iterator protocol-compliant object\n\t*/\n\tfunction end( value ) {\n\t\tFLG = true;\n\t\tif ( arguments.length ) {\n\t\t\treturn {\n\t\t\t\t'value': value,\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\treturn {\n\t\t\t'done': true\n\t\t};\n\t}\n\n\t/**\n\t* Returns a new iterator.\n\t*\n\t* @private\n\t* @returns {Iterator} iterator\n\t*/\n\tfunction factory() {\n\t\tif ( fcn ) {\n\t\t\treturn graphemeClusters2iterator( src, fcn, thisArg );\n\t\t}\n\t\treturn graphemeClusters2iterator( src );\n\t}\n}\n\n\n// EXPORTS //\n\nmodule.exports = graphemeClusters2iterator;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2022 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n*    http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Create an iterator which iterates over grapheme clusters.\n*\n* @module @stdlib/string-to-grapheme-cluster-iterator\n*\n* @example\n* var graphemeClusters2iterator = require( '@stdlib/string-to-grapheme-cluster-iterator' );\n*\n* var iter = graphemeClusters2iterator( '\uD83C\uDF37\uD83C\uDF55' );\n*\n* var v = iter.next().value;\n* // returns '\uD83C\uDF37'\n*\n* v = iter.next().value;\n* // returns '\uD83C\uDF55'\n*\n* var bool = iter.next().done;\n* // returns true\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"],
+  "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAc,QAAS,uDAAwD,EAC/EC,EAAa,QAAS,4BAA6B,EACnDC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAiB,QAAS,yBAA0B,EACpDC,EAA2B,QAAS,4CAA6C,EACjFC,EAAS,QAAS,uBAAwB,EA2B9C,SAASC,EAA2BC,EAAM,CACzC,IAAIC,EACAC,EACAC,EACAC,EACAC,EACJ,GAAK,CAACV,EAAUK,CAAI,EACnB,MAAM,IAAI,UAAWF,EAAQ,iEAAkEE,CAAI,CAAE,EAEtG,GAAK,UAAU,OAAS,EAAI,CAE3B,GADAI,EAAM,UAAW,CAAE,EACd,CAACV,EAAYU,CAAI,EACrB,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAI,CAAE,EAE1GH,EAAU,UAAW,CAAE,CACxB,CACA,OAAAI,EAAI,EAGJH,EAAO,CAAC,EACHE,EACJX,EAAaS,EAAM,OAAQI,CAAM,EAEjCb,EAAaS,EAAM,OAAQK,CAAM,EAElCd,EAAaS,EAAM,SAAUM,CAAI,EAG5BZ,GACJH,EAAaS,EAAMN,EAAgBa,CAAQ,EAErCP,EAQP,SAASI,GAAQ,CAChB,IAAII,EACAC,EACJ,OAAKR,EACG,CACN,KAAQ,EACT,GAEDQ,EAAId,EAA0BG,EAAKK,CAAE,EAChCM,IAAM,IACVR,EAAM,GACDH,EAAI,OACD,CACN,MAASI,EAAI,KAAMH,EAASD,EAAI,UAAWK,CAAE,EAAGA,EAAGL,CAAI,EACvD,KAAQ,EACT,EAEM,CACN,KAAQ,EACT,IAEDU,EAAIN,EAAI,KAAMH,EAASD,EAAI,UAAWK,EAAGM,CAAE,EAAGN,EAAGL,CAAI,EACrDK,EAAIM,EACG,CACN,MAASD,EACT,KAAQ,EACT,GACD,CAQA,SAASH,GAAQ,CAChB,IAAIG,EACAC,EACJ,OAAKR,EACG,CACN,KAAQ,EACT,GAEDQ,EAAId,EAA0BG,EAAKK,CAAE,EAChCM,IAAM,IACVR,EAAM,GACDH,EAAI,OACD,CACN,MAASA,EAAI,UAAWK,CAAE,EAC1B,KAAQ,EACT,EAEM,CACN,KAAQ,EACT,IAEDK,EAAIV,EAAI,UAAWK,EAAGM,CAAE,EACxBN,EAAIM,EACG,CACN,MAASD,EACT,KAAQ,EACT,GACD,CASA,SAASF,EAAKI,EAAQ,CAErB,OADAT,EAAM,GACD,UAAU,OACP,CACN,MAASS,EACT,KAAQ,EACT,EAEM,CACN,KAAQ,EACT,CACD,CAQA,SAASH,GAAU,CAClB,OAAKL,EACGL,EAA2BC,EAAKI,EAAKH,CAAQ,EAE9CF,EAA2BC,CAAI,CACvC,CACD,CAKAR,EAAO,QAAUO,ICxJjB,IAAIc,EAAO,IAKX,OAAO,QAAUA",
+  "names": ["require_main", "__commonJSMin", "exports", "module", "setReadOnly", "isFunction", "isString", "iteratorSymbol", "nextGraphemeClusterBreak", "format", "graphemeClusters2iterator", "src", "thisArg", "iter", "FLG", "fcn", "i", "next1", "next2", "end", "factory", "v", "j", "value", "main"]
+}

package/docs/types/index.d.ts

@@ -16,7 +16,7 @@
 * limitations under the License.
 */
 
-// TypeScript Version: 2.0
+// TypeScript Version: 4.1
 
 /// <reference types="@stdlib/types"/>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stdlib/string-to-grapheme-cluster-iterator",
-  "version": "0.0.1",
-  "description": "Create an iterator which iterates grapheme clusters.",
+  "version": "0.1.0",
+  "description": "Create an iterator which iterates over grapheme clusters.",
   "license": "Apache-2.0",
   "author": {
     "name": "The Stdlib Authors",
@@ -37,19 +37,20 @@
     "url": "https://github.com/stdlib-js/stdlib/issues"
   },
   "dependencies": {
-    "@stdlib/assert-is-function": "^0.0.x",
-    "@stdlib/assert-is-string": "^0.0.x",
-    "@stdlib/string-format": "^0.0.x",
-    "@stdlib/string-next-grapheme-cluster-break": "^0.0.x",
-    "@stdlib/symbol-iterator": "^0.0.x",
-    "@stdlib/types": "^0.0.x",
-    "@stdlib/utils-define-nonenumerable-read-only-property": "^0.0.x"
+    "@stdlib/assert-is-function": "^0.1.0",
+    "@stdlib/assert-is-string": "^0.1.0",
+    "@stdlib/string-format": "^0.1.0",
+    "@stdlib/string-next-grapheme-cluster-break": "^0.1.0",
+    "@stdlib/symbol-iterator": "^0.1.0",
+    "@stdlib/types": "^0.1.0",
+    "@stdlib/utils-define-nonenumerable-read-only-property": "^0.1.0",
+    "@stdlib/error-tools-fmtprodmsg": "^0.1.0"
   },
   "devDependencies": {
-    "@stdlib/assert-is-iterator-like": "^0.0.x",
-    "@stdlib/bench": "^0.0.x",
-    "@stdlib/string-num-grapheme-clusters": "^0.0.x",
-    "@stdlib/utils-noop": "^0.0.x",
+    "@stdlib/assert-is-iterator-like": "^0.1.0",
+    "@stdlib/bench": "^0.1.0",
+    "@stdlib/string-num-grapheme-clusters": "^0.0.9",
+    "@stdlib/utils-noop": "^0.1.0",
     "proxyquire": "^2.0.0",
     "tape": "git+https://github.com/kgryte/tape.git#fix/globby",
     "istanbul": "^0.4.1",
@@ -93,7 +94,7 @@
     "convert"
   ],
   "funding": {
-    "type": "patreon",
-    "url": "https://www.patreon.com/athan"
+    "type": "opencollective",
+    "url": "https://opencollective.com/stdlib"
   }
 }

package/docs/repl.txt

@@ -1,55 +0,0 @@
-
-{{alias}}( src[, mapFcn[, thisArg]] )
-    Returns an iterator which iterates over each grapheme cluster in a string.
-
-    When invoked, an input function is provided three arguments:
-
-    - value: grapheme cluster
-    - index: iterated value index
-    - src: source string
-
-    If an environment supports Symbol.iterator, the returned iterator is
-    iterable.
-
-    If an environment supports Symbol.iterator, the function explicitly does not
-    invoke a string's `@@iterator` method, regardless of whether this method is
-    defined. To convert a string to an implementation defined iterator, invoke
-    this method directly.
-
-    Parameters
-    ----------
-    src: string
-        String from which to create the iterator.
-
-    mapFcn: Function (optional)
-        Function to invoke for each iterated value.
-
-    thisArg: any (optional)
-        Execution context.
-
-    Returns
-    -------
-    iterator: Object
-        Iterator.
-
-    iterator.next(): Function
-        Returns an iterator protocol-compliant object containing the next
-        iterated value (if one exists) and a boolean flag indicating whether the
-        iterator is finished.
-
-    iterator.return( [value] ): Function
-        Finishes an iterator and returns a provided value.
-
-    Examples
-    --------
-    > var it = {{alias}}( '🌷🍕' );
-    > var v = it.next().value
-    '🌷'
-    > v = it.next().value
-    '🍕'
-    > var bool = it.next().done
-    true
-
-    See Also
-    --------
-

package/docs/types/test.ts

@@ -1,66 +0,0 @@
-/*
-* @license Apache-2.0
-*
-* Copyright (c) 2022 The Stdlib Authors.
-*
-* Licensed under the Apache License, Version 2.0 (the "License");
-* you may not use this file except in compliance with the License.
-* You may obtain a copy of the License at
-*
-*    http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
-
-import graphemeClusters2iterator = require( './index' );
-
-/**
-* Transforms a string.
-*
-* @param v - iterated value
-* @returns new value
-*/
-function transform( v: string ): string {
-	return v + v;
-}
-
-
-// TESTS //
-
-// The function returns an iterator...
-{
-	graphemeClusters2iterator( 'beep' ); // $ExpectType Iterator
-	graphemeClusters2iterator( 'beep', transform ); // $ExpectType Iterator
-	graphemeClusters2iterator( 'beep', transform, {} ); // $ExpectType Iterator
-}
-
-// The compiler throws an error if the function is provided a first argument which is not a string...
-{
-	graphemeClusters2iterator( 123 );  // $ExpectError
-	graphemeClusters2iterator( true ); // $ExpectError
-	graphemeClusters2iterator( false ); // $ExpectError
-	graphemeClusters2iterator( {} ); // $ExpectError
-	graphemeClusters2iterator( null ); // $ExpectError
-	graphemeClusters2iterator( undefined ); // $ExpectError
-}
-
-// The compiler throws an error if the function is provided a second argument which is not a map function...
-{
-	graphemeClusters2iterator( 'beep', 'abc' ); // $ExpectError
-	graphemeClusters2iterator( 'beep', 123 ); // $ExpectError
-	graphemeClusters2iterator( 'beep', [] ); // $ExpectError
-	graphemeClusters2iterator( 'beep', {} ); // $ExpectError
-	graphemeClusters2iterator( 'beep', true ); // $ExpectError
-	graphemeClusters2iterator( 'beep', false ); // $ExpectError
-	graphemeClusters2iterator( 'beep', null ); // $ExpectError
-}
-
-// The compiler throws an error if the function is provided an unsupported number of arguments...
-{
-	graphemeClusters2iterator(); // $ExpectError
-	graphemeClusters2iterator( 'beep', transform, {}, 123 ); // $ExpectError
-}