Skip to content

Commit c9df4da

Browse files
authored
doc: remove low-level encoding exports from README (#69)
They are still present in the full documentation, with warnings
1 parent 593fe7e commit c9df4da

File tree

1 file changed

+0
-168
lines changed

1 file changed

+0
-168
lines changed

README.md

Lines changed: 0 additions & 168 deletions
Original file line numberDiff line numberDiff line change
@@ -256,174 +256,6 @@ Prefer using strict throwing methods for cryptography applications._
256256

257257
Throws on non-even byte length.
258258

259-
### @exodus/bytes/single-byte.js <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/single-byte.js?style=flat-square)</sub>
260-
261-
Decode / encode the legacy single-byte encodings according to the
262-
[Encoding standard](https://encoding.spec.whatwg.org/)
263-
([§9](https://encoding.spec.whatwg.org/#legacy-single-byte-encodings),
264-
[§14.5](https://encoding.spec.whatwg.org/#x-user-defined)),
265-
and [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859) `iso-8859-*` mappings.
266-
267-
```js
268-
import { createSinglebyteDecoder, createSinglebyteEncoder } from '@exodus/bytes/single-byte.js'
269-
import { windows1252toString, windows1252fromString } from '@exodus/bytes/single-byte.js'
270-
import { latin1toString, latin1fromString } from '@exodus/bytes/single-byte.js'
271-
```
272-
273-
> [!WARNING]
274-
> This is a lower-level API for single-byte encodings.
275-
> It might not match what you expect, as it supports both WHATWG and unicode.org encodings under
276-
> different names, with the main intended usecase for the latter being either non-web or legacy contexts.
277-
>
278-
> For a safe WHATWG Encoding-compatible API, see `@exodus/bytes/encoding.js` import (and variants of it).
279-
>
280-
> Be sure to know what you are doing and check documentation when directly using encodings from this file.
281-
282-
Supports all single-byte encodings listed in the WHATWG Encoding standard:
283-
`ibm866`, `iso-8859-2`, `iso-8859-3`, `iso-8859-4`, `iso-8859-5`, `iso-8859-6`, `iso-8859-7`, `iso-8859-8`,
284-
`iso-8859-8-i`, `iso-8859-10`, `iso-8859-13`, `iso-8859-14`, `iso-8859-15`, `iso-8859-16`, `koi8-r`, `koi8-u`,
285-
`macintosh`, `windows-874`, `windows-1250`, `windows-1251`, `windows-1252`, `windows-1253`, `windows-1254`,
286-
`windows-1255`, `windows-1256`, `windows-1257`, `windows-1258`, `x-mac-cyrillic` and `x-user-defined`.
287-
288-
Also supports `iso-8859-1`, `iso-8859-9`, `iso-8859-11` as defined at
289-
[unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859)
290-
(and all other `iso-8859-*` encodings there as they match WHATWG).
291-
292-
> [!NOTE]
293-
> While all `iso-8859-*` encodings supported by the [WHATWG Encoding standard](https://encoding.spec.whatwg.org/) match
294-
> [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859), the WHATWG Encoding spec doesn't support
295-
> `iso-8859-1`, `iso-8859-9`, `iso-8859-11`, and instead maps them as labels to `windows-1252`, `windows-1254`, `windows-874`.\
296-
> `createSinglebyteDecoder()` (unlike `TextDecoder` or `legacyHookDecode()`) does not do such mapping,
297-
> so its results will differ from `TextDecoder` for those encoding names.
298-
299-
```js
300-
> new TextDecoder('iso-8859-1').encoding
301-
'windows-1252'
302-
> new TextDecoder('iso-8859-9').encoding
303-
'windows-1254'
304-
> new TextDecoder('iso-8859-11').encoding
305-
'windows-874'
306-
> new TextDecoder('iso-8859-9').decode(Uint8Array.of(0x80, 0x81, 0xd0))
307-
'\x81Ğ' // this is actually decoded according to windows-1254 per TextDecoder spec
308-
> createSinglebyteDecoder('iso-8859-9')(Uint8Array.of(0x80, 0x81, 0xd0))
309-
'\x80\x81Ğ' // this is iso-8859-9 as defined at https://unicode.org/Public/MAPPINGS/ISO8859/8859-9.txt
310-
```
311-
312-
All WHATWG Encoding spec [`windows-*` encodings](https://encoding.spec.whatwg.org/#windows-874) are supersets of
313-
corresponding [unicode.org encodings](https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/), meaning that
314-
they encode/decode all the old valid (non-replacement) strings / byte sequences identically, but can also support
315-
a wider range of inputs.
316-
317-
#### `createSinglebyteDecoder(encoding, loose = false)`
318-
319-
Create a decoder for a supported one-byte `encoding`, given its lowercased name `encoding`.
320-
321-
Returns a function `decode(arr)` that decodes bytes to a string.
322-
323-
#### `createSinglebyteEncoder(encoding, { mode = 'fatal' })`
324-
325-
Create an encoder for a supported one-byte `encoding`, given its lowercased name `encoding`.
326-
327-
Returns a function `encode(string)` that encodes a string to bytes.
328-
329-
In `'fatal'` mode (default), will throw on non well-formed strings or any codepoints which could
330-
not be encoded in the target encoding.
331-
332-
#### `latin1toString(arr)`
333-
334-
Decode `iso-8859-1` bytes to a string.
335-
336-
There is no loose variant for this encoding, all bytes can be decoded.
337-
338-
Same as:
339-
```js
340-
const latin1toString = createSinglebyteDecoder('iso-8859-1')
341-
```
342-
343-
> [!NOTE]
344-
> This is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as those
345-
> alias to `new TextDecoder('windows-1252')`.
346-
347-
Prefer using `isomorphicDecode()` from `@exodus/bytes/encoding.js` or `@exodus/bytes/encoding-lite.js`,
348-
which is identical to this but allows more input types.
349-
350-
#### `latin1fromString(string)`
351-
352-
Encode a string to `iso-8859-1` bytes.
353-
354-
Throws on non well-formed strings or any codepoints which could not be encoded in `iso-8859-1`.
355-
356-
Same as:
357-
```js
358-
const latin1fromString = createSinglebyteEncoder('iso-8859-1', { mode: 'fatal' })
359-
```
360-
361-
Prefer using `isomorphicEncode()` from `@exodus/bytes/encoding.js` or `@exodus/bytes/encoding-lite.js`.
362-
363-
#### `windows1252toString(arr)`
364-
365-
Decode `windows-1252` bytes to a string.
366-
367-
There is no loose variant for this encoding, all bytes can be decoded.
368-
369-
Same as:
370-
```js
371-
const windows1252toString = createSinglebyteDecoder('windows-1252')
372-
```
373-
374-
#### `windows1252fromString(string)`
375-
376-
Encode a string to `windows-1252` bytes.
377-
378-
Throws on non well-formed strings or any codepoints which could not be encoded in `windows-1252`.
379-
380-
Same as:
381-
```js
382-
const windows1252fromString = createSinglebyteEncoder('windows-1252', { mode: 'fatal' })
383-
```
384-
385-
### @exodus/bytes/multi-byte.js <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/multi-byte.js?style=flat-square)</sub>
386-
387-
Decode / encode the legacy multi-byte encodings according to the
388-
[Encoding standard](https://encoding.spec.whatwg.org/)
389-
([§10](https://encoding.spec.whatwg.org/#legacy-multi-byte-chinese-(simplified)-encodings),
390-
[§11](https://encoding.spec.whatwg.org/#legacy-multi-byte-chinese-(traditional)-encodings),
391-
[§12](https://encoding.spec.whatwg.org/#legacy-multi-byte-japanese-encodings),
392-
[§13](https://encoding.spec.whatwg.org/#legacy-multi-byte-korean-encodings)).
393-
394-
```js
395-
import { createMultibyteDecoder, createMultibyteEncoder } from '@exodus/bytes/multi-byte.js'
396-
```
397-
398-
> [!WARNING]
399-
> This is a lower-level API for legacy multi-byte encodings.
400-
>
401-
> For a safe WHATWG Encoding-compatible API, see `@exodus/bytes/encoding.js` import (and variants of it).
402-
>
403-
> Be sure to know what you are doing and check documentation when directly using encodings from this file.
404-
405-
Supports all legacy multi-byte encodings listed in the WHATWG Encoding standard:
406-
`gbk`, `gb18030`, `big5`, `euc-jp`, `iso-2022-jp`, `shift_jis`, `euc-kr`.
407-
408-
#### `createMultibyteDecoder(encoding, loose = false)`
409-
410-
Create a decoder for a supported legacy multi-byte `encoding`, given its lowercased name `encoding`.
411-
412-
Returns a function `decode(arr, stream = false)` that decodes bytes to a string.
413-
414-
The returned function will maintain internal state while `stream = true` is used, allowing it to
415-
handle incomplete multi-byte sequences across multiple calls.
416-
State is reset when `stream = false` or when the function is called without the `stream` parameter.
417-
418-
#### `createMultibyteEncoder(encoding, { mode = 'fatal' })`
419-
420-
Create an encoder for a supported legacy multi-byte `encoding`, given its lowercased name `encoding`.
421-
422-
Returns a function `encode(string)` that encodes a string to bytes.
423-
424-
In `'fatal'` mode (default), will throw on non well-formed strings or any codepoints which could
425-
not be encoded in the target encoding.
426-
427259
### @exodus/bytes/bigint.js <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/bigint.js?style=flat-square)</sub>
428260

429261
Convert between BigInt and Uint8Array

0 commit comments

Comments
 (0)