|author||iain barnett <email@example.com>||2019-08-04 13:37:54 +0900|
|committer||Aaron Patterson <firstname.lastname@example.org>||2019-08-09 17:06:07 -0700|
Added some examples to the documentation for String#unpack1 because
there are currently no examples and to contrast with String#unpack.
1 files changed, 14 insertions, 0 deletions
@@ -1925,6 +1925,20 @@ pack_unpack(VALUE str, VALUE fmt)
* Decodes <i>str</i> (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") #=> 
+ * "\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.