// -*- mode: c++; c-basic-offset:4 -*-

// This file is part of libdap, A C++ implementation of the OPeNDAP Data

// Access Protocol.

// Copyright (c) 2002,2003 OPeNDAP, Inc.

// Author: James Gallagher <jgallagher@opendap.org>

//

// This library is free software; you can redistribute it and/or

// modify it under the terms of the GNU Lesser General Public

// License as published by the Free Software Foundation; either

// version 2.1 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 the GNU

// Lesser General Public License for more details.

//

// You should have received a copy of the GNU Lesser General Public

// License along with this library; if not, write to the Free Software

// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

//

// You can contact OPeNDAP, Inc. at PO Box 112, Saunderstown, RI. 02874-0112.

// (c) COPYRIGHT URI/MIT 1994-1999

// Please read the full copyright statement in the file COPYRIGHT_URI.

//

// Authors:

//      jhrg,jimg       James Gallagher <jgallagher@gso.uri.edu>

// Interface for the class Sequence. A sequence contains a single set

// of variables, all at the same lexical level just like a structure

// (and like a structure, it may contain other ctor types...). Unlike

// a structure, a sequence defines a pattern that is repeated N times

// for a sequence of N elements. Thus, Sequence { String name; Int32

// age; } person; means a sequence of N persons where each contain a

// name and age. The sequence can be arbitrarily long (i.e., you don't

// know N by looking at the sequence declaration.

//

// jhrg 9/14/94

#ifndef _sequence_h

#define _sequence_h 1

#include <stack>

#include "Constructor.h"

#ifndef S_XDRUtils_h

#include "XDRUtils.h"

#endif

namespace libdap {

class BaseType;

class ConstraintEvaluator;

class D4Group;

/** The type BaseTypeRow is used to store single rows of values in an

 instance of Sequence. Values are stored in instances of BaseType. */

typedef vector<BaseType *> BaseTypeRow;

/** This type holds all of the values of a Sequence. */

typedef vector<BaseTypeRow *> SequenceValues;

/** This is the interface for the class Sequence. A sequence contains

 a single set of variables, all at the same lexical level just like

 a Structure.  Like a Structure, a Sequence may contain other

 compound types, including other Sequences.  Unlike a Structure, a

 Sequence defines a pattern that is repeated N times for a sequence

 of N elements. It is useful to think of a Sequence as representing

 a table of values (like a relational database), with each row of

 the table corresponding to a Sequence ``instance.''  (This usage

 can be confusing, since ``instance'' also refers to a particular

 item of class Sequence.)  For example:

 Sequence {

 String name;

 Int32 age;

 } person;

 This represents a Sequence of ``person'' records, each instance of

 which contains a name and an age:

 Fred       34

 Ralph      23

 Andrea     29

 ...

 A Sequence can be arbitrarily long, which is to say that its

 length is not part of its declaration.  A Sequence can contain

 other Sequences:

 Sequence {

 String name;

 Int32 age;

 Sequence {

 String friend;

 } friend_list;

 } person;

 This is still represented as a single table, but each row contains

 the elements of both the main Sequence and the nested one:

 Fred       34     Norman

 Fred       34     Andrea

 Fred       34     Ralph

 Fred       34     Lisa

 Ralph      23     Norman

 Ralph      23     Andrea

 Ralph      23     Lisa

 Ralph      23     Marth

 Ralph      23     Throckmorton

 Ralph      23     Helga

 Ralph      23     Millicent

 Andrea     29     Ralph

 Andrea     29     Natasha

 Andrea     29     Norman

 ...        ..     ...

 Internally, the Sequence is represented by a vector of vectors. The

 members of the outer vector are the members of the Sequence. This

 includes the nested Sequences, as in the above example.

 NB: Note that in the past this class had a different behavior. It held

 only one row at a time and the deserialize(...) method had to be called

 from within a loop. This is no longer true. Now the

 deserailize(...) method should be called once and will read the entire

 sequence's values from the server. All the values are now stored in an

 instance of Sequence, not just a single row's.

 Because the length of a Sequence is indeterminate, there are

 changes to the behavior of the functions to read this class of

 data.  The <tt>read()</tt> function for Sequence must be written so that

 successive calls return values for successive rows of the Sequence.

 Similar to a C structure, you refer to members of Sequence

 elements with a ``.'' notation.  For example, if the Sequence has

 a member Sequence called ``Tom'' and Tom has a member Float32

 called ``shoe_size'', you can refer to Tom's shoe size as

 ``Tom.shoe_size''.

 @note This class contains the 'logic' for both the server- and client-side

 behavior. The field \e d_values is used by the client-side methods to store

 the entire Sequence. On the server-side, the read() method uses an underlying

 data system to read one row of data values which are then serialized using the

 serialize() methods of each variable.

 @todo Add an isEmpty() method which returns true if the Sequence is

 empty. This should work before and after calling deserialize().

 @brief Holds a sequence. */

class Sequence: public Constructor

{

private:

    // This holds the values read off the wire. Values are stored in

