Difference between revisions of "String.pack"
From GiderosMobile
(Created page with "__NOTOC__ '''Available since:''' Gideros 2022.1<br/> '''Class:''' string<br/> === Description === Returns a binary string containing the provided arguments. The descripti...") |
|||
| (2 intermediate revisions by one other user not shown) | |||
| Line 5: | Line 5: | ||
=== Description === | === Description === | ||
Returns a binary string containing the provided arguments. The description in the first argument, which must be a string, determines the way the remaining arguments are packed. | Returns a binary string containing the provided arguments. The description in the first argument, which must be a string, determines the way the remaining arguments are packed. | ||
| − | < | + | <syntaxhighlight lang="lua"> |
(string) = string.pack(format,s1,s2,...) | (string) = string.pack(format,s1,s2,...) | ||
| − | </ | + | </syntaxhighlight> |
| + | |||
| + | 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). | ||
=== Parameters === | === Parameters === | ||
Latest revision as of 01:05, 18 October 2023
Available since: Gideros 2022.1
Class: string
Description
Returns a binary string containing the provided arguments. The description in the first argument, which must be a string, determines the way the remaining arguments are packed.
(string) = string.pack(format,s1,s2,...)
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).
Parameters
format: (string) determines the way the strings are packed
s1: (string) string to pack
s2: (string) string to pack
...: (string) string to pack
Return values
Returns (string) the packed string
