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  * Represents a collection of items in a well-defined order.
  25  */
  26 public abstract class Vala.List<G> : Collection<G> {
  27         /**
  28          * Returns the item at the specified index in this list.
  29          *
  30          * @param index zero-based index of the item to be returned
  31          *
  32          * @return      the item at the specified index in the list
  33          */
  34         public abstract G? get (int index);
  35
  36         /**
  37          * Sets the item at the specified index in this list.
  38          *
  39          * @param index zero-based index of the item to be set
  40          */
  41         public abstract void set (int index, G item);
  42
  43         /**
  44          * Returns the index of the first occurrence of the specified item in
  45          * this list.
  46          *
  47          * @return the index of the first occurrence of the specified item, or
  48          *         -1 if the item could not be found
  49          */
  50         public abstract int index_of (G item);
  51
  52         /**
  53          * Inserts an item into this list at the specified position.
  54          *
  55          * @param index zero-based index at which item is inserted
  56          * @param item  item to insert into the list
  57          */
  58         public abstract void insert (int index, G item);
  59
  60         /**
  61          * Removes the item at the specified index of this list.
  62          *
  63          * @param index zero-based index of the item to be removed
  64          *
  65          * @return      the removed element
  66          */
  67         public abstract G remove_at (int index);
  68
  69         /**
  70          * Returns the first item of the list. Fails if the list is empty.
  71          *
  72          * @return      first item in the list
  73          */
  74         public virtual G first () {
  75                 return @get (0);
  76         }
  77
  78         /**
  79          * Returns the last item of the list. Fails if the list is empty.
  80          *
  81          * @return      last item in the list
  82          */
  83         public virtual G last () {
  84                 return @get (size - 1);
  85         }
  86
  87         /**
  88          * Inserts items into this list for the input collection at the
  89          * specified position.
  90          *
  91          * @param index zero-based index of the items to be inserted
  92          * @param collection collection of items to be inserted
  93          */
  94         public virtual void insert_all (int index, Collection<G> collection) {
  95                 for (Iterator<G> iter = collection.iterator (); iter.next ();) {
  96                         G item = iter.get ();
  97                         insert (index, item);
  98                         index++;
  99                 }
 100         }
 101
 102         /**
 103          * Sorts items by comparing with the specified compare function.
 104          *
 105          * @param compare_func compare function to use to compare items
 106          */
 107         public virtual void sort (owned CompareDataFunc<G> compare_func) {
 108                 TimSort.sort<G> (this, compare_func);
 109         }
 110 }
 111