Like string.slice() but bytewise.

string.slice() operates character-wise. Each character can take up to 4 bytes when serialized with UTF-8 (in a file, network request, etc.). This library slices or truncates a string to a specific amount of bytes instead.

Features

• Same interface as string.slice()
• Fastest available library in JavaScript
• Works on all platforms (Node.js, browsers, Deno, etc.)

Example

1import stringByteSlice from 'string-byte-slice'
2
3// Works like `string.slice()`
4stringByteSlice('abcd', 1) // "bcd"
5stringByteSlice('abcd', 1, 3) // "bc"
6stringByteSlice('abcd', -3) // "bcd"
7stringByteSlice('abcd', 0, -1) // "abc"
8stringByteSlice('abcd', 0, 100) // "abcd"
9stringByteSlice('abcd', 0, -100) // ""
10
11// UTF-8 bytes length is taken into account
12stringByteSlice('abcdef', 0, 4) // "abcd"
13stringByteSlice('\nbcdef', 0, 4) // "\nbcd"
14stringByteSlice('±bcdef', 0, 4) // "±bc"
15stringByteSlice('★bcdef', 0, 4) // "★b"
16stringByteSlice('🦄bcdef', 0, 4) // "🦄"
17
18// Partially cut characters are discarded
19stringByteSlice('🦄bcdef', 0, 3) // ""

Install

1npm install string-byte-slice

This package works in both Node.js >=18.18.0 and browsers.

This is an ES module. It must be loaded using an import or import() statement, not require(). If TypeScript is used, it must be configured to output ES modules, not CommonJS.

API

stringByteSlice(input, start, end?)

input string
start number
end number?
Return value: string

Returns a copy of input:

• From byte start
• If specified: up to byte end (excluded)

start and end:

• Are integers that start at 0
• Can be negative to search from the end instead
• If out-of-bound, stop at the start or end of input

Since Unicode characters can span multiple bytes, if the first or last character of the slice has been cut in its middle, it is discarded from the return value. This means the start and end might end up being up to 3 bytes off from the specified value.

Benchmarks

There are several ways to slice a string bytewise:

• Iterating through each codepoint using string.charCodeAt() or string.codePointAt()
• Using Node.js Buffer, e.g. Buffer.from() and buffer.subarray()
• Using TextEncoder, TextDecoder and uint8array.subarray() or uint8array.slice()

Which one is the fastest depends on many factors including:

• The string length
• How often the characters are ASCII or not
• How big the slice is
• Whether the method is supported in the current platform

This library picks the fastest method based on the platform and the input.

                                                                              String length
                                                           1      1e1    1e2     1e3     1e4     1e5     1e6     1e7     1e8

Small slice  Only ASCII         string-byte-slice     38.6ns   74.5ns  355ns  1.16μs  4.11μs  26.7μs  0.26ms  3.27ms  52.6ms
                                String.charCodeAt()   23.5ns   63.0ns  361ns  3.04μs 28.29μs 288.2μs  3.16ms 31.16ms 316.0ms
                                Buffer.from()        302.6ns  359.1ns  400ns  0.62μs  3.53μs  26.5μs  0.26ms  3.22ms  53.3ms
                                TextEncoder          975.4ns  975.9ns  989ns  1.04μs  1.49μs  17.6μs  0.20ms  2.65ms  33.7ms

             Mostly ASCII       string-byte-slice     38.8ns   68.0ns  392ns  2.33μs  9.96μs  97.8μs  0.95ms  9.97ms   103ms
             Very few non-ASCII String.charCodeAt()   28.8ns   54.5ns  360ns  4.14μs 35.73μs 339.7μs  3.50ms 36.34ms   359ms
                                Buffer.from()        222.3ns  343.9ns  509ns  1.83μs 21.34μs 195.6μs  1.70ms 18.99ms   191ms
                                TextEncoder          809.5ns 1043.2ns 1105ns  1.95μs 11.49μs  95.8μs  0.95ms 10.53ms   103ms

             Mostly ASCII       string-byte-slice     38.8ns   48.1ns  235ns  3.48μs  16.6μs   206μs  2.02ms  20.7ms   214ms
             Some non-ASCII     String.charCodeAt()   28.8ns   35.9ns  233ns  2.11μs  22.3μs   241μs  2.01ms  26.5ms   212ms
                                Buffer.from()        222.3ns  252.8ns  624ns  3.30μs  34.6μs   342μs  3.36ms  34.7ms   368ms
                                TextEncoder          809.5ns  789.6ns 1156ns  2.95μs  20.1μs   205μs  2.02ms  20.8ms   224ms

             Only non-ASCII     string-byte-slice     38.6ns   55.1ns  202ns  1.93μs  16.6μs   154μs  1.38ms  16.7ms   167ms
                                String.charCodeAt()   23.5ns   50.6ns  185ns  1.42μs  17.2μs   166μs  1.68ms  16.7ms   168ms
                                Buffer.from()        302.6ns  344.2ns 1113ns  8.73μs 129.9μs  1173μs 11.82ms 124.6ms  1226ms
                                TextEncoder          975.4ns  850.4ns 1304ns  7.15μs  49.5μs   479μs  4.80ms  55.4ms   525ms

