gee/mapiterator.vala

   1 /* mapiterator.vala
   2  *
   3  * Copyright (C) 2009  Didier Villevalois
   4  * Copyright (C) 2011  Maciej Piechotka
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  19  *
  20  * Author:
  21  *      Didier 'Ptitjes Villevalois <ptitjes@free.fr>
  22  */
  23
  24 namespace Gee {
  25         public delegate A FoldMapFunc<A, K, V> (K k, V v, owned A a);
  26         public delegate bool ForallMapFunc<K, V> (K k, V v);
  27 }
  28
  29 /**
  30  * An iterator over a map.
  31  *
  32  * Gee's iterators are "on-track" iterators. They always point to an item
  33  * except before the first call to {@link next}, or, when an
  34  * item has been removed, until the next call to {@link next}.
  35  *
  36  * Please note that when the iterator is out of track, neither {@link get_key},
  37  * {@link get_value}, {@link set_value} nor {@link unset} are defined and all
  38  * will fail. After the next call to {@link next}, they will
  39  * be defined again.
  40  */
  41 [GenericAccessors]
  42 public interface Gee.MapIterator<K,V> : Object {
  43         /**
  44          * Advances to the next entry in the iteration.
  45          *
  46          * @return ``true`` if the iterator has a next entry
  47          */
  48         public abstract bool next ();
  49
  50         /**
  51          * Checks whether there is a next entry in the iteration.
  52          *
  53          * @return ``true`` if the iterator has a next entry
  54          */
  55         public abstract bool has_next ();
  56
  57         /**
  58          * Returns the current key in the iteration.
  59          *
  60          * @return the current key in the iteration
  61          */
  62         public abstract K get_key ();
  63
  64         /**
  65          * Returns the value associated with the current key in the iteration.
  66          *
  67          * @return the value for the current key
  68          */
  69         public abstract V get_value ();
  70
  71         /**
  72          * Sets the value associated with the current key in the iteration.
  73          *
  74          * @param value the new value for the current key
  75          */
  76         public abstract void set_value (V value);
  77
  78         /**
  79          * Unsets the current entry in the iteration. The cursor is set in an
  80          * in-between state. {@link get_key}, {@link get_value}, {@link set_value}
  81          * and {@link unset} will fail until the next move of the cursor (calling
  82          * {@link next}).
  83          */
  84         public abstract void unset ();
  85
  86         /**
  87          * Determines wheather the call to {@link get_key}, {@link get_value} and
  88          * {@link set_value} is legal. It is false at the beginning and after
  89          * {@link unset} call and true otherwise.
  90          */
  91         public abstract bool valid { get; }
  92
  93         /**
  94          * Determines wheather the call to {@link set_value} is legal assuming the
  95          * iterator is valid. The value must not change in runtime hence the user
  96          * of iterator may cache it.
  97          */
  98         public abstract bool mutable { get; }
  99
 100         /**
 101          * Determines wheather the call to {@link unset} is legal assuming the
 102          * iterator is valid. The value must not change in runtime hence the user
 103          * of iterator may cache it.
 104          */
 105         public abstract bool read_only { get; }
 106
 107         /**
 108          * Standard aggragation function.
 109          *
 110          * It takes a function, seed and first element, returns the new seed and
 111          * progress to next element when the operation repeats.
 112          *
 113          * Operation moves the iterator to last element in iteration. If iterator
 114          * points at some element it will be included in iteration.
 115          */
 116         public virtual A fold<A> (FoldMapFunc<A, K, V> f, owned A seed)
 117         {
 118                 if (valid)
 119                         seed = f (get_key (), get_value (), (owned) seed);
 120                 while (next ())
 121                         seed = f (get_key (), get_value (), (owned) seed);
 122                 return (owned) seed;
 123         }
 124
 125         /**
 126          * Apply function to each element returned by iterator.
 127          *
 128          * Operation moves the iterator to last element in iteration. If iterator
 129          * points at some element it will be included in iteration.
 130          */
 131         public new virtual bool foreach (ForallMapFunc<K, V> f) {
 132                 if (valid) {
 133                         if (!f (get_key (), get_value ())) {
 134                                 return false;
 135                         }
 136                 }
 137                 while (next ()) {
 138                         if (!f (get_key (), get_value ())) {
 139                                 return false;
 140                         }
 141                 }
 142                 return true;
 143         }
 144 }
 145