Skip to content

Commit 47eeea2

Browse files
committed
Adds a section on :pack
Although it was rather well covered in the Blob page. Added some references, and changed definitions on that page.
1 parent ceedca6 commit 47eeea2

File tree

2 files changed

+40
-6
lines changed

2 files changed

+40
-6
lines changed

doc/Language/experimental.pod6

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,36 @@ later.)
2020
=comment The following should be a table but formatting in tables is
2121
not yet rendered properly.
2222
23-
=item X<B<pack>|pack> [TBD]
23+
=head2 X<B<pack>|pack>
24+
25+
Pack is a feature that allows binary serialization of general data structures,
26+
and is inherited from
27+
L<Perl's pack|http://perldoc.perl.org/functions/pack.html>.
28+
The C<pack> order creates a
29+
C<Buf> by packing data structures in a certain way given by a I<packing string>
30+
with the options shown
31+
L<in the description of C<unpack>\/type/Blob#method_unpack>.
32+
33+
For instance, we can pack numbers interpreting them as hexadecimal (C<H>) with
34+
the pattern repeating until there are no more elements (C<*>):
35+
36+
=for code
37+
use experimental :pack;
38+
say pack("H*", "414243").contents;# OUTPUT: «(65 66 67)␤»
39+
40+
There is a corresponding C<unpack> routine that does exactly the opposite.
41+
42+
=for code
43+
use experimental :pack;
44+
my $buf=Buf.new(65,66,67);
45+
say $buf.unpack("H*"); # OUTPUT: «414243␤»
46+
47+
48+
Not all of the symbols above are guaranteed to be implemented, and the roadmap
49+
does not include a fixed date for getting out of that stage.
50+
51+
Please see also documentation for L<C<pack>\/type/Blob#sub_pack> and
52+
L<C<unpack>\/type/Blob#method_unpack> in the C<Blob> page.
2453
2554
=head2 X<B<macros>|macros>
2655

doc/Type/Blob.pod6

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -137,14 +137,17 @@ values are given to fill the entire C<Blob>.
137137
138138
=head2 method unpack
139139
140-
This method is considered B<experimental>, in order to use it you will need to do:
140+
This method is considered B<experimental>, in order to use it you will need to
141+
do:
141142
142143
use experimental :pack;
143144
144-
145145
Defined as:
146146
147-
method unpack(Blob:D: $template --> List:D)
147+
method unpack(Blob:D: Str:D $template)
148+
method unpack(Blob:D: @template)
149+
multi sub unpack(Blob:D \blob, Str:D $template)
150+
multi sub unpack(Blob:D \blob, @template)
148151
149152
Extracts features from the blob according to the template string, and
150153
returns them as a list.
@@ -187,13 +190,15 @@ Example:
187190
188191
=head2 sub pack
189192
190-
This subroutine is considered B<experimental>, in order to use it you will need to do:
193+
This subroutine is considered B<experimental>, in order to use it you will need
194+
to do:
191195
192196
=for code
193197
use experimental :pack;
194198
195199
=for code
196-
sub pack(Str $template, *@items --> Buf)
200+
sub pack(Str $template, *@items)
201+
sub pack(@template, *@items)
197202
198203
Packs the given items according to the template and returns a buffer
199204
containing the packed bytes.

0 commit comments

Comments
 (0)