// -*- C++ -*-

// (c) COPYRIGHT URI/MIT 1994-1999
// Please read the full copyright statement in the file COPYRIGHT.
//
// Authors:
//      jhrg,jimg       James Gallagher (jgallagher@gso.uri.edu)

// Interface for List type.
//
// jhrg 9/7/94

/* 
 * $Log: List.h,v $
 * Revision 1.28  1999/05/04 19:47:21  jimg
 * Fixed copyright statements. Removed more of the GNU classes.
 *
 * Revision 1.27  1999/04/29 02:29:30  jimg
 * Merge of no-gnu branch
 *
 * Revision 1.26.6.1  1999/02/02 21:57:00  jimg
 * String to string version
 *
 * Revision 1.26  1998/02/05 20:13:54  jimg
 * DODS now compiles with gcc 2.8.x
 *
 * Revision 1.25  1998/01/12 14:27:59  tom
 * Second pass at class documentation.
 *
 * Revision 1.24  1997/12/18 15:06:12  tom
 * First draft of class documentation, entered in doc++ format,
 * in the comments
 *
 * Revision 1.23  1997/08/11 18:19:18  jimg
 * Fixed comment leaders for new CVS version
 *
 * Revision 1.22  1996/12/02 23:17:27  jimg
 * member member function now takes a DDS & in addition to the BaseType *. This
 * makes it possible to use the new `filename' field of the DDS to pass the
 * filename into member()'s use of ops().
 *
 * Revision 1.21  1996/05/31 23:29:55  jimg
 * Updated copyright notice.
 *
 * Revision 1.20  1996/05/29 22:08:44  jimg
 * Made changes necessary to support CEs that return the value of a function
 * instead of the value of a variable. This was done so that it would be
 * possible to translate Sequences into Arrays without first reading the
 * entire sequence over the network.
 *
 * Revision 1.19  1996/05/16 22:50:05  jimg
 * Dan's changes for version 2.0. Added a parameter to read that returns
 * an error code so that EOF can be distinguished from an actual error when
 * reading sequences. This *may* be replaced by an error member function
 * in the future.
 *
 * Revision 1.18  1996/03/05 18:05:13  jimg
 * Added member and null member functions.
 *
 * Revision 1.17  1995/12/09  01:06:51  jimg
 * Added changes so that relational operators will work properly for all the
 * datatypes (including Sequences). The relational ops are evaluated in
 * DDS::eval_constraint() after being parsed by DDS::parse_constraint().
 *
 * Revision 1.16  1995/12/06  21:56:27  jimg
 * Added `constrained' flag to print_decl.
 * Removed third parameter of read.
 * Modified print_decl() to print only those parts of a dataset that are
 * selected when `constrained' is true.
 *
 * Revision 1.15  1995/11/22  22:31:01  jimg
 * Modified so that the Vector class is now the parent class.
 *
 * Revision 1.14  1995/10/23  23:21:00  jimg
 * Added _send_p and _read_p fields (and their accessors) along with the
 * virtual mfuncs set_send_p() and set_read_p().
 *
 * Revision 1.13  1995/08/26  00:31:42  jimg
 * Removed code enclosed in #ifdef NEVER #endif.
 *
 * Revision 1.12  1995/08/22  23:48:18  jimg
 * Removed card() member function.
 * Removed old, deprecated member functions.
 * Changed the names of read_val and store_val to buf2val and val2buf.
 *
 * Revision 1.11  1995/03/04  15:30:09  jimg
 * Fixed List so that it will compile - it still has major bugs.
 * Modified Makefile.in so that test cases include List even though List
 * won't work (but at least the test cases will link and run, so long
 * as you don't try to do anything with Lists...
 *
 * Revision 1.10  1995/03/04  14:35:03  jimg
 * Major modifications to the transmission and representation of values:
 * Added card() virtual function which is true for classes that
 * contain cardinal types (byte, int float, string).
 * Changed the representation of Str from the C rep to a C++
 * class represenation.
 * Chnaged read_val and store_val so that they take and return
 * types that are stored by the object (e.g., inthe case of Str
 * an URL, read_val returns a C++ String object).
 * Modified Array representations so that arrays of card()
 * objects are just that - no more storing strings, ... as
 * C would store them.
 * Arrays of non cardinal types are arrays of the DODS objects (e.g.,
 * an array of a structure is represented as an array of Structure
 * objects).
 *
 * Revision 1.9  1995/02/10  02:22:56  jimg
 * Added DBMALLOC includes and switch to code which uses malloc/free.
 * Private and protected symbols now start with `_'.
 * Added new accessors for name and type fields of BaseType; the old ones
 * will be removed in a future release.
 * Added the store_val() mfunc. It stores the given value in the object's
 * internal buffer.
 * Made both List and Str handle their values via pointers to memory.
 * Fixed read_val().
 * Made serialize/deserialize handle all malloc/free calls (even in those
 * cases where xdr initiates the allocation).
 * Fixed print_val().
 *
 * Revision 1.8  1995/01/19  21:59:21  jimg
 * Added read_val from dummy_read.cc to the sample set of sub-class
 * implementations.
 * Changed the declaration of readVal in BaseType so that it names the
 * mfunc read_val (to be consistant with the other mfunc names).
 * Removed the unnecessary duplicate declaration of the abstract virtual
 * mfuncs read and (now) read_val from the classes Byte, ... Grid. The
 * declaration in BaseType is sufficient along with the decl and definition
 * in the *.cc,h files which contain the subclasses for Byte, ..., Grid.
 *
 * Revision 1.7  1995/01/18  18:39:42  dan
 * Declared member function 'readVal', defined in dummy_read.cc
 *
 * Revision 1.6  1995/01/11  15:54:43  jimg
 * Added modifications necessary for BaseType's static XDR pointers. This
 * was mostly a name change from xdrin/out to _xdrin/out.
 * Removed the two FILE pointers from ctors, since those are now set with
 * functions which are friends of BaseType.
 *
 * Revision 1.5  1994/12/15  21:11:57  dan
 * Fixed size() member function to return cumulative size of all members
 * of the list.
 * Added length() member function to return number of list elements.
 *
 * Revision 1.4  1994/12/15  15:33:18  jimg
 * Added functions for data transmission.
 * Added size and *buf members.
 * Added accesser mfuncs for size memebr.
 *
 * Revision 1.3  1994/10/17  23:34:46  jimg
 * Added code to print_decl so that variable declarations are pretty
 * printed.
 * Added private mfunc duplicate().
 * Added ptr_duplicate().
 * Added Copy ctor, dtor and operator=.
 *
 * Revision 1.2  1994/09/23  14:46:17  jimg
 * Fixed some errors in comments.
 */

