gee/list.vala

   1 /* list.vala
   2  *
   3  * Copyright (C) 2007  Jürg Billeter
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  18  *
  19  * Author:
  20  *      Jürg Billeter <j@bitron.ch>
  21  */
  22
  23 /**
  24  * An ordered collection.
  25  */
  26 [GenericAccessors]
  27 public interface Gee.List<G> : Collection<G> {
  28         /**
  29          * Returns a ListIterator that can be used for iteration over this list.
  30          *
  31          * @return a ListIterator that can be used for iteration over this list
  32          */
  33         public abstract new ListIterator<G> list_iterator ();
  34
  35         /**
  36          * Returns the item at the specified index in this list.
  37          *
  38          * @param index zero-based index of the item to be returned
  39          *
  40          * @return      the item at the specified index in the list
  41          */
  42         public abstract G get (int index);
  43
  44         /**
  45          * Sets the item at the specified index in this list.
  46          *
  47          * @param index zero-based index of the item to be set
  48          */
  49         public abstract void set (int index, G item);
  50
  51         /**
  52          * Returns the index of the first occurence of the specified item in
  53          * this list.
  54          *
  55          * @return the index of the first occurence of the specified item, or
  56          *         -1 if the item could not be found
  57          */
  58         public abstract int index_of (G item);
  59
  60         /**
  61          * Inserts an item into this list at the specified position.
  62          *
  63          * @param index zero-based index at which item is inserted
  64          * @param item  item to insert into the list
  65          */
  66         public abstract void insert (int index, G item);
  67
  68         /**
  69          * Removes the item at the specified index of this list.
  70          *
  71          * @param index zero-based index of the item to be removed
  72          *
  73          * @return      the removed element
  74          */
  75         public abstract G remove_at (int index);
  76
  77         /**
  78          * Returns a slice of this list.
  79          *
  80          * @param start zero-based index of the begin of the slice
  81          * @param stop  zero-based index after the end of the slice
  82          *
  83          * @return A list containing a slice of this list
  84          */
  85         public abstract List<G>? slice (int start, int stop);
  86
  87         /**
  88          * Returns the first item of the list. Fails if the list is empty.
  89          *
  90          * @return      first item in the list
  91          */
  92         public virtual G first () {
  93                 return get (0);
  94         }
  95
  96         /**
  97          * Returns the last item of the list. Fails if the list is empty.
  98          *
  99          * @return      last item in the list
 100          */
 101         public virtual G last () {
 102                 return get (size - 1);
 103         }
 104
 105         /**
 106          * Inserts items into this list for the input collection at the
 107          * specified position.
 108          *
 109          * @param index zero-based index of the items to be inserted
 110          * @param collection collection of items to be inserted
 111          */
 112         public virtual void insert_all (int index, Collection<G> collection) {
 113                 foreach (G item in collection) {
 114                         insert(index, item);
 115                         index++;
 116                 }
 117         }
 118
 119         /**
 120          * Sorts items by comparing with the specified compare function.
 121          *
 122          * @param compare_func compare function to use to compare items
 123          */
 124         public virtual void sort (owned CompareDataFunc<G>? compare_func = null) {
 125                 if (compare_func == null) {
 126                         compare_func = Functions.get_compare_func_for (typeof (G));
 127                 }
 128                 TimSort.sort<G> (this, compare_func);
 129         }
 130
 131         /**
 132          * The read-only view of this list.
 133          */
 134         public abstract new List<G> read_only_view { owned get; }
 135
 136         /**
 137          * Returns an immutable empty list.
 138          *
 139          * @return an immutable empty list
 140          */
 141         public static List<G> empty<G> () {
 142                 return new LinkedList<G> ().read_only_view;
 143         }
 144 }
 145