End of Life Ruby 3.1 has reached end of life and gets no more fixes. Switch to Ruby 4.0 →
String#unpack1
# File tmp/rubies/ruby-3.1.3/pack.rb, line 308
def unpack1(fmt, offset: 0)
Primitive.pack_unpack1(fmt, offset)
end
Decodes str (which may contain binary data) according to the format string, returning the first value extracted.
See also String#unpack, Array#pack.
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)
Ruby version changes
-
3.1
-
String#unpackandString#unpack1now accept anoffset:keyword argument to start the unpacking after an arbitrary number of bytes have been skipped. Ifoffsetis outside of the string boundsArgumentErroris raised. [Feature #18254]
-