From 789776be08830b53499db86ab33ade9db1111a79 Mon Sep 17 00:00:00 2001 From: iain barnett Date: Sun, 4 Aug 2019 13:37:54 +0900 Subject: [PATCH] Added some examples to the documentation for String#unpack1 because there are currently no examples and to contrast with String#unpack. --- pack.c | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/pack.c b/pack.c index e43e43777e..ba2348cb53 100644 --- a/pack.c +++ b/pack.c @@ -1925,6 +1925,20 @@ pack_unpack(VALUE str, VALUE fmt) * 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. */ static VALUE