#ifndef _List_h
#define _List_h 1

#ifdef __GNUG__
#pragma interface
#endif

#include <string>

#include "dods-limits.h"
#include "Vector.h"

const int DODS_MAX_LIST = DODS_INT_MAX;

  /** This class uses the Vector class to implement a simple list of
      DODS data types.  A list is a simple sequence of data items,
      without the sophisticated subsetting and array indexing features
      of an Array.

      DODS does not support Lists of Lists.

      @memo Holds a List of other objects.
      */

class List: public Vector {
protected:
    void _duplicate(const List &l);

public:
  /** The List constructor requires the name of the variable
      to be created, and the type of data the list is to hold.  
      The name may be omitted, which will create a
      nameless variable.  The template pointer may not be omitted. 
      
      @param n A string containing the name of the variable to be
      created. 
      @param v A pointer to a variable of the type to be included 
      in the list.  This variable may not itself be a List.

      @memo The List constructor.
      */
    List(const string &n = "", BaseType *v = 0);
  /** The List copy constructor. */
    List(const List &rhs);
    virtual ~List();

    const List &operator=(const List &rhs);
    virtual BaseType *ptr_duplicate() = 0;

    virtual bool read(const string &dataset, int &error) = 0;

  /** Determine whether an object is a member of the list.

      @return TRUE if {\it *btp} is a member of the list.
      @param btp A pointer to an object.
      @param dds The fully-initialized data descriptor object
      corresponding to the dataset containing the list.
      */
    virtual bool member(BaseType *btp, DDS &dds);

  /** Returns TRUE if the list is empty. */
    virtual bool null();
};

#endif