# New Ticket Created by Scott Walters
# Please include the string: [perl #15308]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt2/Ticket/Display.html?id=15308 >
There are some questions burried in there, marked with XXX. I'm sorry I was
unable to resolve those questions completely.
There has been confusion on how keys are supposed to function, and Dan
was kind enough to post the details to this list. This should provide a
starting point to developers writing PMCs to define methods that take
KEY * structures as multdimentional indices.
Thanks,
-scott
-- attachment 1 ------------------------------------------------------
url: http://rt.perl.org/rt2/attach/30930/25913/beb502/vtables.diff
Index: parrot/docs/vtables.pod
===================================================================
RCS file: /cvs/public/parrot/docs/vtables.pod,v
retrieving revision 1.10
diff -u -r1.10 vtables.pod
--- parrot/docs/vtables.pod 21 Jun 2002 17:23:06 -0000 1.10
+++ parrot/docs/vtables.pod 22 Jul 2002 04:46:11 -0000
@@ -317,6 +317,59 @@
=back
+=head2 Keyed Methods
+
+ for my $i (1..1000) {
+ for my $j (1..1000) {
+ for my $k (1..1000) {
+ @foo[$i;$j$k]++;
+ }
+ }
+ }
+
+Given this Perl 6 example, the Parrot Virtual Machine would be instructed to
+create a key:
+
+ new_key S0
+ size_key S0, 3
+ set_key S0, P1, 0, 0 # P1 into slot 0 of key in S0, see note below
+ set_key S0, P2, 1, 0 # P2 into slot 1 of key in S0
+ set_key S0, P3, 2, 0 # P3 into slot 1 of key in S0
+ # set_key S0, I1, 1 # I1 into slot 1 of key in S0 -- using an integer
+ # set_key S0, S1, 2 # S1 into slot 2 of key in S0 -- using a string
+
+When a PMC is stored in a position in a key, we need to tell Parrot what
+to ask of the PMC to use for the value. This is where the fourth field
+comes in. This corresponds to the C<KEY_TYPE> enum in C<include/parrot/key.h>.
+0 means to use the PMC as an integer, 1 means to use it as a string, and 2 means
+to use it as an object.
+(XXX I don't think I have this correct, as the enum options are undef, int, num,
+string and pmc -
+if I did have it correct, 0 would correspond to undef, so these numbers would be
+wrong).
+The C<KEY_ATOM> structure holds the C<KEY_TYPE> and C<UnionVal>, containing the int,
+number,
+string or PMC to provide the value for that position.
+The C<KEY> datastructure is a linked list, with each element holding a C<KEY_ATOM>.
+The third argument of C<set_key> corresponds directly to a C<KEY_ATOM> in this list.
+
+This key structure in this example will persist for the life of the enclosing
+for-loop.
+Since each C<KEY_ATOM> member references a PMC, no additional work is required for
+the key
+to reflect the current values of the index variables.
+
+Ideally, your PMC should process as much of the C<KEY> as possible. If it does
+not directly contain the item be references, the unused remainder of the key
+may be passed off to the keyed method of the indexed object:
+
+ if(key->next != NULL) {
+ mypmc->vtable->set_string_keyed(INTERP, mypmc, key->next, value);
+ }
+ else {
+ mypmc->vtable->set_string_native(INTERP, mypmc, value);
+ }
+
+keyed_int() methods are another special case, but a much easier one: an
+integer value is supplied as a single dimentional subscript into your PMC.
+
+=head2 Default Methods
+
Parrot will provide a set of default methods you can inherit from if
you don't need to do anything special for a given method. These will
be named C<Parrot_default_...>. If you don't want to implement a
@@ -325,3 +378,8 @@
void logical_not (PMC* value) = default;
and a sensible default will be provided for you.
+
+XXX Do the default methods recurse on the KEY structure? Looking at vtable.tbl,
+I don't see anything to that effect. It is logically for containers to be "special".
+
+
