Revision 27365

Date:
2009/07/02 17:42:33
Author:
moritz
Revision Log:
[S32/Containers] flesh out Buf semantics
Files:

Legend:

 
Added
 
Removed
 
Modified

  • docs/Perl6/Spec/S32-setting-library/Containers.pod

     
    757 757 Buf.new(127, :size(16)) # returns a buf16
    758 758 Buf.new(1024, :size(8)) # dies, because 1024 >= 2**8
    759 759
    760 Subtypes with additional constraints like C<utf8> (which only allows valid
    761 UTF-8 byte sequences) exist and provide similar constructors. See
    762 L<S02/Built-In Data Types>.
    763
    760 764 =head3 Methods
    761 765
    762 766 =item decode
    763 767
    764 768 our Str method decode($encoding = $?ENC, $nf = $?NF)
    765 769
    766 Decode the C<Buf> into a C<Str>
    770 Decode the C<Buf> into a C<Str>. For subtypes that know their encoding (like
    771 C<utf8>, C<utf16>) the C<$encoding> parameter defaults to their intrisic
    772 encoding instead.
    767 773
    774 =head3 C<Buf> Operators
    775
    776 Two C<Buf> objects of the same bit size can be compared with the same
    777 operators as strings (in particular C<eq>, C<lt>, C<le>, C<gt>, C<ge>,
    778 C<ne> and C<leg>), but actually compares the stored integers, not
    779 characters. Concatenating two compatible C<Buf>s produces an object of the
    780 most specific type possible, for example C<buf8.new() ~ utf8.new()> results in
    781 a C<buf8> object.
    782
    783 Comparing or concatenating two C<Buf> objects of different bit sizes,
    784 or a C<Buf> that doesn't know its encoding with a C<Str> throws an exception.
    785
    786 Likewising coercing an encoding-unaware C<Buf> to C<Str> dies.
    787
    788 [Conjecture: The behaviour of encoding-aware C<Buf> objects on string
    789 operators is intentially not defined yet, because I have no idea what
    790 implications on speed and usage they might have --moritz].
    791
    768 792 =head2 Pair
    769 793
    770 794 class Pair does Associative {...}