In file Sequence.h:

class Sequence : public BaseType

Holds a sequence.

Inheritance:


Public Methods

Sequence(const string &n = "")
The Sequence constructor.
Sequence(const Sequence &rhs)
The Sequence copy constructor
virtual int length()
Returns the number of elements in a Sequence object
virtual void set_level(int lvl)
Sets the level number
virtual int level()
Returns the level number
virtual bool deserialize(XDR *source, DDS *dds, bool reuse = false)
Read one Sequence instance from the network.
bool seq_read_error()
Check for error or end of Sequence.
virtual bool read(const string &dataset, int &error)
Reads a single instance of a Sequence
virtual void add_var(BaseType *, Part p = nil)
Adds a variable to the Sequence
Pix first_var()
Returns an index to the first variable in a Sequence instance
void next_var(Pix &p)
Increments the Sequence instance
BaseType* var(Pix p)
Returns a pointer to a Sequence member
virtual void print_val(ostream &os, string space = "", bool print_decl_p = true)
Prints the first instance of the Sequence
virtual void print_all_vals(ostream& os, XDR *src, DDS *dds, string space = "", bool print_decl_p = true)
Print the entire sequence.

Inherited from BaseType:

Public Methods

virtual BaseType* ptr_duplicate()
string name() const
void set_name(const string &n)
Type type() const
void set_type(const Type &t)
string type_name() const
bool is_simple_type()
bool is_vector_type()
bool is_constructor_type()
virtual int element_count(bool leaves = false)
bool synthesized_p()
void set_synthesized_p(bool state)
bool read_p()
virtual void set_read_p(bool state)
bool send_p()
virtual void set_send_p(bool state)
xdrproc_t xdr_coder()
virtual unsigned int width()
virtual unsigned int buf2val(void **val)
virtual unsigned int val2buf(void *val, bool reuse = false)
virtual bool serialize(const string &dataset, DDS &dds, XDR *sink, bool ce_eval = true)
virtual void print_decl(ostream &os, string space = " ", bool print_semi = true, bool constraint_info = false, bool constrained = false)
virtual bool check_semantics(string &msg, bool all = false)
virtual bool ops(BaseType *b, int op, const string &dataset)

Documentation

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: \begin{verbatim} Sequence { String name; Int32 age; } person; \end{verbatim} This represents a Sequence of ``person'' records, each instance of which contains a name and an age: \begin{verbatim} Fred 34 Ralph 23 Andrea 29 ... \end{verbatim} 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: \begin{verbatim} Sequence { String name; Int32 age; Sequence { String friend; } friend_list; } person; \end{verbatim} This is still represented as a single table, but each row contains the elements of both the main Sequence and the nested one: \begin{verbatim} 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 ... .. ... \end{verbatim} Internally, the Sequence is represented by a singly-linked list. The members of this list are the members of a single Sequence instance: one element in the series. This includes the nested Sequences, as in the above example. The list does {\it not} contain all the elements of the Sequence. You can think of it as containing a single row. Each Sequence also carries a ``level'' number. This can be used to good effect with some data access APIs (such as JGOFS) to record the level of nested Sequences. The top-level Sequence is Level 0, and any Sequences it contains would be Level 1. Any Sequences contained by those Level 1 Sequences would be at Level 2, and so on. The class contains read and set functions for this datum. Because the length of a Sequence is indeterminate, there are changes to the behavior of the functions to read this class of data. The #read()# function for a Sequence is designed to be called repeatedly, each time returning the next item in the Sequence. Similarly, the #deserialize()# function is here meant to be called repeatedly until the end of the Sequence is reached. 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''.
Sequence(const string &n = "")
The Sequence constructor requires only the name of the variable to be created. The name may be omitted, which will create a nameless variable. This may be adequate for some applications.
Parameters:
n - A string containing the name of the variable to be created.

Sequence(const Sequence &rhs)
The Sequence copy constructor

virtual int length()
Returns the number of elements in a Sequence object. Note that this is {\it not} the number of items in a row, but the number of rows in the complete sequence object. To be meaningful, this must be computed after constraint expresseion (CE) evaluation. The purpose of this function is to facilitate translations between Sequence objects and Array objects, particularly when the Sequence is too large to be transferred from the server to the client in its entirety. This function, to be useful, must be specialized for the API and data format in use.
Returns:
The base implentation returns -1, indicating that the length is not known. Sub-classes specific to a particular API will have a more complete implementation.

virtual void set_level(int lvl)
Sets the level number

virtual int level()
Returns the level number

virtual bool deserialize(XDR *source, DDS *dds, bool reuse = false)
Deserialize (read from the network) one instance of the current sequence. The information read is sorted into the sequence instance variables.
Returns:
TRUE if more instances remain to be read, FALSE if this is the last instance {\it or} if there was an error reading the instance. In the latter case, check the value of #seq_read_error()#.

bool seq_read_error()
Was there an error reading the sequence? This function is called after a call to #deserialize()# returns FALSE, implying {\it either} an error condition or the end of the Sequence. The return from this function clears up the difference.
Returns:
This function will return TRUE if either the xdr function returned an error or the end of instance/sequence marker could not be read. If FALSE, the read error indicates the end of the sequence.

virtual bool read(const string &dataset, int &error)
Reads a single instance of a Sequence
Returns:
TRUE on success, FALSE on failure, {\it or} the end of the Sequence.

virtual void add_var(BaseType *, Part p = nil)
Adds a variable to the Sequence. Remember that if you wish to add a member to a nested Sequence, you must use the #add_var()# of that Sequence. This means that variable names need not be unique among a set of nested Sequences.

Pix first_var()
Returns an index to the first variable in a Sequence instance. This corresponds to the item in the first column of the table the Sequence represents. It is not the first row of the table.

void next_var(Pix &p)
Increments the Sequence instance. This returns a pointer to the next ``column'' in the Sequence, not the next row.

BaseType* var(Pix p)
Returns a pointer to a Sequence member. This may be another Sequence.

virtual void print_val(ostream &os, string space = "", bool print_decl_p = true)
Prints the first instance of the Sequence.
See Also:
Sequence::print_all_vals

virtual void print_all_vals(ostream& os, XDR *src, DDS *dds, string space = "", bool print_decl_p = true)
Prints a formatted version of an entire Sequence (all rows, all columns), including nested Sequences. This is meant to be used on the client side of a DODS connection, and the source of the Sequence data to be printed is specified with an XDR pointer.
Parameters:
os - The output stream on which to print the Sequence.
src - The external source from which the data is to come. This is passed to #deserialize()#.
dds - The Data Descriptor Structure object corresponding to this dataset. See {\it The DODS User Manual} for information about this structure. This would have been received from the server in an earlier transmission.
space - The leading spaces of the output.
print_del_p - If TRUE, prints the declaration of the Sequence as well as its data.


This class has no child classes.

alphabetic index hierarchy of classes


generated by doc++