# utfx **Repository Path**: makerbob/utfx ## Basic Information - **Project Name**: utfx - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-03-28 - **Last Updated**: 2021-03-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ![utfx - A compact library to encode, decode and convert UTF8 / UTF16 in JavaScript.](https://raw.github.com/dcodeIO/utfx/master/utfx.png) ==== **utfx** is a compact library to encode, decode and convert UTF8 / UTF16 in JavaScript using arbitrary sources and destinations through the use of successively called functions, basically eliminating [memory overhead](https://github.com/dcodeIO/utfx/wiki#faq). The standalone library is also capable of using binary strings and arrays (with the usual overhead) and provides polyfills for `String.fromCodePoint` and `String#codePointAt`. API --- ### encodeUTF8(src, dst) Encodes UTF8 code points to UTF8 bytes. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null) | number* | Code points source, either as a function returning the next code point respectively `null` if there are no more code points left or a single numeric code point. | dst | *function(number)* | Bytes destination as a function successively called with the next byte ### decodeUTF8(src, dst) Decodes UTF8 bytes to UTF8 code points. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null)* | Bytes source as a function returning the next byte respectively `null` if there are no more bytes left. | dst | *function(number)* | Code points destination as a function successively called with each decoded code point. | **@throws** | *RangeError* | If a starting byte is invalid in UTF8 | **@throws** | *Error* | If the last sequence is truncated. Has an array property `bytes` holding the remaining bytes. ### UTF16toUTF8(src, dst) Converts UTF16 characters to UTF8 code points. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null)* | Characters source as a function returning the next char code respectively `null` if there are no more characters left. | dst | *function(number)* | Code points destination as a function successively called with each converted code point. ### UTF8toUTF16(src, dst) Converts UTF8 code points to UTF16 characters. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null) | number* | Code points source, either as a function returning the next code point respectively `null` if there are no more code points left or a single numeric code point. | dst | *function(number)* | Characters destination as a function successively called with each converted char code. | **@throws** | *RangeError* | If a code point is out of range ### encodeUTF16toUTF8(src, dst) Converts and encodes UTF16 characters to UTF8 bytes. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null)* | Characters source as a function returning the next char code respectively `null` if there are no more characters left. | dst | *function(number)* | Bytes destination as a function successively called with the next byte. ### decodeUTF8toUTF16(src, dst) Decodes and converts UTF8 bytes to UTF16 characters. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null)* | Bytes source as a function returning the next byte respectively `null` if there are no more bytes left. | dst | *function(number)* | Characters destination as a function successively called with each converted char code. | **@throws** | *RangeError* | If a starting byte is invalid in UTF8 | **@throws** | *Error* | If the last sequence is truncated. Has an array property `bytes` holding the remaining bytes. ### assertByte(b) Asserts a byte value. | Parameter | Type | Description |-----------------|-----------------|--------------- | b | *number* | 8bit byte value | **@returns** | *number* | Valid byte value | **@throws** | *TypeError* | If the byte value is invalid | **@throws** | *RangeError* | If the byte value is out of range ### assertCharCode(c) Asserts an UTF16 char code. | Parameter | Type | Description |-----------------|-----------------|--------------- | c | *number* | UTF16 char code | **@returns** | *number* | Valid char code | **@throws** | *TypeError* | If the char code is invalid | **@throws** | *RangeError* | If the char code is out of range ### assertCodePoint(cp) Asserts an UTF8 code point. | Parameter | Type | Description |-----------------|-----------------|--------------- | cp | *number* | UTF8 code point | **@returns** | *number* | Valid code point | **@throws** | *TypeError* | If the code point is invalid | **@throws** | *RangeError* | If the code point is out of range ### calculateCodePoint(cp) Calculates the byte length of an UTF8 code point. | Parameter | Type | Description |-----------------|-----------------|--------------- | cp | *number* | UTF8 code point | **@returns** | *number* | Byte length ### calculateUTF8(src) Calculates the number of UTF8 bytes required to store UTF8 code points. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null)* | Code points source as a function returning the next code point respectively `null` if there are no more code points left. | **@returns** | *number* | The number of UTF8 bytes required ### calculateUTF16asUTF8(src) Calculates the number of UTF8 code points respectively UTF8 bytes required to store UTF16 char codes. | Parameter | Type | Description |-----------------|-----------------|--------------- | src | *function():(number | null)* | Characters source as a function returning the next char code respectively `null` if there are no more characters left. | **@returns** | *!Array.<number>* | The number of UTF8 code points at index 0 and the number of UTF8 bytes required at index 1. ### arraySource(a) Creates a source function for an array. | Parameter | Type | Description |-----------------|-----------------|--------------- | a | *!Array.<number>* | Array to read from | **@returns** | *function():(number | null)* | Source function returning the next value respectively `null` if there are no more values left. | **@throws** | *TypeError* | If the argument is invalid ### arrayDestination(a) Creates a destination function for an array. | Parameter | Type | Description |-----------------|-----------------|--------------- | a | *!Array.<number>* | Array to write to | **@returns** | *function(number)* | Destination function successively called with the next value. | **@throws** | *TypeError* | If the argument is invalid ### stringSource(s) Creates a source function for a string. | Parameter | Type | Description |-----------------|-----------------|--------------- | s | *string* | String to read from | **@returns** | *function():(number | null)* | Source function returning the next char code respectively `null` if there are no more characters left. | **@throws** | *TypeError* | If the argument is invalid ### stringDestination() Creates a destination function for a string. | Parameter | Type | Description |-----------------|-----------------|--------------- | **@returns** | *function(number=):(undefined | string)* | Destination function successively called with the next char code. Returns the final string when called without arguments. ### fromCodePoint(var_args) A polyfill for `String.fromCodePoint`. | Parameter | Type | Description |-----------------|-----------------|--------------- | var_args | *...number* | Code points | **@returns** | *string* | JavaScript string | **@throws** | *TypeError* | If arguments are invalid or a code point is invalid | **@throws** | *RangeError* | If a code point is out of range ### codePointAt(s, i) A polyfill for `String#codePointAt`. | Parameter | Type | Description |-----------------|-----------------|--------------- | s | *string* | JavaScript string | i | *number* | Index | **@returns** | *number | undefined* | Code point or `undefined` if `i` is out of range | **@throws** | *TypeError* | If arguments are invalid ### polyfill(override=) Installs utfx as a polyfill for `String.fromCodePoint` and `String#codePointAt` if not implemented. | Parameter | Type | Description |-----------------|-----------------|--------------- | override | *boolean* | Overrides an existing implementation if `true`, defaults to `false` | **@returns** | *!Object.<string,*>* | utfx namespace Usage ----- * **node.js**: `npm install utfx` ```js var utfx = require("utfx"); ... ``` * **Browser**: `` ```js var utfx = dcodeIO.utfx; ... ``` * **Require.js/AMD** ```js require.config({ "paths": { "utfx": "/path/to/utfx.min.js" } }); require(["utfx"], function(utfx) { ... } ``` Downloads --------- * [Distributions](https://github.com/dcodeIO/utfx/tree/master/dist) FAQ and examples ---------------- * [Wiki](https://github.com/dcodeIO/utfx/wiki) License ------- Apache License, Version 2.0