Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Adds a section on :pack
Although it was rather well covered in the Blob page. Added some
references, and changed definitions on that page.
  • Loading branch information
JJ committed Jan 1, 2019
1 parent ceedca6 commit 47eeea2
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 6 deletions.
31 changes: 30 additions & 1 deletion doc/Language/experimental.pod6
Expand Up @@ -20,7 +20,36 @@ later.)
=comment The following should be a table but formatting in tables is
not yet rendered properly.
=item X<B<pack>|pack> [TBD]
=head2 X<B<pack>|pack>
Pack is a feature that allows binary serialization of general data structures,
and is inherited from
L<Perl's pack|http://perldoc.perl.org/functions/pack.html>.
The C<pack> order creates a
C<Buf> by packing data structures in a certain way given by a I<packing string>
with the options shown
L<in the description of C<unpack>\/type/Blob#method_unpack>.
For instance, we can pack numbers interpreting them as hexadecimal (C<H>) with
the pattern repeating until there are no more elements (C<*>):
=for code
use experimental :pack;
say pack("H*", "414243").contents;# OUTPUT: «(65 66 67)␤»
There is a corresponding C<unpack> routine that does exactly the opposite.
=for code
use experimental :pack;
my $buf=Buf.new(65,66,67);
say $buf.unpack("H*"); # OUTPUT: «414243␤»
Not all of the symbols above are guaranteed to be implemented, and the roadmap
does not include a fixed date for getting out of that stage.
Please see also documentation for L<C<pack>\/type/Blob#sub_pack> and
L<C<unpack>\/type/Blob#method_unpack> in the C<Blob> page.
=head2 X<B<macros>|macros>
Expand Down
15 changes: 10 additions & 5 deletions doc/Type/Blob.pod6
Expand Up @@ -137,14 +137,17 @@ values are given to fill the entire C<Blob>.
=head2 method unpack
This method is considered B<experimental>, in order to use it you will need to do:
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: $template --> List:D)
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.
Expand Down Expand Up @@ -187,13 +190,15 @@ Example:
=head2 sub pack
This subroutine is considered B<experimental>, in order to use it you will need to do:
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 --> Buf)
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.
Expand Down

0 comments on commit 47eeea2

Please sign in to comment.