truncate

文字列を決めた長さまで縮め、切った箇所を省略記号で示します。Unicode に対して安全で、しかも どちら側を残すか で切り詰めの意味が変わることをわきまえています。

使い方

import { truncate } from 'ranuts/utils';

truncate('the quick brown fox', 12); // 'the quick b…'

truncate('/Users/me/code/app/src/index.ts', { length: 20, position: 'start' });
// '…de/app/src/index.ts'

truncate('0xabcdef0123456789', { length: 11, position: 'middle' });
// '0xabc…56789'

API

truncate(value, options)

パラメーター

パラメーター	説明	型	既定値
value	縮める文字列	string	必須
options	数値だけを渡すと { length } の略記になります	TruncateOptions | number	必須

TruncateOptions

フィールド	説明	型	既定値
length	結果の最大の長さ。省略記号も数に入ります	number	—
position	どちら側を残すか。下を参照	'end' | 'start' | 'middle'	'end'
ellipsis	切った箇所に入れる印	string	'…'

position はどちら側を残すかを決めます。そしてこの選択には、ちゃんと意味があります。

• 'end'（既定）は先頭を残します。文章や見出しに向きます。
• 'start' は 末尾 を残します。ファイルパスが求めるのはこちらです。/Users/someone/work/… は読み手がすでに知っている部分で、…/src/utils/str.ts こそ知りたい部分です。
• 'middle' は両端を残します。ハッシュや口座番号のように、頭 も 末尾も意味を持つ識別子に向きます。

戻り値

string です。length を超えることはありません。length が省略記号そのものより短ければ、はみ出すのではなく、省略記号のほうが切り詰められます。

補足

1. 切るのは UTF-16 の符号単位ではなく、Unicode の符号位置です。 素朴に value.slice(i) と書くと、サロゲートペアの途中で切ってしまうことがあります。基本多言語面の外にある文字（絵文字や一部の CJK 拡張の文字）は UTF-16 で 2 単位なので、省略記号の隣に対にならないサロゲートが残り、文字化けとして表示されます。truncate は符号位置をたどるので、複数単位の文字が割れることはありません。
2. value が length より短ければ、そのまま返します。省略記号は付きません。
3. 既定の '…' が、描画に使うフォントにない場合は、'...' や '[cut]' のように ellipsis を自分で渡してください。