unpack

        # String.unpack

(from ruby core)
---
    str.unpack(format)    ->  anArray
    str.unpack(format, offset: anInteger)    ->  anArray

---

Decodes *str* (which may contain binary data) according to the format
string, returning an array of each value extracted. The format string
consists of a sequence of single-character directives, summarized in the
table at the end of this entry. Each directive may be followed by a
number, indicating the number of times to repeat with this directive. An
asterisk (```*`'') will use up all remaining elements. The directives
`sSiIlL` may each be followed by an underscore (```_`'') or exclamation
mark (```!`'') to use the underlying platform's native size for the
specified type; otherwise, it uses a platform-independent consistent
size. Spaces are ignored in the format string.

See also String#unpack1,  Array#pack.

    "abc \0\0abc \0\0".unpack('A6Z6')   #=> ["abc", "abc "]
    "abc \0\0".unpack('a3a3')           #=> ["abc", " \000\000"]
    "abc \0abc \0".unpack('Z*Z*')       #=> ["abc ", "abc "]
    "aa".unpack('b8B8')                 #=> ["10000110", "01100001"]
    "aaa".unpack('h2H2c')               #=> ["16", "61", 97]
    "\xfe\xff\xfe\xff".unpack('sS')     #=> [-2, 65534]
    "now=20is".unpack('M*')             #=> ["now is"]
    "whole".unpack('xax2aX2aX1aX2a')    #=> ["h", "e", "l", "l", "o"]

This table summarizes the various formats and the Ruby classes returned
by each.

    Integer       |         |
    Directive     | Returns | Meaning
    ------------------------------------------------------------------
    C             | Integer | 8-bit unsigned (unsigned char)
    S             | Integer | 16-bit unsigned, native endian (uint16_t)
    L             | Integer | 32-bit unsigned, native endian (uint32_t)
    Q             | Integer | 64-bit unsigned, native endian (uint64_t)
    J             | Integer | pointer width unsigned, native endian (uintptr_t)
                  |         |
    c             | Integer | 8-bit signed (signed char)
    s             | Integer | 16-bit signed, native endian (int16_t)
    l             | Integer | 32-bit signed, native endian (int32_t)
    q             | Integer | 64-bit signed, native endian (int64_t)
    j             | Integer | pointer width signed, native endian (intptr_t)
                  |         |
    S_ S!         | Integer | unsigned short, native endian
    I I_ I!       | Integer | unsigned int, native endian
    L_ L!         | Integer | unsigned long, native endian
    Q_ Q!         | Integer | unsigned long long, native endian (ArgumentError
                  |         | if the platform has no long long type.)
    J!            | Integer | uintptr_t, native endian (same with J)
                  |         |
    s_ s!         | Integer | signed short, native endian
    i i_ i!       | Integer | signed int, native endian
    l_ l!         | Integer | signed long, native endian
    q_ q!         | Integer | signed long long, native endian (ArgumentError
                  |         | if the platform has no long long type.)
    j!            | Integer | intptr_t, native endian (same with j)
                  |         |
    S> s> S!> s!> | Integer | same as the directives without ">" except
    L> l> L!> l!> |         | big endian
    I!> i!>       |         |
    Q> q> Q!> q!> |         | "S>" is the same as "n"
    J> j> J!> j!> |         | "L>" is the same as "N"
                  |         |
    S< s< S!< s!< | Integer | same as the directives without "<" except
    L< l< L!< l!< |         | little endian
    I!< i!<       |         |
    Q< q< Q!< q!< |         | "S<" is the same as "v"
    J< j< J!< j!< |         | "L<" is the same as "V"
                  |         |
    n             | Integer | 16-bit unsigned, network (big-endian) byte order
    N             | Integer | 32-bit unsigned, network (big-endian) byte order
    v             | Integer | 16-bit unsigned, VAX (little-endian) byte order
    V             | Integer | 32-bit unsigned, VAX (little-endian) byte order
                  |         |
    U             | Integer | UTF-8 character
    w             | Integer | BER-compressed integer (see Array#pack)

    Float        |         |
    Directive    | Returns | Meaning
    -----------------------------------------------------------------
    D d          | Float   | double-precision, native format
    F f          | Float   | single-precision, native format
    E            | Float   | double-precision, little-endian byte order
    e            | Float   | single-precision, little-endian byte order
    G            | Float   | double-precision, network (big-endian) byte order
    g            | Float   | single-precision, network (big-endian) byte order

    String       |         |
    Directive    | Returns | Meaning
    -----------------------------------------------------------------
    A            | String  | arbitrary binary string (remove trailing nulls and ASCII spaces)
    a            | String  | arbitrary binary string
    Z            | String  | null-terminated string
    B            | String  | bit string (MSB first)
    b            | String  | bit string (LSB first)
    H            | String  | hex string (high nibble first)
    h            | String  | hex string (low nibble first)
    u            | String  | UU-encoded string
    M            | String  | quoted-printable, MIME encoding (see RFC2045)
    m            | String  | base64 encoded string (RFC 2045) (default)
                 |         | base64 encoded string (RFC 4648) if followed by 0
    P            | String  | pointer to a structure (fixed-length string)
    p            | String  | pointer to a null-terminated string

    Misc.        |         |
    Directive    | Returns | Meaning
    -----------------------------------------------------------------
    @            | ---     | skip to the offset given by the length argument
    X            | ---     | skip backward one byte
    x            | ---     | skip forward one byte

The keyword *offset* can be given to start the decoding after skipping
the specified amount of bytes:
    "abc".unpack("C*") # => [97, 98, 99]
    "abc".unpack("C*", offset: 2) # => [99]
    "abc".unpack("C*", offset: 4) # => offset outside of string (ArgumentError)

HISTORY

*   J, J! j, and j! are available since Ruby 2.3.
*   Q_, Q!, q_, and q! are available since Ruby 2.1.
*   I!<, i!<, I!>, and i!> are available since Ruby 1.9.3.