feat: refactor truncate string package

[steff456]

Part of #1062

Description

What is the purpose of this pull request?

This pull request:

• Refactors the string package @stdlib/string/truncate
• Adds @stdlib/string/base/truncate
• Adds @stdlib/string/base/truncate-code-point
• Adds @stdlib/string/base/truncate-grapheme-cluster
• Adds @stdlib/string/num-code-points

Related Issues

Does this pull request have any related issues?

This pull request:

• part of Tracking issue: refactor string packages handling grapheme clusters in terms of "base" packages #1062

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-point	$165/165$ $+100.00\mathrm{\%}$	$15/15$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$165/165$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-cluster	$142/142$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$142/142$ $+100.00\mathrm{\%}$
string/base/truncate	$113/113$ $+100.00\mathrm{\%}$	$8/8$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$113/113$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[kgryte]

@steff456 Similar to string/reverse (pr: #1082), would you mind renaming truncate-code-point and truncate-grapheme-cluster to truncate-code-points and truncate-grapheme-clusters, respectively? As in that PR, it makes sense to use the plural; otherwise, the package name suggests that one truncates a single code point or grapheme cluster, which is not the case.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$165/165$ $+100.00\mathrm{\%}$	$15/15$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$165/165$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$142/142$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$142/142$ $+100.00\mathrm{\%}$
string/base/truncate	$113/113$ $+100.00\mathrm{\%}$	$8/8$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$113/113$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$165/165$ $+100.00\mathrm{\%}$	$15/15$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$165/165$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$142/142$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$142/142$ $+100.00\mathrm{\%}$
string/base/truncate	$113/113$ $+100.00\mathrm{\%}$	$8/8$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$113/113$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$165/165$ $+100.00\mathrm{\%}$	$15/15$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$165/165$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$142/142$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$142/142$ $+100.00\mathrm{\%}$
string/base/truncate	$113/113$ $+100.00\mathrm{\%}$	$8/8$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$113/113$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$165/165$ $+100.00\mathrm{\%}$	$15/15$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$165/165$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$142/142$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$142/142$ $+100.00\mathrm{\%}$
string/base/truncate	$113/113$ $+100.00\mathrm{\%}$	$8/8$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$113/113$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$162/162$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$162/162$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$139/139$ $+100.00\mathrm{\%}$	$13/13$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$139/139$ $+100.00\mathrm{\%}$
string/base/truncate	$112/112$ $+100.00\mathrm{\%}$	$7/7$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$112/112$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$162/162$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$162/162$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$139/139$ $+100.00\mathrm{\%}$	$13/13$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$139/139$ $+100.00\mathrm{\%}$
string/base/truncate	$112/112$ $+100.00\mathrm{\%}$	$7/7$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$112/112$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$162/162$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$162/162$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$139/139$ $+100.00\mathrm{\%}$	$13/13$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$139/139$ $+100.00\mathrm{\%}$
string/base/truncate	$112/112$ $+100.00\mathrm{\%}$	$7/7$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$112/112$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$161/161$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$161/161$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$139/139$ $+100.00\mathrm{\%}$	$13/13$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$139/139$ $+100.00\mathrm{\%}$
string/base/truncate	$112/112$ $+100.00\mathrm{\%}$	$7/7$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$112/112$ $+100.00\mathrm{\%}$
string/num-code-points	$137/137$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$137/137$ $+100.00\mathrm{\%}$
string/truncate	$187/187$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$187/187$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[kgryte]

This should be refactored. See https://github.com/stdlib-js/stdlib/blob/30019b1fc159eb3fcf59b182e62ef53997a7675f/lib/node_modules/%40stdlib/string/camelcase/bin/cli.

Please open an issue about num-grapheme-clusters.

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
string/base/truncate-code-points	$161/161$ $+100.00\mathrm{\%}$	$14/14$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$161/161$ $+100.00\mathrm{\%}$
string/base/truncate-grapheme-clusters	$139/139$ $+100.00\mathrm{\%}$	$13/13$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$139/139$ $+100.00\mathrm{\%}$
string/base/truncate	$112/112$ $+100.00\mathrm{\%}$	$7/7$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$112/112$ $+100.00\mathrm{\%}$
string/num-code-points	$132/132$ $+100.00\mathrm{\%}$	$11/11$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$132/132$ $+100.00\mathrm{\%}$
string/truncate	$186/186$ $+100.00\mathrm{\%}$	$22/22$ $+100.00\mathrm{\%}$	$1/1$ $+100.00\mathrm{\%}$	$186/186$ $+100.00\mathrm{\%}$

The above coverage report was generated for the changes in this PR.

[kgryte]

@steff456 Given that we break here, does this mean we could end up with a string having fewer than the desired number of Unicode code points?

The comment on L96 says the end of the input string, but this is not precise, as it is at the end of the "eligible" string. There could be a low surrogate at the next code unit, but we don't process that character, and I believe we should be.

Is my understanding correct?

[kgryte]

This test case seems odd to me. Isn't the 𐒻 character comprised of a high and low surrogate? If so, that is a single Unicode code point, but the expected output is only 4 code point (visual) characters. Is this the intended behavior?

[kgryte]

In this case, we are omitting the unpaired surrogate entirely, resulting in a string of 3 Unicode code points, which is less than len. This also doesn't make sense to me.

I would think that we should treat unpaired high surrogates as simply another code unit. In which case, for this test, I'd expect \uD800....

[headlessNode]

After a discussion during project office hours on unblocking the #5414, I will split this PR it into separate PRs in order to unblock the related ongoing work.

cc @kgryte

[kgryte]

@headlessNode That sounds good! Will be good to move this work forward. During review and merge, I'll be sure to give @steff456 proper attribution.