diff options
Diffstat (limited to 'doc/packed_data.rdoc')
| -rw-r--r-- | doc/packed_data.rdoc | 99 |
1 files changed, 49 insertions, 50 deletions
diff --git a/doc/packed_data.rdoc b/doc/packed_data.rdoc index ec13b24c69..17bbf92023 100644 --- a/doc/packed_data.rdoc +++ b/doc/packed_data.rdoc @@ -1,4 +1,4 @@ -== Packed \Data += Packed \Data Certain Ruby core methods deal with packing and unpacking data: @@ -64,7 +64,7 @@ If elements don't fit the provided directive, only least significant bits are en [257].pack("C").unpack("C") # => [1] -=== Packing \Method +== Packing \Method \Method Array#pack accepts optional keyword argument +buffer+ that specifies the target string (instead of a new string): @@ -76,7 +76,7 @@ The method can accept a block: # Packed string is passed to the block. [65, 66].pack('C*') {|s| p s } # => "AB" -=== Unpacking Methods +== Unpacking Methods Methods String#unpack and String#unpack1 each accept an optional keyword argument +offset+ that specifies an offset @@ -95,12 +95,12 @@ Both methods can accept a block: # The single unpacked object is passed to the block. 'AB'.unpack1('C*') {|ele| p ele } # => 65 -=== \Integer Directives +== \Integer Directives Each integer directive specifies the packing or unpacking for one element in the input or output array. -==== 8-Bit \Integer Directives +=== 8-Bit \Integer Directives - <tt>'c'</tt> - 8-bit signed integer (like C <tt>signed char</tt>): @@ -109,14 +109,14 @@ for one element in the input or output array. s = [0, 1, -1].pack('c*') # => "\x00\x01\xFF" s.unpack('c*') # => [0, 1, -1] -- <tt>'C'</tt> - 8-bit signed integer +- <tt>'C'</tt> - 8-bit unsigned integer (like C <tt>unsigned char</tt>): [0, 1, 255].pack('C*') # => "\x00\x01\xFF" s = [0, 1, -1].pack('C*') # => "\x00\x01\xFF" s.unpack('C*') # => [0, 1, 255] -==== 16-Bit \Integer Directives +=== 16-Bit \Integer Directives - <tt>'s'</tt> - 16-bit signed integer, native-endian (like C <tt>int16_t</tt>): @@ -146,7 +146,7 @@ for one element in the input or output array. s.unpack('v*') # => [0, 1, 65535, 32767, 32768, 65535] -==== 32-Bit \Integer Directives +=== 32-Bit \Integer Directives - <tt>'l'</tt> - 32-bit signed integer, native-endian (like C <tt>int32_t</tt>): @@ -178,7 +178,7 @@ for one element in the input or output array. s.unpack('v*') # => [0, 0, 1, 0, 65535, 65535] -==== 64-Bit \Integer Directives +=== 64-Bit \Integer Directives - <tt>'q'</tt> - 64-bit signed integer, native-endian (like C <tt>int64_t</tt>): @@ -196,7 +196,7 @@ for one element in the input or output array. s.unpack('Q*') # => [578437695752307201, 17940646550795321087] -==== Platform-Dependent \Integer Directives +=== Platform-Dependent \Integer Directives - <tt>'i'</tt> - Platform-dependent width signed integer, native-endian (like C <tt>int</tt>): @@ -214,26 +214,24 @@ for one element in the input or output array. s.unpack('I*') # => [67305985, 4244504319] -==== Pointer Directives - -- <tt>'j'</tt> - 64-bit pointer-width signed integer, - native-endian (like C <tt>intptr_t</tt>): +- <tt>'j'</tt> - Pointer-width signed integer, native-endian + (like C <tt>intptr_t</tt>): s = [67305985, -50462977].pack('j*') # => "\x01\x02\x03\x04\x00\x00\x00\x00\xFF\xFE\xFD\xFC\xFF\xFF\xFF\xFF" s.unpack('j*') # => [67305985, -50462977] -- <tt>'j'</tt> - 64-bit pointer-width unsigned integer, - native-endian (like C <tt>uintptr_t</tt>): +- <tt>'J'</tt> - Pointer-width unsigned integer, native-endian + (like C <tt>uintptr_t</tt>): s = [67305985, 4244504319].pack('J*') # => "\x01\x02\x03\x04\x00\x00\x00\x00\xFF\xFE\xFD\xFC\x00\x00\x00\x00" s.unpack('J*') # => [67305985, 4244504319] -==== Other \Integer Directives -: +=== Other \Integer Directives + - <tt>'U'</tt> - UTF-8 character: s = [4194304].pack('U*') @@ -242,38 +240,37 @@ for one element in the input or output array. # => [4194304] - <tt>'w'</tt> - BER-encoded integer - (see {BER enocding}[https://en.wikipedia.org/wiki/X.690#BER_encoding]): + (see {BER encoding}[https://en.wikipedia.org/wiki/X.690#BER_encoding]): s = [1073741823].pack('w*') # => "\x83\xFF\xFF\xFF\x7F" s.unpack('w*') # => [1073741823] -==== Modifiers for \Integer Directives - -For directives in -<tt>'i'</tt>, -<tt>'I'</tt>, -<tt>'s'</tt>, -<tt>'S'</tt>, -<tt>'l'</tt>, -<tt>'L'</tt>, -<tt>'q'</tt>, -<tt>'Q'</tt>, -<tt>'j'</tt>, and -<tt>'J'</tt>, -these modifiers may be suffixed: - -- <tt>'!'</tt> or <tt>'_'</tt> - Underlying platform’s native size. +=== Modifiers for \Integer Directives + +For the following directives, <tt>'!'</tt> or <tt>'_'</tt> modifiers may be +suffixed as underlying platform’s native size. + +- <tt>'i'</tt>, <tt>'I'</tt> - C <tt>int</tt>, always native size. +- <tt>'s'</tt>, <tt>'S'</tt> - C <tt>short</tt>. +- <tt>'l'</tt>, <tt>'L'</tt> - C <tt>long</tt>. +- <tt>'q'</tt>, <tt>'Q'</tt> - C <tt>long long</tt>, if available. +- <tt>'j'</tt>, <tt>'J'</tt> - C <tt>intptr_t</tt>, always native size. + +Native size modifiers are silently ignored for always native size directives. + +The endian modifiers also may be suffixed in the directives above: + - <tt>'>'</tt> - Big-endian. - <tt>'<'</tt> - Little-endian. -=== \Float Directives +== \Float Directives Each float directive specifies the packing or unpacking for one element in the input or output array. -==== Single-Precision \Float Directives +=== Single-Precision \Float Directives - <tt>'F'</tt> or <tt>'f'</tt> - Native format: @@ -290,7 +287,7 @@ for one element in the input or output array. s = [3.0].pack('g') # => "@@\x00\x00" s.unpack('g') # => [3.0] -==== Double-Precision \Float Directives +=== Double-Precision \Float Directives - <tt>'D'</tt> or <tt>'d'</tt> - Native format: @@ -317,12 +314,12 @@ A float directive may be infinity or not-a-number: [nan].pack('f') # => "\x00\x00\xC0\x7F" "\x00\x00\xC0\x7F".unpack('f') # => [NaN] -=== \String Directives +== \String Directives Each string directive specifies the packing or unpacking for one byte in the input or output string. -==== Binary \String Directives +=== Binary \String Directives - <tt>'A'</tt> - Arbitrary binary string (space padded; count is width); +nil+ is treated as the empty string: @@ -380,7 +377,7 @@ for one byte in the input or output string. "foo".unpack('Z*') # => ["foo"] "foo\0bar".unpack('Z*') # => ["foo"] # Does not read past "\0". -==== Bit \String Directives +=== Bit \String Directives - <tt>'B'</tt> - Bit string (high byte first): @@ -424,7 +421,7 @@ for one byte in the input or output string. "\x01".unpack("b2") # => ["10"] "\x01".unpack("b3") # => ["100"] -==== Hex \String Directives +=== Hex \String Directives - <tt>'H'</tt> - Hex string (high nibble first): @@ -470,7 +467,7 @@ for one byte in the input or output string. "\x01\xfe".unpack('h4') # => ["10ef"] "\x01\xfe".unpack('h5') # => ["10ef"] -==== Pointer \String Directives +=== Pointer \String Directives - <tt>'P'</tt> - Pointer to a structure (fixed-length string): @@ -488,7 +485,7 @@ for one byte in the input or output string. ("\0" * 8).unpack("p") # => [nil] [nil].pack("p") # => "\x00\x00\x00\x00\x00\x00\x00\x00" -==== Other \String Directives +=== Other \String Directives - <tt>'M'</tt> - Quoted printable, MIME encoding; text mode, but input must use LF and output LF; @@ -557,12 +554,14 @@ for one byte in the input or output string. - <tt>'u'</tt> - UU-encoded string: - [0].pack("U") # => "\u0000" - [0x3fffffff].pack("U") # => "\xFC\xBF\xBF\xBF\xBF\xBF" - [0x40000000].pack("U") # => "\xFD\x80\x80\x80\x80\x80" - [0x7fffffff].pack("U") # => "\xFD\xBF\xBF\xBF\xBF\xBF" + [""].pack("u") # => "" + ["a"].pack("u") # => "!80``\n" + ["aaa"].pack("u") # => "#86%A\n" + + "".unpack("u") # => [""] + "#86)C\n".unpack("u") # => ["abc"] -=== Offset Directives +== Offset Directives - <tt>'@'</tt> - Begin packing at the given byte offset; for packing, null fill if necessary: @@ -580,7 +579,7 @@ for one byte in the input or output string. [0, 1, 2].pack("CCX2C") # => "\x02" "\x00\x02".unpack("CCXC") # => [0, 2, 2] -=== Null Byte Direcive +== Null Byte Directive - <tt>'x'</tt> - Null byte: |