gee/sortedset.vala

   1 /* sortedset.vala
   2  *
   3  * Copyright (C) 2009  Didier Villevalois, Maciej Piechotka
   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  *      Maciej Piechotka <uzytkownik2@gmail.com>
  22  */
  23
  24 /**
  25  * A sorted set, which you can navigate over and get sub-sets of.
  26  */
  27 [GenericAccessors]
  28 public interface Gee.SortedSet<G> : Gee.Set<G> {
  29         /**
  30          * Returns the first element of the sorted set. Set must not be empty.
  31          *
  32          * @return the first element in the sorted set
  33          */
  34         public abstract G first ();
  35
  36         /**
  37          * Returns the last element of the sorted set. Set must not be empty.
  38          *
  39          * @return the last element in the sorted set
  40          */
  41         public abstract G last ();
  42
  43         /**
  44          * Returns a {@link BidirIterator} initialy pointed at the specified
  45          * element.
  46          *
  47          * @param element the element to point the iterator at
  48          *
  49          * @return        a {@link BidirIterator} over this sorted set, or null if
  50          *                the specified element is not in this set
  51          */
  52         public abstract Iterator<G>? iterator_at (G element);
  53
  54         /**
  55          * Returns the element which is strictly lower than the specified element.
  56          *
  57          * @param element the element which you want the lower element for
  58          *
  59          * @return        the corresponding element
  60          */
  61         public abstract G? lower (G element);
  62
  63         /**
  64          * Returns the element which is strictly higher than the specified element.
  65          *
  66          * @param element the element which you want the strictly higher element
  67          *                for
  68          *
  69          * @return        the corresponding element
  70          */
  71         public abstract G? higher (G element);
  72
  73         /**
  74          * Returns the element which is lower or equal then the specified element.
  75          *
  76          * @param element the element which you want the lower or equal element for
  77          *
  78          * @return        the corresponding element
  79          */
  80         public abstract G? floor (G element);
  81
  82         /**
  83          * Returns the element which is higher or equal then the specified element.
  84          *
  85          * @param element the element which you want the higher or equal element
  86          *                for
  87          *
  88          * @return        the corresponding element
  89          */
  90         public abstract G? ceil (G element);
  91
  92         /**
  93          * Returns the sub-set of this sorted set containing elements strictly
  94          * lower than the specified element.
  95          *
  96          * @param before the lower inclusive bound for the sub-set
  97          *
  98          * @return     the corresponding sub-set of this sorted set
  99          */
 100         public abstract SortedSet<G> head_set (G before);
 101
 102         /**
 103          * Returns the sub-set of this sorted set containing elements equal or
 104          * higher than the specified element.
 105          *
 106          * @param after the higher exclusive bound for the sub-set
 107          *
 108          * @return   the corresponding sub-set of this sorted set
 109          */
 110         public abstract SortedSet<G> tail_set (G after);
 111
 112         /**
 113          * Returns the right-open sub-set of this sorted set, thus containing
 114          * elements equal or higher than the specified ``from`` element, and stricly
 115          * lower than the specified ``to`` element.
 116          *
 117          * @param from the lower inclusive bound for the sub-set
 118          * @param to   the higher exclusive bound for the sub-set
 119          *
 120          * @return     the corresponding sub-set of this sorted set
 121          */
 122         public abstract SortedSet<G> sub_set (G from, G to);
 123
 124         /**
 125          * The read-only view of this set.
 126          */
 127         public abstract new SortedSet<G> read_only_view { owned get; }
 128
 129         /**
 130          * Returns an immutable empty sorted set.
 131          *
 132          * @return an immutable empty sorted set
 133          */
 134         public static SortedSet<G> empty<G> () {
 135                 return new TreeSet<G> ().read_only_view;
 136         }
 137 }