summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoriain barnett <iainspeed@gmail.com>2019-08-04 13:37:54 +0900
committerAaron Patterson <tenderlove@ruby-lang.org>2019-08-09 17:06:07 -0700
commit789776be08830b53499db86ab33ade9db1111a79 (patch)
treeecaf6e64336616d53093e84cb9eb34702e6dac09
parent9d298b9dab831f966ea4bf365c712161118dd631 (diff)
Added some examples to the documentation for String#unpack1 because
there are currently no examples and to contrast with String#unpack.
-rw-r--r--pack.c14
1 files changed, 14 insertions, 0 deletions
diff --git a/pack.c b/pack.c
index e43e437..ba2348c 100644
--- a/pack.c
+++ b/pack.c
@@ -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") #=> [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