3 * Copyright (C) 2009 Didier Villevalois
4 * Copyright (C) 2011 Maciej Piechotka
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.
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.
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
21 * Didier 'Ptitjes Villevalois <ptitjes@free.fr>
25 public delegate A FoldMapFunc<A, K, V> (K k, V v, owned A a);
26 public delegate void ForallMapFunc<K, V> (K k, V v);
30 * An iterator over a map.
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}.
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
42 public interface Gee.MapIterator<K,V> : Object {
44 * Advances to the next entry in the iteration.
46 * @return ``true`` if the iterator has a next entry
48 public abstract bool next ();
51 * Checks whether there is a next entry in the iteration.
53 * @return ``true`` if the iterator has a next entry
55 public abstract bool has_next ();
58 * Returns the current key in the iteration.
60 * @return the current key in the iteration
62 public abstract K get_key ();
65 * Returns the value associated with the current key in the iteration.
67 * @return the value for the current key
69 public abstract V get_value ();
72 * Sets the value associated with the current key in the iteration.
74 * @param value the new value for the current key
76 public abstract void set_value (V value);
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
84 public abstract void unset ();
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.
91 public abstract bool valid { get; }
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.
98 public abstract bool mutable { get; }
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.
105 public abstract bool read_only { get; }
108 * Standard aggragation function.
110 * It takes a function, seed and first element, returns the new seed and
111 * progress to next element when the operation repeats.
113 * Operation moves the iterator to last element in iteration. If iterator
114 * points at some element it will be included in iteration.
116 public virtual A fold<A> (FoldMapFunc<A, K, V> f, owned A seed)
119 seed = f (get_key (), get_value (), (owned) seed);
121 seed = f (get_key (), get_value (), (owned) seed);
126 * Apply function to each element returned by iterator.
128 * Operation moves the iterator to last element in iteration. If iterator
129 * points at some element it will be included in iteration.
131 public new virtual void foreach (ForallMapFunc<K, V> f) {
133 f (get_key (), get_value ());
135 f (get_key (), get_value ());