    // instances of BaseTypeRow objects which hold instances of BaseType.

    SequenceValues d_values;

    // The number of the row that has just been deserialized. Before

    // deserialized has been called, this field is -1.

    int d_row_number;

    // If a client asks for certain rows of a sequence using the bracket

    // notation (<tt>[<start>:<stride>:<stop>]</tt>) primarily intended for

    // arrays

    // and grids, record that information in the next three fields. This

    // information can be used by the translation software. s.a. the accessor

    // and mutator methods for these members. Values of -1 indicate that

    // these have not yet been set.

    int d_starting_row_number;

    int d_row_stride;

    int d_ending_row_number;

    // Used to track if data has not already been sent.

    bool d_unsent_data;

    // Track if the Start Of Instance marker has been written. Needed to

    // properly send EOS for only the outer Sequence when a selection

    // returns an empty Sequence.

    bool d_wrote_soi;

    // This signals whether the sequence is a leaf or parent.

    bool d_leaf_sequence;

    // In a hierarchy of sequences, is this the top most?

    bool d_top_most;

    bool is_end_of_rows(int i);

    friend class SequenceTest;

protected:

    void m_duplicate(const Sequence &s);

    typedef stack<SequenceValues*> sequence_values_stack_t;

    virtual bool serialize_parent_part_one(DDS &dds, ConstraintEvaluator &eval, Marshaller &m);

    virtual void serialize_parent_part_two(DDS &dds, ConstraintEvaluator &eval, Marshaller &m);

    virtual bool serialize_leaf(DDS &dds, ConstraintEvaluator &eval, Marshaller &m, bool ce_eval);

    virtual void intern_data_private(ConstraintEvaluator &eval, DDS &dds,

            sequence_values_stack_t &sequence_values_stack);

    virtual void intern_data_for_leaf(DDS &dds, ConstraintEvaluator &eval,

            sequence_values_stack_t &sequence_values_stack);

    virtual void intern_data_parent_part_one(DDS &dds, ConstraintEvaluator &eval,

            sequence_values_stack_t &sequence_values_stack);

    virtual void intern_data_parent_part_two(DDS &dds, ConstraintEvaluator &eval,

            sequence_values_stack_t &sequence_values_stack);

public:

    Sequence(const string &n);

    Sequence(const string &n, const string &d);

    Sequence(const Sequence &rhs;;

    virtual ~Sequence();

    Sequence &operator=(const Sequence &rhs;;

    virtual BaseType *ptr_duplicate();

    virtual void clear_local_data();

    virtual void transform_to_dap4(D4Group *root, Constructor *container);

    virtual bool is_dap2_only_type();

    virtual string toString();

    virtual bool is_linear();

    virtual int length() const;

    virtual int number_of_rows() const;

    virtual bool read_row(int row, DDS &dds, ConstraintEvaluator &eval, bool ce_eval = true);

    virtual void intern_data(ConstraintEvaluator &eval, DDS &dds;;

    virtual bool serialize(ConstraintEvaluator &eval, DDS &dds, Marshaller &m, bool ce_eval = true);

    virtual bool deserialize(UnMarshaller &um, DDS *dds, bool reuse = false);

    /// Rest the row number counter

    void reset_row_number();

    // I added a second method instead of a param with a default value because I think

    // this will result only in an addition to the ABI/API, not a change. 5/16/15 jhrg

    void reset_row_number(bool recur);

    void increment_row_number(unsigned int i) { d_row_number += i; }

    int get_row_number() const { return d_row_number; }

    int get_starting_row_number();

    virtual int get_row_stride();

    virtual int get_ending_row_number();

    virtual void set_row_number_constraint(int start, int stop, int stride = 1);

    /// Get the unsent data property

    bool get_unsent_data() const

    {

        return d_unsent_data;

    }

    /// Set the unsent data property

    void set_unsent_data(bool usd)

    {

        d_unsent_data = usd;

    }

    virtual void set_value(SequenceValues &values);

    virtual SequenceValues value();

    virtual SequenceValues &value_ref();

    virtual BaseType *var_value(size_t row, const string &name);

    virtual BaseType *var_value(size_t row, size_t i);

    virtual BaseTypeRow *row_value(size_t row);

    virtual void print_one_row(ostream &out, int row, string space, bool print_row_num = false);

    virtual void print_val_by_rows(ostream &out, string space = "", bool print_decl_p = true, bool print_row_numbers =

            true);

    virtual void print_val(ostream &out, string space = "", bool print_decl_p = true);

    virtual void print_one_row(FILE *out, int row, string space, bool print_row_num = false);

    virtual void print_val_by_rows(FILE *out, string space = "", bool print_decl_p = true,

            bool print_row_numbers = true);

    virtual void print_val(FILE *out, string space = "", bool print_decl_p = true);

    virtual void set_leaf_p(bool state);

    virtual bool is_leaf_sequence();

    virtual void set_leaf_sequence(int lvl = 1);

    virtual void dump(ostream &strm) const;

};

} // namespace libdap

#endif //_sequence_h