{"id":19777499,"url":"https://github.com/ilib-js/ilib-istring","last_synced_at":"2026-05-26T16:02:01.073Z","repository":{"id":58116762,"uuid":"489478933","full_name":"iLib-js/ilib-istring","owner":"iLib-js","description":"A formattable string with the same API as an intrinsic string","archived":false,"fork":false,"pushed_at":"2023-11-30T16:21:54.000Z","size":124,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-11T01:49:53.564Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iLib-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-06T19:59:59.000Z","updated_at":"2022-08-29T04:48:09.000Z","dependencies_parsed_at":"2023-11-30T17:54:09.211Z","dependency_job_id":null,"html_url":"https://github.com/iLib-js/ilib-istring","commit_stats":{"total_commits":16,"total_committers":2,"mean_commits":8.0,"dds":0.0625,"last_synced_commit":"42b0aeedb23482712acfb56ccaa1dbbf42de45ec"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-istring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-istring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-istring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-istring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iLib-js","download_url":"https://codeload.github.com/iLib-js/ilib-istring/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241107734,"owners_count":19910975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:25:17.507Z","updated_at":"2026-05-26T16:01:56.023Z","avatar_url":"https://github.com/iLib-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003e :warning: **Deprecation Notice** :warning:\n\u003e This repository has been deprecated. Please use the corresponding package from the [iLib-js monorepo](https://github.com/iLib-js/ilib-mono) instead.\n\n# ilib-istring\n\nAn intrinsic string replacement that includes formatting capabilities\n\n## Installation\n\n```\nnpm install ilib-istring\n\nor\n\nyarn add ilib-istring\n```\n\n## The IString Class\n\nThe IString class is designed to be a drop-in replacement for the intrinsic\nJavascript String class.\n\nFull documentation: [IString class](./docs/ilibIString.md)\n\nThe String class does not allow subclassing, so the\nIString class is a delegate class that delegates most of its methods to an\ninternal String instance, but adds functionality on top.\n\nFor this reason, most of the rest of thus documentation will focus on the\nthe methods of the IString class that are different from the String class.\nTo see the methods that are the same, see other sites like the\n[MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)\nfor details.\n\nIString contains the following functionality above and beyond the String class:\n\n* format - format parameters into a string\n* formatChoice - format parameters into a string, taking care to pluralize\n  properly for the locale\n* codePointAt - return the Unicode code point at the given index\n* forEach - visit each character in the string\n* forEachCodePoint - visit each code point in the string\n* iterator - return an iterator through the code points\n* charIterator - return an iterator through the characters\n* setLocale - set the locale of this string\n* getLocale - get the locale of this string\n* codePointLength - return the number of code points in this string\n\nAdditionally, this class modifies the behaviour of the following methods:\n\n* constructor - add a second parameter\n* localeCompare - always compare using the instance's locale rather than\n  the system's locale\n\n### Formatting\n\nTwo methods of the IString class that are not in the instrinsic String\nclass are the `format` and `formatChoice` methods.\n\n#### Format\n\nTo format a string, pass in an object containing named parameters:\n\n```javascript\nimport IString from 'ilib-istring';\n\nconst string = new IString(\"This is a {value} test.\");\n\nconsole.log(string.format({value: \"big\"}));\n// will print:\n// This is a big test.\n```\n\nParameters will generally be converted to strings before formatting\nthem into the string. The result is an intrinsic String instance, as\npresumably, you do not need the extra IString functionality after\nformatting is done.\n\nSee the [format method documentation](./docs/IString.html#format)\nfor more details.\n\n#### FormatChoice\n\nIn order to support plurals properly, the IString class includes a\n[formatChoice](./docs/IString.html#formatChoice) method. Pluralization\nis locale-dependent, as different\nlanguages and cultures have different ways of handling plurals.\n\nFor example, in English, there are only singular and plural\ncategories. \"one car\" vs. \"two cars\" (or any other number of cars).\nIn Russian, there is a singular\ncategory, a \"few\" category for the numbers 2 to 4, and a \"many\"\ncategory for numbers from 5 to 9. That is, if you have 2 cars\n\"2 машины\" (2 mashiny), then the word for \"car\" is spelled differently\nthan when you have 5 cars \"5 машин\" (5 mashin).\n\nThe definition of which numbers belong to which plural category are\nlocale-dependent. See [the description on the Unicode website](http://cldr.unicode.org/index/cldr-spec/plural-rules)\nfor more details about how plurals work in many languages.\n\nIn order to get pluralization correct for each string in any\nlocale, the string must have its own locale. This locale may be\ndifferent from the locale of the platform.\n\nChoice strings can do more than simple pluralization. The syntax of the\nstring is similar to that of the Java `ChoiceFormat` class upon\nwhich it was originally modeled. However, there are few enhancements\nover the `ChoiceFormat` strings. Basically, the selector for each\nchoice can be a [CLDR plural category](http://cldr.unicode.org/index/cldr-spec/plural-rules#TOC-Choosing-Plural-Category-Names),\na number with an optional operator, a boolean, or even a regular\nexpression. This allows you to do things like switching on a string\nlike \"gender\", or on the result of a boolean expression.\n\nTo format a choice string:\n\n```javascript\nimport IString from 'ilib-istring';\n\nconst x = 2;\nconst string = new IString(\"one#singular {x} string|#plural {x} string\");\nconsole.log(string.formatChoice(x, {x});\n// will print: \"plural 2 string\"\n```\n\nTo format a choice string based on gender:\n\n```javascript\nimport IString from 'ilib-istring';\n\nconst gender = \"female\";\nconst string = new IString(\"male#The patient is male.|female#The patient is female.\");\nconsole.log(string.formatChoice(gender);\n// will print: \"The patient is female.\"\n```\n\nSee the [formatChoice method documentation](./docs/IString.html#formatChoice)\nfor more details.\n\n### Code Points\n\nA code point is a unique number in Unicode which encodes a particular\ncharacter. The range of a code point is currently 0x000000 through\n0x10FFFF, though the upper limit may change in the future. Code points\nat or below 0xFFFF (2 bytes) are known as the Basic Multilingual Plane\n(BMP) or UCS-2. Code points above 0xFFFF are in the extended planes,\nalso known colloquially as \"the astral planes\".\n\nUnicode code points in Javascript strings are encoded as UTF-16. This\nis a multi-byte encoding scheme where each character is either 2 or 4\nbytes long. Unicode characters in a certain range (ie. a surrogate character)\nmust be joined with the following character to create a 4 byte character\nin the extended planes. Characters that are not surrogate characters\nare a simple character in the BMP.\n\nAny character that the processing system does not recognize should be\nskipped. In the UTF-16 encoding, older systems that can only process 2-byte\nUnicode characters can still process UTF-16 strings by processing the string\n2 bytes at a time and ignoring any character it does not recognize.\n\nUnfortunately, most of the String methods are not code point aware\nbecause they were designed before UTF-16 became the base encoding for\nJavascript. That\nis, if you ask it to give you the character at a particular index, it\nwill return the surrogate character. You have to know how to calculate\nthe code point yourself using the next character.\n\nThe new methods of IString now do the code point calculations for you.\n\n* [codePointAt](./docs/IString.html#codePointAt) - split the string into a sequence of code points, and then\n  return the code point at the given index. This is different than\n  the `charAt` method, which returns Unicode characters.\n* [forEach](./docs/IString.html#forEach) - split the string into a sequence of code points, convert\n  each to a full character (in the BMP or extended planes) and then\n  call a callback function for each character\n* [forEachCodePoint](./docs/IString.html#forEachCodePoint) - split the string into a sequence of code points,\n  and then call a callback function for each one\n* [iterator](./docs/IString.html#iterator) - return an iterator through the sequence of code points\n* [charIterator](./docs/IString.html#charIterator) - return an iterator through the sequence of code\n  points that are returned as full characters\n* [codePointLength](./docs/IString.html#codePointLength) - return the total number of code points in this string\n  when the string is converted into a sequence of code points\n\n### Return values\n\nMost methods of the intrinsic string which return another instance of\nString return an instance of IString instead.\n\nFor example, `String.substring()` returns a String, whereas\n`IString.substring()` returns an IString.\n\n### Iterator\n\nIn addition to the `iterator()` method, IString includes an\n[@@Iterator](./docs/IString.html#.@@Iterator)\nimplementation. This means that it can support the \"spread\" operator (\"...\")\nand any other language feature that uses the [@@Iterator] such as the\nfor-of construct.\n\nSpread operator example, spreads accross all characters in the string:\n\n```javascript\nimport IString from 'ilib-istring';\n\nvar string = new IString(\"this is a test.\");\nconsole.log(JSON.stringify(...string));\n// prints ['t','h','i','s',' ','a',' ','t','e','s','t','.']\n```\n\n```javascript\nimport IString from 'ilib-istring';\n\nvar string = new IString(\"this is a test.\");\n\nfor (let ch of string) {\n    console.log(ch);\n}\n/*\nprints:\nt\nh\ni\ns\n\ni\ns\n\na\n\nt\ne\ns\nt\n.\n*/\n```\n\n## License\n\nCopyright © 2022-2023, JEDLSoft\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n## Release Notes\n\n### v1.1.0\n\n* Update to CLDR v44\n\n### v1.0.1\n\n* remove references to import.meta in the transpiled code so that it\n  runs properly when you require() this package\n\n### v1.0.0\n\n- initial version\n- copied from ilib 14.9.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-istring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filib-js%2Filib-istring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-istring/lists"}