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

These were backported a year ago, yet are not even mentioned once anywhere on the devhub.
https://developer.roblox.com/en-us/api-reference/lua-docs/string
https://www.lua.org/manual/5.3/manual.html#6.4.2

11 Likes

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

2 Likes

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

maybe it will be added to the api documentation soon

1 Like

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

1 Like

still nothing :’{ it is in the autocomplete tho

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

6 Likes

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.

3 Likes

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

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

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

1 Like

This has been corrected, thanks for your report!

1 Like

This topic was automatically closed after 15 hours. New replies are no longer allowed.