global sio

Binary input from strings with sio (string input-output)

This library provides a set of functions for reading numbers from a string and in addition to the regular io library functions.

There are eight additional little endian variants for the cardinal[1-4] and integer[1-4] readers: cardinal[1-4]le and integer[1-4]le.

Reference:

• Corresponding C source code: liolibext.c
• Source file of the LuaTeX manual: luatex-lua.tex#L701-714

😱 Types incomplete or incorrect? 🙏 Please contribute!

---

methods

---

sio.readcardinal1

---

function sio.readcardinal1(
  text: string,
  position: integer
) ->  integer?

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - A 1 byte unsigned integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 1 byte unsigned integer (8-bit) from a string.

Example:

assert.is_nil(sio.readcardinal1("test", 0))
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readcardinal1("test", 1), 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(sio.readcardinal1("test", 2), 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(sio.readcardinal1("test", 3), 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readcardinal1("test", 4), 116)
assert.is_nil(sio.readcardinal1("test", 5))

Reference:

• Corresponding C source code: liolibext.c#L124-L135

@see fio.readcardinal1

sio.readcardinal2

---

function sio.readcardinal2(
  text: string,
  position: integer
) ->  integer?

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - A 2 byte unsigned integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 2 byte unsigned integer (16-bit) from a string.

Example:

assert.equals(sio.readcardinal2("test", 0), 116)
-- t.e: decimal=29797 hexadecimal=74.65 binary=01110100.01100101
assert.equals(sio.readcardinal2("test", 1), 29797)
-- s.t: decimal=29556 hexadecimal=73.74 binary=01110011.01110100
assert.equals(sio.readcardinal2("test", 3), 29556)
assert.is_nil(sio.readcardinal2("test", 4))

Reference:

• Corresponding C source code: liolibext.c#L160-L172

@see fio.readcardinal2

sio.readcardinal3

---

function sio.readcardinal3(
  text: string,
  position: integer
) ->  integer?

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - A 3 byte unsigned integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 3 byte unsigned integer (24-bit) from a string.

Example:

assert.equals(sio.readcardinal3("test", 0), 29797)
-- l.u.a: decimal=7107937 hexadecimal=6C.75.61 binary=01101100.01110101.01100001
assert.equals(sio.readcardinal3("luatex", 1), 7107937)
-- t.e.x: decimal=7628152 hexadecimal=74.65.78 binary=01110100.01100101.01111000
assert.equals(sio.readcardinal3("luatex", 4), 7628152)
assert.is_nil(sio.readcardinal3("test", 5))

Reference:

• Corresponding C source code: liolibext.c#L212-L225

@see fio.readcardinal3

sio.readcardinal4

---

function sio.readcardinal4(
  text: string,
  position: integer
) ->  integer?

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - A 4 byte unsigned integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 4 byte unsigned integer (32-bit) from a string.

Example:

assert.equals(sio.readcardinal4("test", 0), 7628147)
-- t.e.s.t:
-- decimal=1952805748
-- hexadecimal=74.65.73.74
-- binary=01110100.01100101.01110011.01110100
assert.equals(sio.readcardinal4("test", 1), 1952805748)
assert.is_nil(sio.readcardinal4("test", 2))

Reference:

• Corresponding C source code: liolibext.c#L268-L282

@see fio.readcardinal4

sio.readcardinaltable

---

function sio.readcardinaltable(
  text: string,
  position: integer,
  number: integer,
  bytes: (1|2|3|4)
) ->  table<integer,integer>

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@param number - The number of integers in the resulting table.

@param bytes - Specify 1 for 1 byte unsigned integers, 2 for a 2 byte unsigned integers.

Read number unsigned integers of bytes as a table from a string.

Example:

local t = sio.readcardinaltable("test", 1, 4, 1)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(t[1], 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(t[2], 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(t[3], 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(t[4], 116)

@see fio.readcardinaltable

sio.readcardinal1le

---

function sio.readcardinal1le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 1 byte unsigned little endian integer (8-bit) from a string.

Example:

assert.is_nil(sio.readinteger1le("test", 0))
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readinteger1le("test", 1), 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(sio.readinteger1le("test", 2), 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(sio.readinteger1le("test", 3), 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readinteger1le("test", 4), 116)
assert.is_nil(sio.readinteger1le("test", 5))

Reference:

• Corresponding C source code: liolibext.c#L124-L135

little endian variant

@see fio.readcardinal1le

sio.readcardinal2le

---

function sio.readcardinal2le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 2 byte unsigned little endian integer (16-bit) from a string.

Example:

assert.equals(sio.readinteger2le("test", 0), 29696)
assert.equals(sio.readinteger2le("test", 1), 25972)
assert.equals(sio.readinteger2le("test", 2), 29541)
assert.equals(sio.readinteger2le("test", 3), 29811)
assert.is_nil(sio.readinteger2le("test", 4))

Reference:

• Corresponding C source code: liolibext.c#L173-L185

little endian variant

@see fio.readcardinal2le

sio.readcardinal3le

---

function sio.readcardinal3le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 3 byte unsigned little endian integer (24-bit) from a string.

Example:

assert.equals(sio.readinteger3le("test", 0), 6648832)
assert.equals(sio.readinteger3le("test", 1), 7562612)
assert.equals(sio.readinteger3le("test", 2), 7631717)
assert.is_nil(sio.readinteger3le("test", 3))

Reference:

• Corresponding C source code: liolibext.c#L226-L239

little endian variant

@see fio.readcardinal3le

sio.readcardinal4le

---

function sio.readcardinal4le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 4 byte unsigned little endian integer (32-bit) from a string.

Example:

assert.equals(sio.readinteger4le("test", 0), 1936028672)
assert.equals(sio.readinteger4le("test", 1), 1953719668)
assert.equals(sio.readinteger4le("test", 2), nil)

Reference:

• Corresponding C source code: liolibext.c#L283-L297

little endian variant

@see fio.readcardinal4le

sio.readinteger1

---

function sio.readinteger1(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - a 1 byte signed integer

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 1 byte signed integer (8-bit) from a string.

Example:

assert.is_nil(sio.readinteger1("test", 0))
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readinteger1("test", 1), 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(sio.readinteger1("test", 2), 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(sio.readinteger1("test", 3), 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readinteger1("test", 4), 116)
assert.is_nil(sio.readinteger1("test", 5))

Reference:

• Corresponding C source code: liolibext.c#L444-L458

@see fio.readinteger1

sio.readinteger2

---

function sio.readinteger2(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - a 2 byte signed integer

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 2 byte signed integer (16-bit) from a string.

Example:

assert.equals(sio.readinteger2("test", 0), 116)
assert.equals(sio.readinteger2("test", 1), 29797)
assert.equals(sio.readinteger2("test", 2), 25971)
assert.equals(sio.readinteger2("test", 3), 29556)
assert.is_nil(sio.readinteger2("test", 4))

Reference:

• Corresponding C source code: liolibext.c#L485-L500

@see fio.readinteger2

sio.readinteger3

---

function sio.readinteger3(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - a 3 byte signed integer

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 3 byte signed integer (24-bit) from a string.

Example:

assert.equals(sio.readinteger3("test", 0), 29797)
assert.equals(sio.readinteger3("test", 1), 7628147)
assert.equals(sio.readinteger3("test", 2), 6648692)
assert.is_nil(sio.readinteger3("test", 3))

Reference:

• Corresponding C source code: liolibext.c#L545-561

@see fio.readinteger3

sio.readinteger4

---

function sio.readinteger4(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@return - a 4 byte signed integer

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 4 byte signed integer (32-bit) from a file.

Example:

assert.equals(sio.readinteger4("test", 0), 7628147)
assert.equals(sio.readinteger4("test", 1), 1952805748)
assert.is_nil(sio.readinteger4("test", 2))

Reference:

• Corresponding C source code: liolibext.c#L609-626

@see fio.readinteger4

sio.readintegertable

---

function sio.readintegertable(
  text: string,
  position: integer,
  number: integer,
  bytes: (1|2|3|4)
) ->  table<integer,integer>

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@param number - The number of integers in the resulting table.

@param bytes - Specify 1 for 1 byte signed integers, 2 for a 2 byte signed integers, and so on.

Read number signed integers of bytes as a table from a string.

Example:

local t = sio.readintegertable("test", 1, 4, 1)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(t[1], 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(t[2], 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(t[3], 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(t[4], 116)

Reference:

• Corresponding C source code: liolibext.c#L717-798

@see fio.readintegertable

sio.readinteger1le

---

function sio.readinteger1le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 1 byte signed little endian integer (8-bit) from a string.

Example:

assert.is_nil(sio.readinteger1le("test", 0))
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readinteger1le("test", 1), 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(sio.readinteger1le("test", 2), 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(sio.readinteger1le("test", 3), 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(sio.readinteger1le("test", 4), 116)
assert.is_nil(sio.readinteger1le("test", 5))

Reference:

• Corresponding C source code: liolibext.c#L444-L458 little endian variant

@see fio.readinteger1le

sio.readinteger2le

---

function sio.readinteger2le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 2 byte signed little endian integer (16-bit) from a string.

Example:

assert.equals(sio.readinteger2le("test", 0), 29696)
assert.equals(sio.readinteger2le("test", 1), 25972)
assert.equals(sio.readinteger2le("test", 2), 29541)
assert.equals(sio.readinteger2le("test", 3), 29811)
assert.is_nil(sio.readinteger2le("test", 4))

Reference:

• Corresponding C source code: liolibext.c#L501-L516

little endian variant

@see fio.readinteger2le

sio.readinteger3le

---

function sio.readinteger3le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 3 byte signed little endian integer (24-bit) from a string.

Example:

assert.equals(sio.readinteger3le("test", 0), 6648832)
assert.equals(sio.readinteger3le("test", 1), 7562612)
assert.equals(sio.readinteger3le("test", 2), 7631717)
assert.is_nil(sio.readinteger3le("test", 3))

Reference:

• Corresponding C source code: liolibext.c#L562-578

little endian variant

@see fio.readinteger3le

sio.readinteger4le

---

function sio.readinteger4le(
  text: string,
  position: integer
) ->  integer

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 4 byte signed little endian integer (32-bit) from a string.

Example:

assert.equals(sio.readinteger4le("test", 0), 1936028672)
assert.equals(sio.readinteger4le("test", 1), 1953719668)
assert.equals(sio.readinteger4le("test", 2), nil)

Reference:

• Corresponding C source code: liolibext.c#L627-644

little endian variant

@see fio.readinteger4le

sio.readfixed2

---

function sio.readfixed2(
  text: string,
  position: integer
) ->  number?

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 2 byte float (used in font files) from a string.

Example:

assert.numbers(sio.readfixed2("test", 0), 0.453125)
assert.numbers(sio.readfixed2("test", 1), 116.39453125)
assert.is_nil(sio.readfixed2("test", 2))
assert.is_nil(sio.readfixed2("test", 3))

Reference:

• Corresponding C source code: liolibext.c#L815-828

@see fio.readfixed2

sio.readfixed4

---

function sio.readfixed4(
  text: string,
  position: integer
) ->  number?

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 4 byte float (used in font files) from a string.

Example:

assert.numbers(sio.readfixed4("test", 0), 116.39628601074)
assert.numbers(sio.readfixed4("test", 1), 29797.45098877)
assert.is_nil(sio.readfixed4("test", 2))

Reference:

• Corresponding C source code: liolibext.c#L845-860

@see fio.readfixed4

sio.read2dot14

---

function sio.read2dot14(
  text: string,
  position: integer
) ->  number?

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

Read a 2 byte float (used in font files) from a string.

Example:

assert.numbers(sio.read2dot14("test", 1), 1.8186645507812)
assert.numbers(sio.read2dot14("test", 2), 1.5851440429688)
assert.numbers(sio.read2dot14("test", 3), 1.803955078125)
assert.is_nil(sio.read2dot14("test", 4))

Reference:

• Corresponding C source code: liolibext.c#L876-889
• Corresponding fontforge C source code: mem.c#L101-L107
• Corresponding fontforge C source code: ttf2eps.c#L418-L424

@see fio.read2dot14

sio.readbytes

---

function sio.readbytes(
  text: string,
  position: integer,
  number: integer
) ->  integer ...

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@param number - The number of bytes to be read.

Read number bytes from a string.

Example:

local b1, b2, b3, b4 = sio.readbytes("test", 1, 4)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(b1, 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(b2, 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(b3, 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(b4, 116)

Reference:

• Corresponding C source code: liolibext.c#L982-1001

@see fio.readbytes

sio.readbytetable

---

function sio.readbytetable(
  text: string,
  position: integer,
  number: integer
) ->  table<integer,integer>

@param text - A string to read from.

@param position - The position in bytes from which to read. 1 and not 0 reads from the first byte.

@param number - The number of bytes to be read.

Read number bytes as a table from a string.

Example:

local t = sio.readbytetable("test", 1, 4)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(t[1], 116)
-- e: decimal=101 hexadecimal=65 binary=01100101
assert.equals(t[2], 101)
-- s: decimal=115 hexadecimal=73 binary=01110011
assert.equals(t[3], 115)
-- t: decimal=116 hexadecimal=74 binary=01110100
assert.equals(t[4], 116)

Reference:

• Corresponding C source code: liolibext.c#L945-965

@see fio.readbytetable