Method: String#unpack

Defined in:

pack.c

#unpack(format) ⇒ Array

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 (<code>*</code>'') will use up all remaining elements. The directives <code>sSiIlL</code> may each be followed by an underscore (<code>_'') 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 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.

Format | Returns | Function
-------+---------+-----------------------------------------
 A    | String  | with trailing nulls and spaces removed
-------+---------+-----------------------------------------
 a    | String  | string
-------+---------+-----------------------------------------
 B    | String  | extract bits from each character (msb first)
-------+---------+-----------------------------------------
 b    | String  | extract bits from each character (lsb first)
-------+---------+-----------------------------------------
 C    | Fixnum  | extract a character as an unsigned integer
-------+---------+-----------------------------------------
 c    | Fixnum  | extract a character as an integer
-------+---------+-----------------------------------------
 d,D  | Float   | treat sizeof(double) characters as
      |         | a native double
-------+---------+-----------------------------------------
 E    | Float   | treat sizeof(double) characters as
      |         | a double in little-endian byte order
-------+---------+-----------------------------------------
 e    | Float   | treat sizeof(float) characters as
      |         | a float in little-endian byte order
-------+---------+-----------------------------------------
 f,F  | Float   | treat sizeof(float) characters as
      |         | a native float
-------+---------+-----------------------------------------
 G    | Float   | treat sizeof(double) characters as
      |         | a double in network byte order
-------+---------+-----------------------------------------
 g    | Float   | treat sizeof(float) characters as a
      |         | float in network byte order
-------+---------+-----------------------------------------
 H    | String  | extract hex nibbles from each character
      |         | (most significant first)
-------+---------+-----------------------------------------
 h    | String  | extract hex nibbles from each character
      |         | (least significant first)
-------+---------+-----------------------------------------
 I    | Integer | treat sizeof(int) (modified by _)
      |         | successive characters as an unsigned
      |         | native integer
-------+---------+-----------------------------------------
 i    | Integer | treat sizeof(int) (modified by _)
      |         | successive characters as a signed
      |         | native integer
-------+---------+-----------------------------------------
 L    | Integer | treat four (modified by _) successive
      |         | characters as an unsigned native
      |         | long integer
-------+---------+-----------------------------------------
 l    | Integer | treat four (modified by _) successive
      |         | characters as a signed native
      |         | long integer
-------+---------+-----------------------------------------
 M    | String  | quoted-printable
-------+---------+-----------------------------------------
 m    | String  | base64-encoded
-------+---------+-----------------------------------------
 N    | Integer | treat four characters as an unsigned
      |         | long in network byte order
-------+---------+-----------------------------------------
 n    | Fixnum  | treat two characters as an unsigned
      |         | short in network byte order
-------+---------+-----------------------------------------
 P    | String  | treat sizeof(char *) characters as a
      |         | pointer, and  return \emph{len} characters
      |         | from the referenced location
-------+---------+-----------------------------------------
 p    | String  | treat sizeof(char *) characters as a
      |         | pointer to a  null-terminated string
-------+---------+-----------------------------------------
 Q    | Integer | treat 8 characters as an unsigned
      |         | quad word (64 bits)
-------+---------+-----------------------------------------
 q    | Integer | treat 8 characters as a signed
      |         | quad word (64 bits)
-------+---------+-----------------------------------------
 S    | Fixnum  | treat two (different if _ used)
      |         | successive characters as an unsigned
      |         | short in native byte order
-------+---------+-----------------------------------------
 s    | Fixnum  | Treat two (different if _ used)
      |         | successive characters as a signed short
      |         | in native byte order
-------+---------+-----------------------------------------
 U    | Integer | UTF-8 characters as unsigned integers
-------+---------+-----------------------------------------
 u    | String  | UU-encoded
-------+---------+-----------------------------------------
 V    | Fixnum  | treat four characters as an unsigned
      |         | long in little-endian byte order
-------+---------+-----------------------------------------
 v    | Fixnum  | treat two characters as an unsigned
      |         | short in little-endian byte order
-------+---------+-----------------------------------------
 w    | Integer | BER-compressed integer (see Array.pack)
-------+---------+-----------------------------------------
 X    | ---     | skip backward one character
-------+---------+-----------------------------------------
 x    | ---     | skip forward one character
-------+---------+-----------------------------------------
 Z    | String  | with trailing nulls removed
      |         | upto first null with *
-------+---------+-----------------------------------------
 @    | ---     | skip to the offset given by the
      |         | length argument
-------+---------+-----------------------------------------

Returns:

• (Array)

# File 'pack.c', line 1303

static VALUE
pack_unpack(str, fmt)
VALUE str, fmt;