Author: lwall
Date: 2010-04-07 20:07:45 +0200 (Wed, 07 Apr 2010)
New Revision: 30332
Modified:
docs/Perl6/Spec/S02-bits.pod
Log:
[S02] some clarifications of the desired semantics of buffers
Modified: docs/Perl6/Spec/S02-bits.pod
===================================================================
--- docs/Perl6/Spec/S02-bits.pod 2010-04-06 23:07:58 UTC (rev 30331)
+++ docs/Perl6/Spec/S02-bits.pod 2010-04-07 18:07:45 UTC (rev 30332)
@@ -13,8 +13,8 @@
Created: 10 Aug 2004
- Last Modified: 5 Apr 2010
- Version: 211
+ Last Modified: 7 Apr 2010
+ Version: 212
This document summarizes Apocalypse 2, which covers small-scale
lexical items and typological issues. (These Synopses also contain
@@ -886,16 +886,18 @@
A C<Buf> is a stringish view of an array of
integers, and has no Unicode or character properties without explicit
-conversion to some kind of C<Str>. (A C<buf> is the native counterpart.)
-Typically it's an array of bytes serving as a buffer. Bitwise
+conversion to some kind of C<Str>. (The C<buf8>, C<buf16>, C<buf32>,
+and C<buf64> types are the native counterparts; native buf types are
+required to occupy contiguous memory for the entire buffer.)
+Typically a C<Buf> is an array of bytes serving as a buffer. Bitwise
operations on a C<Buf> treat the entire buffer as a single large
integer. Bitwise operations on a C<Str> generally fail unless the
C<Str> in question can provide an abstract C<Buf> interface somehow.
Coercion to C<Buf> should generally invalidate the C<Str> interface.
-As a generic type C<Buf> may be instantiated as (or bound to) any
-of C<buf8>, C<buf16>, or C<buf32> (or to any type that provides the
+As a generic role C<Buf> may be instantiated as any
+of C<buf8>, C<buf16>, or C<buf32> (or as any type that provides the
appropriate C<Buf> interface), but when used to create a buffer C<Buf>
-defaults to C<buf8>.
+is punned to a class implementing C<buf8> (actually C<Buf[uint8]>).
Unlike C<Str> types, C<Buf> types prefer to deal with integer string
positions, and map these directly to the underlying compact array
@@ -908,6 +910,32 @@
Note, though, that if you remap a section of C<buf32> memory to be
C<buf8>, you'll have to multiply all your positions by 4.
+These native types are defined based on the C<Buf> role, parameterized
+by the native integer type it is composed of:
+
+ Name Is really
+ ==== =========
+ buf8 Buf[uint8]
+ buf16 Buf[uint16]
+ buf32 Buf[uint32]
+ buf64 Buf[uint64]
+
+There are no signed buf types provided as built-ins, but you may say
+
+ Buf[int8]
+ Buf[int16]
+ Buf[int32]
+ Buf[int64]
+
+to get buffers of signed integers. It is also possible to defined
+a C<Buf> based on non-integers or on non-native types:
+
+ Buf[complex64]
+ Buf[FatRat]
+ Buf[Int]
+
+However, no guarantee of memory contiguity can be made for non-native types.
+
=item *
The C<utf8> type is derived from C<buf8>, with the additional constraint
@@ -1349,7 +1377,7 @@
KeyBag KeyHash of UInt (does Bag in list/array context)
Pair A single key-to-value association
PairSeq A Seq of Pairs
- Buf Perl buffer (a stringish array of memory locations)
+ Buf Perl buffer (array of integers with some stringy features)
IO Perl filehandle
Routine Base class for all wrappable executable objects
Sub Perl subroutine
