------------------------->  GNU Sather - sourcefile  <-------------------------
-- Copyright (C) 1994 by International Computer Science Institute            --
-- This file is part of the GNU Sather library. It is free software; you may --
-- redistribute  and/or modify it under the terms of the GNU Library General --
-- Public  License (LGPL)  as published  by the  Free  Software  Foundation; --
-- either version 2 of the license, or (at your option) any later version.   --
-- This  library  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 Doc/LGPL for more details.       --
-- The license text is also available from:  Free Software Foundation, Inc., --
-- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA                     --
-------------->  Please email comments to <bug-sather@gnu.org>  <--------------

-- aref.sa: Built-in reference arrays, primarily to be included.

-------------------------------------------------------------------
class AREF{T} is
   -- Built-in arrays of elements of type T. Primarily intended to be
   -- included in reference classes that need an array portion in their
   -- objects. Array indices start at 0 and go up to "asize-1".
   -- All feature names begin with "a" to minimize name conflicts when
   -- include. None of the features work with void(self).  This class is
   -- primarily meant to be included. ARRAY{T} provides an array 
   -- abstraction that is meant to be used directly.
   
   asize:INT pre ~void(self) is builtin AREF_ASIZE; end;
      -- The number of elements in self. Classes which inherit this may
      -- replace this by a constant to get constant sized objects (and 
      -- the compiler may optimize certain operations in this case).
      -- Built-in.

   create(n:INT):SAME 
      -- A new array with `n' elements.
      pre n>=0 is
      return new(n) 
   end;
   
   aget(ind:INT):T
      -- The element of self with index `ind'. Built-in.
      pre ~void(self) and ind.is_bet(0,asize-1) is
      builtin AREF_AGET; 
   end;

   aset(ind:INT, val:T)
      -- Set the element of self with index `ind' to `val'. Built-in. 
      pre ~void(self) and ind.is_bet(0,asize-1) is 
      builtin AREF_ASET;
   end;

   aclear 
      -- Set each element of self to nil. Built-in.
      pre ~void(self) is 
      builtin AREF_ACLEAR; 
   end;

   aelt!:T 
      -- Yield each element of self in order. Built-in.
      pre ~void(self) is 
      builtin AREF_AELTB;
   end;

   aelt!(once beg:INT):T
      -- Yield each element of self starting at `beg'. Built-in.
      pre ~void(self) and beg.is_bet(0,asize-1) is
      builtin AREF_AELT_BEGB;
   end;
   
   aelt!(once beg,once num:INT):T
      -- Yield `num' successive elements of self starting at
      -- index `beg'. Built-in.
      pre ~void(self) and beg.is_bet(0,asize-1) and 
	 num.is_bet(0,asize-beg) is
      builtin AREF_AELT_BEG_NUMB;
   end;

   private is_legal_aelts_arg( beg, num, step:INT) :BOOL is
      -- True if the arguments are legal values for `aelts'.
      return beg.is_bet(0,asize-1) and
         ((step>0 and num.is_bet(0,(asize-beg+step-1)/step)) or
          (step<0 and num.is_bet(0,(beg-step)/-step))) 
   end;
   
   aelt!(once beg,once num,once step:INT):T
      -- Yield `num' elements of self starting at `beg' and stepping
      -- by `step' which must not be zero. Built-in.
      pre ~void(self) and is_legal_aelts_arg(beg,num,step) is
      builtin AREF_AELT_BEG_NUM_STEPB;
   end;
   
   aset!(val:T) 
      -- Set successive elements of self to the values `val'. 
      -- Built-in.
      pre ~void(self) is 
      builtin AREF_ASETB;
   end;

   aset!(once beg:INT,val:T)
      -- Set successive elements of self starting at `beg' to the 
      -- values `val'. 
      pre ~void(self) and beg.is_bet(0,asize-1) is
      builtin AREF_ASET_BEGB;
   end;
   
   aset!(once beg,once num:INT,val:T)
      -- Set `num' successive elements of self starting at `beg'
      -- to the values `val'. 
      pre ~void(self) and  beg.is_bet(0,asize-1) and 
          num.is_bet(0,asize-beg) is
      builtin AREF_ASET_BEG_NUMB;
   end;

   aset!(once beg,once num,once step:INT, val:T)
      -- Set `num' elements of self starting at `beg' stepping 
      -- by `step' to the values `val'. `step' must not be zero. 
      pre ~void(self) and is_legal_aelts_arg(beg,num,step) is
      builtin AREF_ASET_BEG_NUM_STEPB;
   end;
   
   acopy(src:SAME)
      -- Copy as many elements from `src' to self as will fit.
      -- Built-in.
      pre ~void(self) and ~void(src) is
      builtin AREF_ACOPY;
   end;
   
   acopy(beg:INT, src:SAME)
      -- Copy as many elements from `src' to self as will fit when
      -- starting at index `beg' of self. 
      pre ~void(self) and ~void(src) and (beg.is_bet(0,asize-1) or src.asize=0) is
      builtin AREF_ACOPY_BEG;
   end;
   
   acopy(beg,num:INT, src:SAME)
      -- Copy `num' elements from `src' to self starting at index
      -- `beg' of self.
      pre ~void(self) and ~void(src) and beg.is_bet(0,asize-1) and 
	 num.is_bet(0,asize-beg) and num<=src.asize is
      builtin AREF_ACOPY_BEG_NUM;
   end;
   
   acopy(beg,num,srcbeg:INT, src:SAME)
      -- Copy `num' elements from `src' to self starting at index
      -- `beg' of self and index `srcbeg' of `src'. Built-in.
      pre ~void(self) and ~void(src) and beg.is_bet(0,asize-1) and 
          num.is_bet(0,asize-beg) and num<=src.asize-srcbeg is   
      builtin AREF_ACOPY_BEG_NUM_SRCBEG;
   end;
   
   aind!:INT
      -- Yield the indices of self in order.
      pre ~void(self) is builtin AREF_AINDB; 
   end;

   array_ptr:C_PTR is
      builtin AREF_ARRAY_PTR;
   end;
   
end; -- class AREF{T}

-------------------------------------------------------------------
