Skip to content

Latest commit

 

History

History
304 lines (219 loc) · 10.9 KB

data.md

File metadata and controls

304 lines (219 loc) · 10.9 KB

Data

Copyright 2017-2024 Moddable Tech, Inc.
Revised: March 29, 2024

Table of Contents

class Base64

Note: Base64 encoding and decoding are now supported directly in JavaScript. See the Base64 proposal for details. The Moddable SDK no longer uses the Base64 module. The Base64 module is still supported for compatibility but it is not recommended for use in new code.

The Base64 class provides static functions to encode and decode using the Base64 algorithm defined in RFC 4648.

import Base64 from "base64";

Include the module's manifest to use it in a project:

"include": [
	"$(MODULES)/data/base64/manifest.json"
]

static decode(str)

The decode function takes a String encoded in Base64 and returns an ArrayBuffer with the decoded bytes.

trace(Base64.decode("aGVsbG8sIHdvcmxk") + "\n");
// output: "hello, world"

static encode(data)

The encode function takes a String or buffer and returns an ArrayBuffer containing the data with Base64 encoding applied.

trace(Base64.encode("hello, world") + "\n");
// output: "aGVsbG8sIHdvcmxk"

Note: When a string is provided, its contents are treated as UTF-8 encoded characters when performing Base64 encoding.

class Hex

Note: Hex encoding and decoding are now supported directly in JavaScript. See the proposal for details. The Moddable SDK no longer uses the Hex module. The Hex module is still supported for compatibility but it is not recommended for use in new code.

The Hex class provides static functions to convert between an ArrayBuffer and hexadecimal encoded String values.

import Hex from "hex";

Include the module's manifest to use it in a project:

"include": [
	"$(MODULES)/data/hex/manifest.json"
]

static toBuffer(string [, separator])

The toBuffer function converts a hexadecimal encoded String, with optional separator, to an ArrayBuffer.

let b0 = Hex.toBuffer("0123456789abcdef");
let b1 = Hex.toBuffer("01:23:45:67:89:AB:CD:EF", ":");

The hexadecimal digits may be uppercase or lowercase. If the optional separator argument is provided, it must appear between each pair of hexadecimal digits.

The optional separator must be a single character in the 7-bit ASCII range.

static toString(buffer [[, separator], hexChars]);

The toString function converts a buffer to a hexadecimal encoded String.

let buffer = Hex.toBuffer("0123456789abcdef");
let s0 = Hex.toString(buffer, ".");
// s0 is 01.23.45.67.89.AB.CD.EF
let s1 = Hex.toString(buffer);
// s1 is 0123456789ABCDEF

The optional separator must be a single character in the 7-bit ASCII range.

The optional hexChars argument may contain 16 characters to use for the hexadecimal encoding. The characters must be 7-bit ASCII:

let buffer = Hex.toBuffer("0123456789abcdef");
let s0 = Hex.toString(buffer, "-", "0123456789abwxyz");
// s0 is 01-23-45-67-89-ab-wx-yz

class CRC8, CRC16

The CRC8 and CRC16 classes calculate CRC checksums on data.

import {CRC8} from "crc";
import {CRC16} from "crc";

Include the module's manifest to use it in a project:

"include": [
	"$(MODULES)/data/crc/manifest.json"
]

CRC8(polynomial [, initial [, reflectInput [, reflectOutput [, xorOutput]]]])

CRC16(polynomial [, initial [, reflectInput [, reflectOutput [, xorOutput]]]])

The CRC8 and CRC16 functions take a number of options used to specify the CRC checksum to calculate.

Parameter Default Description
polynomial (none) Polynomial to use (required)
initial 0 Initial CRC accumulator value (optional)
reflectInput false If true, each input byte is reflected (bits used in reverse order) before being used (optional)
reflectOutput false If true, each output byte is reflected before being returned. The output reflection is done over the whole CRC value (optional)
xorOutput 0 Value to XOR to the final CRC value (optional)

The polynomial, initial and xorOutput values are 8-bit integers for CRC8 and 16-bit integers for CRC16.

