src/pmc/iterator.pmc

   1 /*
   2 Copyright (C) 2001-2008, The Perl Foundation.
   3 $Id$
   4
   5 =head1 NAME
   6
   7 src/pmc/iterator.pmc - Iterator PMC
   8
   9 =head1 DESCRIPTION
  10
  11 These are the vtable functions for the Iterator base class. Iterators are
  12 used in combination with other classes(mainly aggregates) to visit all entries
  13 in that aggregate.
  14
  15 =head1 SYNOPSIS
  16
  17 =head2 default usage
  18
  19     .local pmc iterator, array, entry
  20     iterator = new 'Iterator', array
  21   iter_loop:
  22     unless iterator, iter_end  # while (more values)
  23     entry = shift iterator     # get an entry
  24     ...
  25     goto iter_loop
  26   iter_end:
  27
  28 The C<new> can alteratively be written as:
  29
  30   iterator = iter array
  31
  32 =head2 iterate from the end, for arrays
  33
  34     .local pmc iterator, array, entry
  35     iterator = new 'Iterator', array
  36     iterator = .ITERATE_FROM_END
  37   iter_loop:
  38     unless iterator, iter_end  # while (more values)
  39     entry = pop iterator     # get an entry
  40     ...
  41     goto iter_loop
  42   iter_end:
  43
  44 =head2 iterate over a hash
  45
  46     .local pmc iterator, hash, key, entry
  47     iterator = new 'Iterator', hash
  48   iter_loop:
  49     unless iterator, iter_end  # while (more values)
  50     key   = shift iterator     # get the key..
  51     entry = hash[key]
  52     ...
  53     goto iter_loop
  54   iter_end:
  55
  56 =head1 Methods
  57
  58 =over 4
  59
  60 =cut
  61
  62 */
  63
  64 #include "parrot/parrot.h"
  65
  66 pmclass Iterator no_ro {
  67
  68     void class_init() {
  69         if (pass) {
  70             /* Make the shift_pmc vtable function available as
  71              * a method named "next" */
  72             register_nci_method(INTERP, enum_class_Iterator,
  73                     F2DPTR(Parrot_Iterator_shift_pmc), "next", "PJO");
  74         }
  75     }
  76
  77 /*
  78
  79 =item C<void init()>
  80
  81 Raises an exception. Use C<init_pmc()>.
  82
  83 =cut
  84
  85 */
  86
  87     VTABLE void init() {
  88         real_exception(INTERP, NULL, E_Exception,
  89                 "Iterator init without aggregate");
  90     }
  91
  92 /*
  93
  94 =item C<void init_pmc(PMC *initializer)>
  95
  96 Initializes the iterator with an aggregate PMC.
  97 Defaults iteration mode to iterate from start.
  98
  99 =cut
 100
 101 */
 102
 103     VTABLE void init_pmc(PMC *aggregate) {
 104         PMC_pmc_val(SELF)    = aggregate;
 105         PMC_struct_val(SELF) = NULL;
 106         PObj_custom_mark_SET(SELF);
 107
 108         /* by default, iterate from start */
 109         SELF.set_integer_native(ITERATE_FROM_START);
 110     }
 111
 112 /*
 113
 114 =item C<void mark()>
 115
 116 Marks the current idx/key and the aggregate as live.
 117
 118 =cut
 119
 120 */
 121
 122     VTABLE void mark() {
 123         /* the KEY */
 124         if (PMC_struct_val(SELF))
 125              pobject_lives(INTERP, (PObj *)PMC_struct_val(SELF));
 126
 127         /* the aggregate */
 128         if (PMC_pmc_val(SELF))
 129              pobject_lives(INTERP, (PObj *)PMC_pmc_val(SELF));
 130     }
 131
 132 /*
 133
 134 =item C<PMC *clone()>
 135
 136 Make a clone of the iterator.
 137
 138 =cut
 139
 140 */
 141
 142     VTABLE PMC *clone() {
 143         PMC * const key     = (PMC *)PMC_struct_val(SELF);
 144         PMC * const res     = pmc_new_init(INTERP, SELF->vtable->base_type,
 145                                            PMC_pmc_val(SELF));
 146         PMC_struct_val(res) = VTABLE_clone(interp, key);
 147         return res;
 148     }
 149
 150 /*
 151
 152 =item C<INTVAL get_integer()>
 153
 154 Get number of remaining elements. Does not work for hashes yet.
 155 TODO: keep track of current position and direction
 156
 157 =cut
 158
 159 */
 160
 161     VTABLE INTVAL get_integer() {
 162         return SELF.elements();
 163     }
 164
 165 /*
 166
 167 =item C<STRING *get_string()>
 168
 169 Returns a textual representation of the iterator.
 170
 171 =cut
 172
 173 */
 174
 175     VTABLE STRING *get_string() {
 176         PMC * const key = (PMC *)PMC_struct_val(SELF);
 177         return string_from_int(INTERP, key_integer(INTERP, key));
 178     }
 179
 180 /*
 181
 182 =item C<INTVAL get_integer_keyed(PMC *key)>
 183
 184 =cut
 185
 186 */
 187
 188     VTABLE INTVAL get_integer_keyed(PMC *key) {
 189         return VTABLE_get_integer_keyed(INTERP, PMC_pmc_val(SELF), key);
 190     }
 191
 192 /*
 193
 194 =item C<INTVAL get_integer_keyed_int(INTVAL idx)>
 195
 196 Get integer value of current position plus idx.
 197
 198 =cut
 199
 200 */
 201
 202     VTABLE INTVAL get_integer_keyed_int(INTVAL idx) {
 203         PMC * const key = (PMC *)PMC_struct_val(SELF);
 204         PMC * const agg = PMC_pmc_val(SELF);
 205         return VTABLE_get_integer_keyed_int(INTERP, agg, PMC_int_val(key) +idx);
 206     }
 207
 208 /*
 209
 210 =item C<FLOATVAL get_number_keyed(PMC *key)>
 211
 212 =cut
 213
 214 */
 215
 216     VTABLE FLOATVAL get_number_keyed(PMC *key) {
 217         return VTABLE_get_number_keyed(INTERP, PMC_pmc_val(SELF), key);
 218     }
 219
 220 /*
 221
 222 =item C<FLOATVAL get_number_keyed_int(INTVAL idx)>
 223
 224 Get number value of current position plus idx.
 225
 226 =cut
 227
 228 */
 229
 230     VTABLE FLOATVAL get_number_keyed_int(INTVAL idx) {
 231         PMC * const key = (PMC *)PMC_struct_val(SELF);
 232         PMC * const agg = PMC_pmc_val(SELF);
 233         return VTABLE_get_number_keyed_int(INTERP, agg, PMC_int_val(key) + idx);
 234     }
 235
 236
 237
 238 /*
 239
 240 =item C<STRING *get_string_keyed(PMC *key)>
 241
 242 =cut
 243
 244 */
 245
 246     VTABLE STRING *get_string_keyed(PMC *key) {
 247         return VTABLE_get_string_keyed(INTERP, PMC_pmc_val(SELF), key);
 248     }
 249
 250 /*
 251
 252 =item C<STRING *get_string_keyed_int(INTVAL idx)>
 253
 254 Get string value of current position plus idx.
 255
 256 =cut
 257
 258 */
 259
 260     VTABLE STRING *get_string_keyed_int(INTVAL idx) {
 261         PMC * const key = (PMC *)PMC_struct_val(SELF);
 262         PMC * const agg = PMC_pmc_val(SELF);
 263         return VTABLE_get_string_keyed_int(INTERP, agg, PMC_int_val(key) + idx);
 264     }
 265
 266 /*
 267
 268 =item C<INTVAL get_bool()>
 269
 270 Returns true if the idx/key is not C<-1>.
 271
 272 =cut
 273
 274 */
 275
 276     VTABLE INTVAL get_bool() {
 277         PMC * const key = (PMC *)PMC_struct_val(SELF);
 278         return key && PMC_int_val(key) != -1;
 279     }
 280
 281 /*
 282
 283 =item C<INTVAL elements()>
 284
 285 Returns the number of remaining elements in the aggregate. TODO.
 286
 287 =cut
 288
 289 */
 290
 291     VTABLE INTVAL elements() {
 292         return VTABLE_elements(INTERP, PMC_pmc_val(SELF));
 293     }
 294
 295 /*
 296
 297 =item C<PMC *get_pmc_keyed(PMC *key)>
 298
 299 Returns the element for C<*key>.
 300
 301 =cut
 302
 303 */
 304
 305     VTABLE PMC *get_pmc_keyed(PMC *key) {
 306         return VTABLE_get_pmc_keyed(INTERP, PMC_pmc_val(SELF), key);
 307     }
 308
 309 /*
 310
 311 =item C<PMC *get_pmc_keyed_int(INTVAL key)>
 312
 313 Returns the element for C<key>.
 314
 315 =cut
 316
 317 */
 318
 319     VTABLE PMC *get_pmc_keyed_int(INTVAL idx) {
 320         PMC * const key = (PMC *)PMC_struct_val(SELF);
 321         PMC * const agg = PMC_pmc_val(SELF);
 322         return VTABLE_get_pmc_keyed_int(INTERP, agg, PMC_int_val(key) + idx);
 323     }
 324
 325 /*
 326
 327 =item C<void set_integer_native(INTVAL value)>
 328
 329 Reset the Iterator. C<value> must be one of
 330
 331  ITERATE_FROM_START        ... Iterate from start
 332  ITERATE_FROM_START_KEYS   ... OrderedHash by keys
 333  ITERATE_FROM_END          ... Arrays and PerlString only
 334
 335 =cut
 336
 337 */
 338
 339     VTABLE void set_integer_native(INTVAL value) {
 340         PMC *key, *agg;
 341         if (value < ITERATE_FROM_START || value > ITERATE_FROM_END)
 342             real_exception(INTERP, NULL, E_TypeError,
 343                     "Illegal set_integer on iterator");
 344
 345         /* reset iterator on aggregate */
 346         agg = PMC_pmc_val(SELF);
 347
 348         if (agg->vtable->base_type == enum_class_Slice) {
 349             /* it's an xrange serving as its own aggregate */
 350             PMC_struct_val(SELF) =
 351                 VTABLE_nextkey_keyed(INTERP, agg, NULL, value);
 352         }
 353         else {
 354             if (!PMC_struct_val(SELF))
 355                 key = key_new(INTERP);
 356             else
 357                 key = (PMC *)PMC_struct_val(SELF);
 358
 359             PMC_struct_val(SELF) =
 360                 VTABLE_nextkey_keyed(INTERP, key, agg, value);
 361         }
 362     }
 363
 364 /*
 365
 366 =item C<INTVAL pop_integer()>
 367
 368 =cut
 369
 370 */
 371
 372     VTABLE INTVAL pop_integer() {
 373         PMC * const key      = (PMC *)PMC_struct_val(SELF);
 374         PMC * const agg      = PMC_pmc_val(SELF);
 375         const INTVAL ret     = VTABLE_get_integer_keyed(INTERP, agg, key);
 376         PMC_struct_val(SELF) =
 377             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_PREV);
 378
 379         return ret;
 380     }
 381
 382 /*
 383
 384 =item C<FLOATVAL pop_float()>
 385
 386 =cut
 387
 388 */
 389
 390     VTABLE FLOATVAL pop_float() {
 391         PMC * const key      = (PMC *)PMC_struct_val(SELF);
 392         PMC * const agg      = PMC_pmc_val(SELF);
 393         const FLOATVAL ret   = VTABLE_get_number_keyed(INTERP, agg, key);
 394         PMC_struct_val(SELF) =
 395             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_PREV);
 396
 397         return ret;
 398     }
 399
 400 /*
 401
 402 =item C<STRING *pop_string()>
 403
 404 =cut
 405
 406 */
 407
 408     VTABLE STRING *pop_string() {
 409         PMC * const key      = (PMC *)PMC_struct_val(SELF);
 410         PMC * const agg      = PMC_pmc_val(SELF);
 411         STRING * const ret   = VTABLE_get_string_keyed(INTERP, agg, key);
 412         PMC_struct_val(SELF) =
 413             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_PREV);
 414         return ret;
 415     }
 416
 417 /*
 418
 419 =item C<PMC *pop_pmc()>
 420
 421 Returns the element for the current idx/key and sets the idx/key to
 422 the previous one.
 423
 424 =cut
 425
 426 */
 427
 428     VTABLE PMC *pop_pmc() {
 429         PMC * const key      = (PMC *)PMC_struct_val(SELF);
 430         PMC * const agg      = PMC_pmc_val(SELF);
 431         PMC * const ret      = VTABLE_get_pmc_keyed(INTERP, agg, key);
 432         PMC_struct_val(SELF) =
 433             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_PREV);
 434
 435         return ret;
 436     }
 437
 438 /*
 439
 440 =item C<INTVAL shift_integer()>
 441
 442 Returns the element for the current idx/key and sets the idx/key to
 443 the next one.
 444
 445 =cut
 446
 447 */
 448
 449     VTABLE INTVAL shift_integer() {
 450         PMC * const key      = (PMC *)PMC_struct_val(SELF);
 451         PMC * const agg      = PMC_pmc_val(SELF);
 452         const INTVAL ret     = VTABLE_get_integer_keyed(INTERP, agg, key);
 453         PMC_struct_val(SELF) =
 454             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_NEXT);
 455         return ret;
 456     }
 457
 458 /*
 459
 460 =item C<opcode_t *invoke(void *next)>
 461
 462 Return the next element of the aggregate. The return type may depend on
 463 the aggregate. If there are no more items in the aggregate, I1 .. I4 are
 464 zero.
 465
 466 See F<docs/pdds/pdd03_calling_conventions.pod>.
 467
 468 =cut
 469
 470 */
 471     VTABLE opcode_t *invoke(void *next) {
 472         PMC *agg;
 473
 474         /* iterator constructor */
 475         if (REG_INT(interp, 3) == 1) {
 476             PMC *arg = REG_PMC(interp, 5);
 477             PMC *iter;
 478
 479             if (PObj_is_object_TEST(arg)) {
 480                 REG_PMC(interp, 5) = VTABLE_get_iter(INTERP, arg);
 481                 return (opcode_t *)next;
 482             }
 483
 484             REG_PMC(interp, 5) = iter = pmc_new_init(INTERP,
 485                     enum_class_Iterator, arg);
 486             VTABLE_set_integer_native(INTERP, iter, 0);
 487             return (opcode_t *)next;
 488         }
 489         /* TODO function + sentinel */
 490         else if (REG_INT(interp, 3) == 2)
 491             real_exception(INTERP, NULL, E_AssertionError,
 492                     "Iterator: invoke 2 args");
 493
 494         REG_INT(interp, 1) =
 495             REG_INT(interp, 2) =
 496             REG_INT(interp, 3) =
 497             REG_INT(interp, 4) = 0;
 498
 499         agg        = PMC_pmc_val(SELF);
 500
 501         if (agg->vtable->base_type == enum_class_IntList) {
 502             const INTVAL ires  = SELF.shift_integer();
 503             REG_INT(interp, 1) = 1;
 504             REG_INT(interp, 5) = ires;
 505             return (opcode_t *)next;
 506         }
 507         else {
 508             PMC * const res    = SELF.shift_pmc();
 509             REG_INT(interp, 3) = 1;
 510             REG_PMC(interp, 5) = res;
 511             return (opcode_t *)next;
 512         }
 513     }
 514
 515 /*
 516
 517 =item C<FLOATVAL shift_float()>
 518
 519 =cut
 520
 521 */
 522
 523     VTABLE FLOATVAL shift_float() {
 524         PMC * const key      = (PMC *)PMC_struct_val(SELF);
 525         PMC * const agg      = PMC_pmc_val(SELF);
 526         const FLOATVAL ret   = VTABLE_get_number_keyed(INTERP, agg, key);
 527         PMC_struct_val(SELF) =
 528             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_NEXT);
 529         return ret;
 530     }
 531
 532
 533 /*
 534
 535 =item C<STRING *shift_string()>
 536
 537 =cut
 538
 539 */
 540
 541     VTABLE STRING *shift_string() {
 542         PMC * const key      = (PMC *)PMC_struct_val(SELF);
 543         PMC * const agg      = PMC_pmc_val(SELF);
 544         STRING * const ret   = VTABLE_get_string_keyed(INTERP, agg, key);
 545         PMC_struct_val(SELF) =
 546             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_NEXT);
 547         return ret;
 548     }
 549
 550 /*
 551
 552 =item C<PMC *shift_pmc()>
 553
 554 Returns the element for the current idx/key and sets the idx/key to
 555 the next one.
 556
 557 =cut
 558
 559 */
 560
 561     VTABLE PMC *shift_pmc() {
 562         PMC * const key = (PMC *)PMC_struct_val(SELF);
 563         PMC * const agg = PMC_pmc_val(SELF);
 564         PMC        *ret;
 565
 566         if (PMC_int_val(key) == -1)
 567             real_exception(INTERP, NULL, E_StopIteration, "StopIteration");
 568
 569         ret = VTABLE_get_pmc_keyed(INTERP, agg, key);
 570
 571         PMC_struct_val(SELF) =
 572             VTABLE_nextkey_keyed(INTERP, key, agg, ITERATE_GET_NEXT);
 573
 574         return ret;
 575     }
 576
 577 /*
 578
 579 =item C<INTVAL exists_keyed(PMC *key)>
 580
 581 Returns whether an element for C<*key> exists in the aggregate.
 582
 583 =cut
 584
 585 */
 586
 587     VTABLE INTVAL exists_keyed(PMC *key) {
 588         return VTABLE_exists_keyed(INTERP, PMC_pmc_val(SELF), key);
 589     }
 590
 591 /*
 592
 593 =item C<INTVAL exists_keyed_int(INTVAL idx)>
 594
 595 Returns whether an element for C<idx> exists in the aggregate.
 596
 597 =cut
 598
 599 */
 600
 601     VTABLE INTVAL exists_keyed_int(INTVAL idx) {
 602         PMC * const key = (PMC *)PMC_struct_val(SELF);
 603         PMC * const agg = PMC_pmc_val(SELF);
 604         return VTABLE_exists_keyed_int(INTERP, agg, PMC_int_val(key) + idx);
 605     }
 606
 607 /*
 608
 609 =item C<INTVAL defined()>
 610
 611 Returns whether the iterator contains an aggregate.
 612
 613 =cut
 614
 615 */
 616
 617     VTABLE INTVAL defined() {
 618         return (INTVAL)(PMC_pmc_val(SELF) != 0);
 619     }
 620
 621 /*
 622
 623 =item C<INTVAL defined_keyed(PMC *key)>
 624
 625 =cut
 626
 627 */
 628
 629     VTABLE INTVAL defined_keyed(PMC *key) {
 630         return VTABLE_defined_keyed(INTERP, PMC_pmc_val(SELF), key);
 631     }
 632
 633 /*
 634
 635 =item C<INTVAL defined_keyed_int(INTVAL key)>
 636
 637 Returns the result of calling C<defined_keyed(key)> on the aggregate.
 638
 639 =cut
 640
 641 */
 642
 643     VTABLE INTVAL defined_keyed_int(INTVAL idx) {
 644         PMC * const key = (PMC *)PMC_struct_val(SELF);
 645         PMC * const agg = PMC_pmc_val(SELF);
 646         return VTABLE_defined_keyed_int(INTERP, agg, PMC_int_val(key) + idx);
 647     }
 648
 649 /*
 650
 651 =item C<INTVAL type_keyed(PMC *key)>
 652
 653 Returns the result of calling C<type_keyed(key)> on the aggregate.
 654
 655 =cut
 656
 657 */
 658
 659     VTABLE INTVAL type_keyed(PMC *key) {
 660         return VTABLE_type_keyed(INTERP, PMC_pmc_val(SELF), key);
 661     }
 662
 663 /*
 664
 665 =item C<INTVAL type_keyed_int(PMC *idx)>
 666
 667 Returns the result of calling C<type_keyed(key)> on the aggregate.
 668
 669 =cut
 670
 671 */
 672
 673     VTABLE INTVAL type_keyed_int(INTVAL idx) {
 674         PMC * const key = (PMC *)PMC_struct_val(SELF);
 675         PMC * const agg = PMC_pmc_val(SELF);
 676         return VTABLE_type_keyed_int(INTERP, agg, PMC_int_val(key) + idx);
 677     }
 678
 679     VTABLE PMC *get_iter() {
 680         return SELF;
 681     }
 682 }
 683
 684 /*
 685
 686 =back
 687
 688 =cut
 689
 690 */
 691
 692 /*
 693  * Local variables:
 694  *   c-file-style: "parrot"
 695  * End:
 696  * vim: expandtab shiftwidth=4:
 697  */