{unpack:string}

Description

Converts a packed (binary) string to its hexadecimal text form - the AA counterpart of PHP bin2hex() and the AA function unpack_id(). AA historically stores item IDs as 16 raw bytes to save space; unpack turns such a packed value back into the readable 32-character hexadecimal long ID. More generally it hex-encodes the bytes of any string: each input byte becomes two lowercase hex digits. The input is NOT trimmed, so leading or trailing spaces are encoded too (a space becomes 20). Edge case: a single 0 passed as the whole argument is read by AA as an empty argument and yields empty output (not the hex 30). Empty input also yields empty output. The inverse operation is packid - but note that round-tripping arbitrary binary through templates is lossy (non-printable bytes degrade to a question mark), so use packid/unpack in templates only for printable data.

Parameters

string required default (empty)

The packed (binary) string to hex-encode. Usually a 16-byte packed item ID, but any byte string works: each byte becomes two lowercase hex digits. Not trimmed - surrounding spaces are encoded (a space becomes 20). A single 0 as the whole argument is read by AA as an empty argument, so it yields empty output (not the hex 30).

Examples

test[{unpack:ABC}]
Expected[414243]
Actual[414243]
Hex-encode the bytes of a string: each byte becomes two lowercase hex digits. The three ASCII letters A B C are bytes 65 66 67, which in hex are 41 42 43.
test[{unpack:}]
Expected[]
Actual[]
Empty input gives empty output - there are no bytes to encode.
virtual[{unpack:{packid:a65d19971986e750761f0efcd9a16b1b}}]
Expected(intended: the same long id back; in practice a template roundtrip corrupts the binary - see description)
Actual[3f5d193f193f3f50761f0e3fd9a16b1b]
The conceptual inverse of packid for a real item ID: packid would pack a 32-character long id into 16 raw bytes and unpack would read them back. IMPORTANT TRAP: doing this roundtrip inside a template is LOSSY. The packed bytes are arbitrary binary, and AA passes the intermediate result through a text path that is not binary-safe, so bytes outside printable ASCII are replaced by a question mark (byte 3f). The example actually returns 3f5d193f193f3f50... not the original id. unpack only round-trips cleanly when the packed bytes are printable (see the Hello example above). To read a stored packed ID, let AA unpack it at the database layer (the long id you already see in templates IS the unpacked form); do not re-pack and unpack it in a template.
test[{unpack: ab }]
Expected[20616220]
Actual[20616220]
unpack does NOT trim its argument. The leading and trailing spaces are encoded too: a space is byte 32, hex 20, so the result is 20 61 62 20 (space, a, b, space).
test[{unpack:{packid:48656c6c6f}}]
Expected[48656c6c6f]
Actual[48656c6c6f]
unpack is the inverse of packid. packid packs the hex string 48656c6c6f into the 5 raw bytes of the word Hello; unpack turns those bytes straight back into the same hex.
test[{unpack:hi}]
Expected[6869]
Actual[6869]
Another plain string. The letters h and i are bytes 104 and 105, hex 68 and 69.
test[{unpack:0}]
Expected[]
Actual[]
Edge case worth knowing: a single 0 as the whole argument is read by AA as an empty argument, so the output is empty - NOT the hex 30 you would get for a literal digit. Two zeros, {unpack#:00}, are coerced to the number 0 and unpack returns 0. Only multi-character non-zero input is hex-encoded byte by byte.
← All expressions