The crc example demonstrates the definition of the parameters for a number of common CRC checksums:

  • CRC-8
  • CRC-8/CDMA2000
  • CRC-8/DARC
  • CRC-8/DVB-S2
  • CRC-8/EBU
  • CRC-8/I-CODE
  • CRC-8/ITU
  • CRC-8/MAXIM
  • CRC-8/ROHC
  • CRC-8/WCDM
  • CRC-16/CCITT-FALSE
  • CRC-16/ARC
  • CRC-16/ARG-CCITT
  • CRC-16/BUYPASS
  • CRC-16/CDMA2000
  • CRC-16/DDS-110
  • CRC-16/DECT-R
  • CRC-16/DECT-X
  • CRC-16/DNP
  • CRC-16/EN-13757
  • CRC-16/GENIBUS
  • CRC-16/MAXIM
  • CRC-16/MCRF4XX
  • CRC-16/RIELLO
  • CRC-16/T10-DIF
  • CRC-16/TELEDISK
  • CRC-16/TMS37157
  • CRC-16/USB
  • CRC-A
  • CRC-16/KERMIT
  • CRC-16/MODBUS
  • CRC-16/X-25
  • CRC-16/XMODE

close()

The close function frees resources associated with the CRC checksum calculation.

checksum(buffer)

The checksum function applies the CRC calculation to the data provided in buffer. The CRC checksum is returned.

The buffer parameter may be a String or buffer.

The checksum function may be called multiple times. Each time it is called the CRC updated and returned. Call the reset function to start a new calculation.

reset()

The reset function clears the CRC accumulator to the initial value.

class QRCode

The QRCode class generates QR Code data from Strings and buffers. The data may then be rendering in various ways. Extensions are provided to Poco and Piu to efficiently render QR Codes. The core implementation is the QR Code Generator Library from Project Nayuki.

import qrCode from "qrcode";

Include the module's manifest to use them in a project:

"include": [
	"$(MODULES)/data/qrcode/manifest.json"
]

For additional details see the article QR Code module for the Moddable SDK.

qrCode(options)

The qrCode function accepts an options object that describes the QR Code to generate. It returns an ArrayBuffer where each byte is 0 or 1 for a white or black pixel. The returned buffer has a size property that indicate the number of cells in one dimension of the generated QR Code.

The following properties are supported in the options object:

Property Description
maxVersion A number between 1 and 40 inclusive indicating the maximum version of the generated QR Code. The version number determines the amount of data the QR Code can contain. The implementation uses the minimum version number possible for the size of the data provided. This property is optional and defaults to 40.
input A String or buffer containing the data to encode into the QR Code. This property is required.

The qrCode function throws an exception if it detects invalid parameters or that there is not enough memory to generate the QR Code.

const code = qrCode({input: "Welcome to Moddable", maxVersion: 4});

// trace QR Code to console
code = new Uint8Array(code);
for (let y = 0; y <= code.size; y++) {
    for (let x = 0; x <= code.size; x++)
        trace(code[(y * code.size) + x] ? "X" : ".", "\n");
    trace("\n");
}

class TextDecoder and class TextEncoder

The TextDecoder and TextEncoder classes implement conversion between JavaScript strings and memory buffers containing UTF-8 data.

import TextDecoder from "text/decoder";
import TextEncoder from "text/encoder";

Include the modules' manifest to use them in a project:

"include": [
	"$(MODULES)/data/text/decoder/manifest.json",
	"$(MODULES)/data/text/encoder/manifest.json"
]

The TextDecoder implements the TextDecoder class as specified by WHATWG. It accepts only UTF-8 input data.

The TextEncoder implements the TextEncoder class as specified by WHATWG. The implementation includes encodeInto().

zlib: class Inflate and class Deflate

The Inflate and Deflate classes implement zlib decompression and compression. The JavaScript API follows the API defined by the pako library.

import Inflate from "inflate";
import Deflate from "deflate";

Include the modules' manifest to use them in a project:

"include": [
	"$(MODULES)/data/zlib/manifest_deflate.json",
	"$(MODULES)/data/zlib/manifest_inflate.json"
]

The inflate example demonstrates how to decompress data as a one-shot operation and using the onData callback for streaming.

Note: A significant amount of memory is required for zlib decompression and especially for compression. These libraries may not work on all microcontrollers because of memory constraints.

class URL and class URLSearchParams

The URL and URLSearchParams classes provide utilities for working with URLs and their search parameters.

import URL from "url";
import {URL, URLSearchParams} from "url";

Include the module's manifest to use it in a project:

"include": [
	"$(MODULES)/data/url/manifest.json"
]

URL implements the URL class as specified by WHATWG. The implementation fully conforms to the standard with two exceptions: Punycode and IDNA support are unimplemented. These are used primarily for the display and safe handling of user-entered URLs in browsers, which are not generally a concern on embedded systems. With some effort (and increase in code size), the implementation could support both.

URLSearchParams implements the URLSearchParams class as specified by WHATWG.

Tests for both are included in the Moddable SDK. They are based on the tests used to validate these APIs in web browsers.