///////////////////////////////////////////////////////////////////////////////
//                             Lisaac Library                                //
//                                                                           //
//                   LSIIT - ULP - CNRS - INRIA - FRANCE                     //
//                                                                           //
//   This program is free software: you can redistribute it and/or modify    //
//   it under the terms of the GNU General Public License as published by    //
//   the Free Software Foundation, either version 3 of the License, or       //
//   (at your option) any later version.                                     //
//                                                                           //
//   This program is distributed in the hope that it will be useful,         //
//   but WITHOUT ANY WARRANTY; without even the implied warranty of          //
//   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           //
//   GNU General Public License for more details.                            //
//                                                                           //
//   You should have received a copy of the GNU General Public License       //
//   along with this program.  If not, see <http://www.gnu.org/licenses/>.   //
//                                                                           //
//                     http://isaacproject.u-strasbg.fr/                     //
///////////////////////////////////////////////////////////////////////////////
Section Header
  
  + name    := TRAVERSABLE[V];


  - copyright   := "2003-2005 Jérome Boutet, 2003-2007 Benoit Sonntag";
  
  - comment := "A `TRAVERSABLE[E_]' is a finite readable sequence of objects of type E_.";
  
  // For instance, `COLLECTION's and `STRING's are `TRAVERSABLE'.
  //
  // A good performance should always be obtained by sequentially acessing a 
  // `TRAVERSABLE' with increasing indexes (from `lower' to `upper'), as 
  // demonstrated in the following code snippet :
  //
  //  i := a_traversable.lower;
  //  {i > a_traversable.upper}.until_do {
  //    do_something_with (a_traversable.item i);
  //    i := i + 1;
  //  };
  //
  // Other accessing methods (including random access and sequential access 
  // from `upper' to `lower') may or may not lead to acceptable performance, 
  // depending on the particular implementation of `TRAVERSABLE'.
  
Section Inherit
  
  - parent_object:OBJECT := OBJECT;
  
Section Public
  
  //
  // Indexing:
  //
  
  - lower:INTEGER <-
  // Minimum index.
  //
  // See also `upper', `valid_index', `item'.
  (
    deferred;
    0
  );

  - upper:INTEGER <-
  // Maximum index.
  //
  // See also `lower', `valid_index', `item'.
  (
    deferred;
    0
  );	
  
  - valid_index i:INTEGER :BOOLEAN <-
  // True when `i' is valid (i.e., inside actual bounds).
  //
  // See also `lower', `upper', `item'.
  ( 
    (lower <= i) && {i <= upper}
  )
  [        
    "Definition." +? {Result = ((lower <= i) & (i <= upper))};
  ];

  //
  // Counting:
  //
  
  - count:INTEGER <-
  // Number of available indices.
  //
  // See also `is_empty', `lower', `upper'.
  (
    deferred;
    0
  )
  [
    "Definition." +? {Result = upper - lower + 1};
  ];

  - is_empty:BOOLEAN <-
  // Is collection empty ?
  //
  // See also `count'.
  (
    deferred
    FALSE
  )
  [
    "Definition." +? {Result = (count = 0)};
  ];
  
  //
  // Accessing:
  //
  
  - item i:INTEGER :V <-
  // Item at the corresponding index `i'.
  //
  // See also `lower', `upper', `valid_index'.
  [
    -? {valid_index i};
  ]
  (
    deferred;
    V
  );

  - first:V <-
  // The very `first' item.
  //
  // See also `last', `item'.
  [
    -? {! is_empty};
  ]
  (
    deferred;
    V
  )
  [	
    "Definition." +? {Result = item lower};
  ];

  - last:V <-
  // The `last' item.
  //
  // See also `first', `item'.
  [ 
    -? {! is_empty};
  ]
  (
    deferred;
    V
  )
  [
    "Definition." +? {Result = item upper};
  ];
  
  