Medium slice Only ASCII         string-byte-slice     38.6ns   97.1ns  624ns  1.27μs  4.57μs  33.0μs  0.48ms  6.02ms  76.2ms
                                String.charCodeAt()   23.5ns   93.6ns  585ns  6.05μs 58.88μs 498.0μs  5.22ms 51.64ms 515.5ms
                                Buffer.from()        302.6ns  356.0ns  418ns  0.65μs  4.13μs  32.1μs  0.49ms  6.13ms  74.7ms
                                TextEncoder          975.4ns 1059.7ns 1124ns  2.50μs  7.28μs  70.0μs  0.92ms  8.80ms 140.6ms

             Mostly ASCII       string-byte-slice     38.8ns   86.7ns  611ns  3.76μs  15.6μs   151μs  1.68ms  16.3ms   212ms
             Very few non-ASCII String.charCodeAt()   28.8ns   86.2ns  608ns  5.32μs  56.9μs   557μs  5.59ms  56.0ms   564ms
                                Buffer.from()        222.3ns  353.2ns  505ns  1.97μs  23.6μs   180μs  1.97ms  20.6ms   215ms
                                TextEncoder          809.5ns 1069.8ns 1185ns  3.36μs  22.1μs   151μs  1.70ms  16.3ms   216ms

             Mostly ASCII       string-byte-slice     38.8ns   60.9ns  377ns  5.41μs  35.9μs   311μs  3.27ms  31.8ms   323ms
             Some non-ASCII     String.charCodeAt()   28.8ns   49.2ns  403ns  3.40μs  33.3μs   378μs  3.77ms  32.1ms   323ms
                                Buffer.from()        222.3ns  383.8ns  822ns  5.16μs  61.1μs   581μs  5.38ms  54.6ms   556ms
                                TextEncoder          809.5ns 1052.9ns 1536ns  4.82μs  37.6μs   399μs  3.26ms  32.0ms   370ms

             Only non-ASCII     string-byte-slice     38.8ns  134.0ns  399ns  3.26μs  31.3μs   294μs  2.91ms  28.5ms   287ms
                                String.charCodeAt()   28.8ns  116.0ns  387ns  2.89μs  30.6μs   291μs  2.86ms  29.3ms   287ms
                                Buffer.from()        222.3ns  465.0ns 1571ns 11.47μs 156.6μs  1525μs 14.54ms 148.0ms  1468ms
                                TextEncoder          809.5ns 1102.0ns 1844ns  7.83μs  65.6μs   608μs  6.25ms  66.8ms   682ms

Large slice  Only ASCII         string-byte-slice     38.6ns  103.0ns  748ns  1.26μs  4.91μs  37.4μs  0.60ms  7.54ms  88.1ms
                                String.charCodeAt()   23.5ns   95.4ns  729ns  7.42μs 66.97μs 674.3μs  6.49ms 65.62ms 651.0ms
                                Buffer.from()        302.6ns  352.2ns  406ns  0.71μs  4.52μs  35.4μs  0.62ms  7.79ms  87.2ms
                                TextEncoder          975.4ns  970.3ns 1491ns  3.12μs 20.00μs 107.7μs  1.44ms 16.48ms 214.5ms

             Mostly ASCII       string-byte-slice     38.8ns   92.4ns  747ns  4.02μs  19.3μs   195μs  2.21ms  23.7ms   279ms
             Very few non-ASCII String.charCodeAt()   28.8ns   93.2ns  832ns  7.89μs  71.4μs   702μs  7.04ms  69.3ms   692ms
                                Buffer.from()        222.3ns  400.5ns  529ns  2.07μs  19.6μs   184μs  2.15ms  22.0ms   225ms
                                TextEncoder          809.5ns 1054.1ns 1614ns  4.17μs  27.7μs   178μs  2.27ms  23.8ms   284ms

             Mostly ASCII       string-byte-slice     38.8ns   60.5ns  467ns  6.61μs  43.1μs   391μs  3.64ms  41.4ms   399ms
             Some non-ASCII     String.charCodeAt()   28.8ns   49.5ns  441ns  4.83μs  36.2μs   455μs  4.50ms  44.8ms   401ms
                                Buffer.from()        222.3ns  400.5ns  949ns  6.50μs  73.8μs   672μs  6.63ms  68.0ms   685ms
                                TextEncoder          809.5ns 1087.9ns 1765ns  5.32μs  46.3μs   485μs  4.18ms  41.6ms   459ms

             Only non-ASCII     string-byte-slice     38.8ns  125.0ns  466ns  3.79μs  38.5μs   373μs  3.68ms  36.7ms   366ms
                                String.charCodeAt()   28.8ns  124.0ns  457ns  3.63μs  37.7μs   370μs  3.67ms  37.2ms   365ms
                                Buffer.from()        222.3ns  458.0ns 1655ns 12.85μs 172.7μs  1662μs 16.14ms 165.7ms  1647ms
                                TextEncoder          809.5ns 1114.0ns 2142ns  8.19μs  75.0μs   697μs  7.13ms  76.1ms   775ms

Related projects

• string-byte-length: Get the UTF-8 byte length of a string
• truncate-json: Truncate a JSON string

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!