Navigation :

N2 Library

Overview

The N2 Library is a precompiled object library that contains helper functions to increase runtime speed, as required. These functions are accessible directly from Lua.

Most functions in this library are used by other NCC API features and are not intended for direct access, so will only be lightly covered here.

This library is automatically included by the NCC API and can be accessed through it directly, e.g.:

x = ncc.logic.profile.u32_to_bin (12345) -- x = "\x30\x39"


Parameters	bytes	Binary string containing 1, 2, 4, or 8 bytes (mandatory).
Returns	The signed integer value encoded in `bytes.`
Errors	If `bytes` is not 1, 2, 4, or 8 bytes in length, the following error will be raised: `Need 4, 2, or 1 byte(s) for sint, have <bytes length>.`
Usage	This function decodes a signed integer from a binary string. `x = ncc.logic.profile.bin_to_sint ("\xff") -- x == -1`


Parameters	bytes	Binary string containing 1, 2, 4, or 8 bytes (mandatory).
Returns	The unsigned integer value encoded in `bytes.`
Errors	If `bytes` is not 1, 2, 4, or 8 bytes in length, the following error will be raised: `Need 8, 4, 2, or 1 byte(s) for uint, have <bytes length>.`
Usage	This function decodes an unsigned integer from a binary string. `x = ncc.logic.profile.bin_to_uint ("\x09") -- x = 9`


Parameters	num	Integer value that can be stored in 8 bytes (mandatory).
Returns	A binary string of length 8.
Errors	None.
Usage	This function encodes an integer value in an 8-byte binary string. `x = ncc.logic.profile.u32_to_bin (1234567890123) -- x = "\x00\x00\x01\x1F\x71\xFB\x04\xCB"`


Parameters	num	Integer value that can be stored in 4 bytes (mandatory).
Returns	A binary string of length 4.
Errors	None.
Usage	This function encodes an integer value in a 4-byte binary string. `x = ncc.logic.profile.u32_to_bin (1234567890) -- x = "\x49\x96\x02\xD2"`


Parameters	num	Integer value that can be stored in 2 bytes (mandatory).
Returns	A binary string of length 2.
Errors	None.
Usage	This function encodes an integer value in a 2-byte binary string. `x = ncc.logic.profile.u16_to_bin (12345) -- x = "\x30\x39"`


Parameters	num	Integer value that can be stored in 1 byte (mandatory).
Returns	A binary string of length 1.
Errors	None.
Usage	This function encodes an integer value in a 1-byte binary string. `x = ncc.logic.profile.u8_to_bin (123) -- x = "\x7B"`


Parameters	bytes	Binary string (mandatory).
Returns	A Lua table with tags => binary strings, e.g.: `{ ["100"] = "0F0F" }`
Errors	If more than one parameter is provided: `Too many parameters, at most 1 is allowed.` If the `bytes` provided is not a string: `Bytes must be string not <bytes type>.` If the length of `bytes` is not a multiple of 4: `Bytes len of <bytes length> is not a multiple of four bytes.` If the length of `bytes` is less than 4 (the minimum for a profile num_entries field): `Bytes insufficient length for num_entries.` If the length of `bytes` is not long enough for the encoded num_entries field): `Bytes insufficient length for <num_entries> entries.` If an encoded data offset does not point to a valid location in `bytes`: `Data <data offset> offset must be longword aligned.` If the end of an encoded data offset points past the end of `bytes`: `Data offset + 4 = <data offset> falls beyond end of bytes.`
Usage	Decode the raw bytes of a provided profile block (as stored in the database) into a Lua table. All tags are decoded into binary strings and no attempt is made to identify any contained content. This function is not used in the N2 Logic Node.


Parameters	profile	Table of tags => binary strings values, as returned by ncc.logic.profile.decode (mandatory).
Returns	A binary string of raw profile bytes.
Errors	If more than one parameter is provided: `Too many parameters, at most 1 is allowed.` If the profile provided is not a table: `Profile must be table not <profile type>.` If a key in profile is not a number: `Profile keys must be number not <key type>` If a value in profile is not a string: `Profile values must be string not <value type>` If a tag number is negative in profile: `Profile tag <tag number> is negative, not supported.` If a tag number is higher than the supported maximum: `Profile tag <tag number> is > <unsigned long maximum>, not supported.` If a tag number cannot be cast to an integer: `Profile tag <tag number> is not integer, not supported.` If a value length is greater than the supported maximum: `Profile value length <value length> bytes is > <unsigned long maximum> byte limit.` If the total length of the encoded profile is greater than the supported maximum: `Profile total length <profile length> bytes is > <unsigned long maximum> byte limit.` Additionally, some errors are - in theory - impossible: `Profile number of tags mismatch on second pass, impossible!` `Profile entry for tag %d is %s not string on third pass, impossible!`
Usage	Encode a provided profile in a Lua table into the raw bytes of a profile block (as stored in the database). All tags must be numbers, and all values must be strings (i.e. binary data). No content encoding is performed. This function is not used in the N2 Logic Node.


Parameters	bytes	Binary string (mandatory).
Returns	A Lua table with prefix => value strings, e.g.: `{ ["1234"] = "0", ["4567"] = "0" }`
Errors	If the `bytes` provided is not a string: `Bytes must be string not <bytes type>.` If the prefix path goes beyond what NCC supports: `Max path length <maximum path length (38)> reached in prefix tree, cannot recurse further.` If the offset of a node does not provide enough room for the node: `Insufficient bytes to process uncompressed node. Have <available bytes>, need 4.` `Insufficient bytes to process compressed node. Have <available bytes>, need 8.` If the characters at the node will not fit in the available bytes: `Insufficient bytes to process compressed node with <number of path chars>` `path chars. Have <available bytes>, need <required bytes>.` If the sub-nodes at the node will not fit in the available bytes: `Insufficient bytes to process uncompressed node with <number of sub-nodes> sub-nodes.` `Have <available bytes>, need <required bytes>.` If the maximum path length would be exceeded while processing nodes: `Max path length <maximum path length (38)> exceeded in prefix tree` `trying to add <number of path chars> to <current path length>.` If the offset provided indicates a circular definition: `Sub-Node offset <next offset> is not > current offset <current offset>.` `Possible loop detected.`
Usage	Decode the raw bytes of a provided prefix tree into a Lua table. These values will indicate the same output as from the acsProfile tool. Prefix trees within NCC can have values at branches or leaves, depending on their type. This function is called by the ncc.profile functions for reading and writing prefix trees.


Parameters	ptree	Table of prefix => value strings values, as returned by ncc.logic.ptree.decode (mandatory).
Returns	A binary string of raw prefix tree bytes.
Errors	If the `ptree` provided is not a table: `Prefix tree must be table not <ptree type>.` If a key in `ptree` is not of type string: `Profile table keys must be string not <key type>` If a value in `ptree` is greater than the allowed maximum: `Profile table value <value> is > <unsigned long maximum>, not supported.` If a value in `ptree` is not able to be cast to an unsigned integer: `Profile table value <value> is not integer, not supported.` If a key in `ptree` has a length that would exceed the maximum NCC path: `Profile key length <key length> bytes is > <maximum path length (38)> byte limit.`
Usage	Encode the provided prefix tree `ptree` in a Lua table into the raw bytes of a profile field suitable for storing in NCC. This function is called by the ncc.profile functions for reading and writing prefix trees.