Missing documentation for string.pack, string.unpack and string.packsize

[Luaction]

These were backported a year ago, yet are not even mentioned once anywhere on the devhub.

string

https://www.lua.org/manual/5.3/manual.html#6.4.2

[RuizuKun_Dev (Kitsune)]

documentation is still missing and I have no idea what the function can do

[D0RYU (nici)]

they have some documentations online, but nothing helpful for beginners trying it out

maybe it will be added to the api documentation soon

[CoinTheKit (Evan)]

This is still an issue. I was looking up how to use these functions.

[DrWhoInTARDIS]

still nothing :’{ it is in the autocomplete tho

[Cozecant]

Thanks for your report! We’ve triaged the issue and will follow up when it has been resolved.

[metatablecatmaid (metatablecat)]

Here’s the documentation for these functions if anyone was wondering, ripped directly from the Lua 5.3 docs for them

string.pack(string fmt, ...: ...Variant) -> string
Returns a binary string containing the values ... packed (that is, serialized in binary form) according to the format string fmt

local num = 16
local packed = string.pack("<I4", num)
local b1, b2, b3, b4 = string.byte(packed, 1, 4)
print(string.format("%02X %02X %02X %02X", b1, b2, b3, b4)) --> 10 00 00 00

string.packsize(fmt: string) -> number
Returns the size of a string resulting from string.pack with the given format. The format string cannot have the variable-length options s or z

print(string.packsize("<I4")) --> 4

string.unpack(fmt: string, s: string, pos: number?) -> Tupl
Returns the values packed in string s according to the format string fmt . An optional pos marks where to start reading in s (default is 1). After the read values, this function also returns the index of the first unread byte in s .

local packed = string.unpack("<I4", "\x10\x00\x00\x00")
print(packed) --> 16, 5

Structure Format Strings:
The first argument to string.pack, string.packsize, and string.unpack is a format string, which describes the layout of the structure being created or read.

A format string is a sequence of conversion options. The conversion options are as follows:

• < : sets little endian
• > : sets big endian
• = : sets native endian
• ![n] : sets maximum alignment to n (default is native alignment)
• b : a signed byte ( char )
• B : an unsigned byte ( char )
• h : a signed short (native size)
• H : an unsigned short (native size)
• l : a signed long (native size)
• L : an unsigned long (native size)
• j : a lua_Integer
• J : a lua_Unsigned
• T : a size_t (native size)
• i[n] : a signed int with n bytes (default is native size)
• I[n] : an unsigned int with n bytes (default is native size)
• f : a float (native size)
• d : a double (native size)
• n : a lua_Number
• cn : a fixed-sized string with n bytes
• z : a zero-terminated string
• s[n] : a string preceded by its length coded as an unsigned integer with n bytes (default is a size_t )
• x : one byte of padding
• Xop : an empty item that aligns according to option op (which is otherwise ignored)
• ’ ': (empty space) ignored

(A " [n] " means an optional integral numeral.) Except for padding, spaces, and configurations (options " xX <=>! "), each option corresponds to an argument (in string.pack) or a result (in string.unpack).

For options " !n ", " sn ", " in ", and " In ", n can be any integer between 1 and 16. All integral options check overflows; string.pack checks whether the given value fits in the given size; string.unpack checks whether the read value fits in a Lua integer.

Any format string starts as if prefixed by " !1= ", that is, with maximum alignment of 1 (no alignment) and native endianness.

Alignment works as follows: For each option, the format gets extra padding until the data starts at an offset that is a multiple of the minimum between the option size and the maximum alignment; this minimum must be a power of 2. Options " c " and " z " are not aligned; option " s " follows the alignment of its starting integer.

All padding is filled with zeros by string.pack (and ignored by string.unpack.

TLDR; these functions are used for messing with binary datatypes such as uint32_t etc. Honestly, these functions deserve their own article on the DevHub because they’re pretty complex for just being in a single function doc.

[primo222 (BigGooss)]

Bump. I guess release of “new, improved documentation” isa good reason to finnaly add this… About to year after report

[idevride]

The Luau documentation has some details about the string pack, unpack and packsize functions here:

Library

There is now an official ticket to bring the string docs up to date with the Luau docs in the new Documentation site.

[Cozecant]

This has been corrected, thanks for your report!

string | Roblox Creator Documentation