Ruby Newbie homepage Ruby Newbie homepage

How to use

Quick guide

Official content
Decodes str (which may contain binary data) according to the format string, returning the first value extracted.
Contrast with String#unpack:
"abc \0\0abc \0\0".unpack('A6Z6')   #=> ["abc", "abc "]
"abc \0\0abc \0\0".unpack1('A6Z6')  #=> "abc"
In that case data would be lost but often it's the case that the array only holds one value, especially when unpacking binary data. For instance:
"\xff\x00\x00\x00".unpack("l")         #=>  [255]
"\xff\x00\x00\x00".unpack1("l")        #=>  255
Thus unpack1 is convenient, makes clear the intention and signals the expected return value to those reading the code.
The keyword offset can be given to start the decoding after skipping the specified amount of bytes:
"abc".unpack1("C*") # => 97
"abc".unpack1("C*", offset: 2) # => 99
"abc".unpack1("C*", offset: 4) # => offset outside of string (ArgumentError)
 
               # File pack.rb, line 308
def unpack1(fmt, offset: 0)
  Primitive.pack_unpack1(fmt, offset)
end
            

Was this page useful?