utfx

!utfx - A compact library to encode, decode and convert UTF8 / UTF16 in JavaScript.
====
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.

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
---

$3

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

$3

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.

$3

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.

$3

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

$3

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.

$3

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.

$3

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

$3

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

$3

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

$3

Calculates the byte length of an UTF8 code point.

| Parameter | Type | Description
|-----------------|-----------------|---------------
| cp | number | UTF8 code point
| @returns | number | Byte length

$3

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

$3

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.

$3

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

$3

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

$3

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

$3

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.

$3

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

$3

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

$3

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

FAQ and examples
----------------
* Wiki

License
-------
Apache License, Version 2.0