/
Blob.pod6
369 lines (229 loc) · 10.2 KB
/
Blob.pod6
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
=begin pod
=TITLE role Blob
=SUBTITLE Immutable buffer for binary data ('Binary Large OBject')
role Blob[::T = uint8] does Positional[T] does Stringy { }
The C<Blob> role is an immutable interface to binary types, and offers a
list-like interface to lists of integers, typically unsigned integers.
=head1 Methods
=head2 method new
Defined as:
method new(*@codes)
Creates a C<Blob> from a list of integers.
my $blob = Blob.new([1, 2, 3]);
=head2 method Bool
Defined as:
multi method Bool(Blob:D:)
Returns C<False> if and only if the buffer is empty.
my $blob = Blob.new();
say $blob.Bool; # OUTPUT: «False»
$blob = Blob.new([1, 2, 3]);
say $blob.Bool; # OUTPUT: «True»
=head2 method Capture
Defined as:
method Capture(Blob:D --> Capture:D)
Equivalent to calling L«C<.List.Capture>|/type/List#method_Capture»
on the invocant.
=head2 method elems
Defined as:
multi method elems(Blob:D: --> Int:D)
Returns the number of elements of the buffer.
my $blob = Blob.new([1, 2, 3]);
say $blob.elems; # OUTPUT: «3»
=head2 method bytes
Defined as:
method bytes(Blob:D: --> Int:D)
Returns the number of bytes used by the elements in the buffer.
say Blob.new([1, 2, 3]).bytes; # OUTPUT: «3»
say blob16.new([1, 2, 3]).bytes; # OUTPUT: «6»
say blob64.new([1, 2, 3]).bytes; # OUTPUT: «24»
=head2 method decode
Defined as:
multi method decode(Blob:D: Str:D $encoding = 'UTF-8' --> Str:D)
Applies an encoding to turn the blob into a L<Str|/type/Str>.
my Blob $blob = "string".encode('utf-8');
say $blob.decode('utf-8'); # OUTPUT: «string»
On malformed utf-8 C<.decode> will throw X::AdHoc. To handle sloppy utf-8 use
L«C<utf8-c8>|/language/unicode#UTF8-C8».
=head2 method gist
Defined as:
method gist(Blob:D: --> Str:D)
Returns the string containing the "gist" of the L<Blob|/type/Blob>,
B<listing up to the first 100> elements, separated by space, appending an
ellipsis if the L<Blob|/type/Blob> has more than 100 elements.
put Blob.new(1, 2, 3).gist; # OUTPUT: «Blob:0x<01 02 03>»
put Blob.new(1..2000).gist;
# OUTPUT:
# Blob:0x<01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15
# 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27 28 29 2A 2B 2C
# 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40 41 42 43
# 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A
# 5B 5C 5D 5E 5F 60 61 62 63 64 ...>
=head2 method subbuf
Defined as:
multi method subbuf(Int $from, Int $len = self.elems --> Blob:D)
multi method subbuf(Range $range --> Blob:D)
Extracts a part of the invocant buffer, starting from the index with
elements C<$from>, and taking C<$len> elements (or less if the buffer is
shorter), and creates a new buffer as the result.
say Blob.new(1..10).subbuf(2, 4); # OUTPUT: «Blob:0x<03 04 05 06>»
say Blob.new(1..10).subbuf(*-2); # OUTPUT: «Blob:0x<09 0a>»
say Blob.new(1..10).subbuf(*-5,2); # OUTPUT: «Blob:0x<06 07>»
For convenience, also allows a C<Range> to be specified to indicate which
part of the invocant buffer you would like:
say Blob.new(1..10).subbuf(2..5); # OUTPUT: «Blob:0x<03 04 05 06>»
=head2 method allocate
Defined as:
multi method allocate($elems --> Blob:D)
multi method allocate($elems, $pattern --> Blob:D)
Returns a newly created C<Blob> object with the given number of elements.
Optionally takes a second argument that indicates the pattern with which to
fill the C<Blob>: this can be a single integer value, or any C<Iterable>
that generates integer values, including another C<Blob>. The pattern will be repeated if not enough
values are given to fill the entire C<Blob>.
my Blob $b0 = Blob.allocate(10,0);
$b0.say; # OUTPUT: «Blob:0x<00 00 00 00 00 00 00 00 00 00>»
=head2 method unpack
This method is considered B<experimental>, in order to use it you will need to
do:
use experimental :pack;
Defined as:
method unpack(Blob:D: Str:D $template)
method unpack(Blob:D: @template)
multi sub unpack(Blob:D \blob, Str:D $template)
multi sub unpack(Blob:D \blob, @template)
Extracts features from the blob according to the template string, and
returns them as a list.
The template string consists of zero or more units that begin with an ASCII
letter, and are optionally followed by a quantifier. The quantifier can be
C<*> (which typically stands for "use up the rest of the Blob here"), or a
positive integer (without a C<+>).
Whitespace between template units is ignored.
Examples of valid templates include C<"A4 C n*"> and C<"A*">.
The following letters are recognized:
=begin table
Letter Meaning
====== =======
A Extract a string, where each element of the Blob maps to a codepoint
a Same as A
C Extract an element from the blob as an integer
H Extracts a hex string
L Extracts four elements and returns them as a single unsigned integer
n Extracts two elements and combines them in "network" (BigEndian) byte order into a single integer
N Extracts four elements and combines them in "network" (BigEndian) byte order into a single integer
S Extracts two elements and returns them as a single unsigned integer
v Same as S
V Same as L
x Drop an element from the blob (that is, ignore it)
Z Same as A
=end table
Example:
use experimental :pack;
say Blob.new(1..10).unpack("C*");
# OUTPUT: «(1 2 3 4 5 6 7 8 9 10)»
=head2 sub pack
This subroutine is considered B<experimental>, in order to use it you will need
to do:
=for code
use experimental :pack;
=for code
sub pack(Str $template, *@items)
sub pack(@template, *@items)
Packs the given items according to the template and returns a buffer
containing the packed bytes.
The template string consists of zero or more units that begin with an ASCII
letter, and are optionally followed by a quantifier. For details, see
L<unpack|/routine/unpack>.
=head2 method reverse
Defined as:
method reverse(Blob:D: --> Blob:D)
Returns a Blob with all elements in reversed order.
say Blob.new([1, 2, 3]).reverse; # OUTPUT: «Blob:0x<03 02 01>»
say blob16.new([2]).reverse; # OUTPUT: «Blob[uint16]:0x<02>»
say buf32.new([16, 32]).reverse; # OUTPUT: «Buf[uint32]:0x<20 10>»
=head1 Methods on blob8 only (6.d, 2018.12 and later)
These methods are available on the blob8 (and C<buf8>) types only. They allow
low level access to reading bytes from the underlying data and interpreting
them in different ways with regards to type (integer or floating point (num)),
size (8, 16, 32, 64 or 128 bits), signed or unsigned (for integer values) and
endianness (native, little and big endianness). The returned values are
always expanded to a 64 bit native value where possible, and to a (big)
integer value if that is not possible.
Endianness must be indicated by using values of the L<Endian|/type/Endian>
enum as the B<second> parameter to these methods. If no endianness is
specified, C<NativeEndian> will be assumed. Other values are
C<LittleEndian> and C<BigEndian>.
=head2 method read-uint8
Defined as:
method read-uint8(blob8:D: uint $pos, $endian = NativeEndian --> uint)
Returns an unsigned native integer value for the byte at the given position.
The C<$endian> parameter has no meaning, but is available for consistency.
=head2 method read-int8
Defined as:
method read-int8(blob8:D: uint $pos, $endian = NativeEndian --> int)
Returns a native C<int> value for the byte at the given position.
The C<$endian> parameter has no meaning, but is available for consistency.
=head2 method read-uint16
Defined as:
method read-uint16(blob8:D: uint $pos, $endian = NativeEndian --> uint)
Returns a native C<uint> value for the B<two> bytes starting at the
given position.
=head2 method read-int16
Defined as:
method read-int16(blob8:D: uint $pos, $endian = NativeEndian --> int)
Returns a native C<int> value for the B<two> bytes starting at the given
position.
=head2 method read-uint32
Defined as:
method read-uint32(blob8:D: uint $pos, $endian = NativeEndian --> uint)
Returns a native C<uint> value for the B<four> bytes starting at the
given position.
=head2 method read-int32
Defined as:
method read-int32(blob8:D: uint $pos, $endian = NativeEndian --> int)
Returns a native C<int> value for the B<four> bytes starting at the given
position.
=head2 method read-uint64
Defined as:
method read-uint64(blob8:D: uint $pos, $endian = NativeEndian --> UInt:D)
Returns an unsigned integer value for the B<eight> bytes starting at the
given position.
=head2 method read-int64
Defined as:
method read-int64(blob8:D: uint $pos, $endian = NativeEndian --> int)
Returns a native C<int> value for the B<eight> bytes starting at the given
position.
=head2 method read-uint128
Defined as:
method read-uint128(blob8:D: uint $pos, $endian = NativeEndian --> UInt:D)
Returns an unsigned integer value for the B<sixteen> bytes starting at the
given position.
=head2 method read-int128
Defined as:
method read-int128(blob8:D: uint $pos, $endian = NativeEndian --> Int:D)
Returns an integer value for the B<sixteen> bytes starting at the given
position.
=head2 method read-num32
Defined as:
method read-num32(blob8:D: uint $pos, $endian = NativeEndian --> int)
Returns a native C<num> value for the B<four> bytes starting at the given
position.
=head2 method read-num64
Defined as:
method read-num64(blob8:D: uint $pos, $endian = NativeEndian --> int)
Returns a native C<num> value for the B<eight> bytes starting at the given
position.
=head1 Methods on blob8 only (6.d, 2019.01 and later)
=head2 method read-ubits
Defined as:
method read-ubits(blob8:D: uint $pos, uint $bits --> UInt:D)
Returns an unsigned integer value for the B<bits> from the given B<bit> offset
and given number of bits. The endianness of the bits is assumed to be
C<BigEndian>.
=head2 method read-bits
Defined as:
method read-bits(blob8:D: uint $pos, uint $bits --> Int:D)
Returns a signed integer value for the B<bits> from the given B<bit> offset
and given number of bits. The endianness of the bits is assumed to be
C<BigEndian>.
=end pod
# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6