.\" ident	@(#)G2++:g2++lib/man/typed_io.3	3.2
.\"
.\" C++ Standard Components, Release 3.0.
.\"
.\" Copyright (c) 1991, 1992 AT&T and UNIX System Laboratories, Inc.
.\" Copyright (c) 1988, 1989, 1990 AT&T.  All Rights Reserved.
.\"
.\" THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AT&T and UNIX System
.\" Laboratories, Inc.  The copyright notice above does not evidence
.\" any actual or intended publication of such source code.
.\" 
.TH \f3typed_io\fP \f3G2++(3C++)\fP " "
.SH NAME
typed_io \- G2++ typed input/output
.SH "SYNOPSIS OF header file generated by \f3g2++comp(1C++)\f1"
.Bf

#include <g2++.h>
#include <Vblock.h>        // See \f3Vblock(.)\fP
#include <String.h>

class istream;   // see \f3iostream(3C++)\fP
class ostream;   // see \f3iostream(3C++)\fP

// For each record type defined in
// the corresponding .g file:

    typedef \f2type_specifier\fP \*(gt;

    istream& operator>>(istream& is,\*(gt& t);
    ostream& operator<<(ostream& os,const \*(gt& t);

.Be
.SH DESCRIPTION
The G2++ compiler, \f3g2++comp(1C++)\f1, 
must be used prior to compiling client code that
uses G2++ typed input/output routines.
\f3g2++comp(1C++)\f1 reads a collection of G2++ 
record definitions from one or more \f3.g\f1 files 
(each definition is itself a G2++ record) 
and writes a pair of files, one \f3.h\f1 file and 
one \f3.c\f1 file, for each \f3.g\f1 file.
The \f3.c\f1 file must be compiled
and linked with the rest of the application.
The \f3.h\f1 file must be included by client programs.
The \f3.h\f1 file contains a set of three declarations
for each record type defined in the \f3.g\f1 file.
The three declarations are:
.IP "\f4typedef \f2type_specifier\fP \*(gt;\f1"
Used by the client to declare 
variables suitable as sources or targets of the typed
I/O operators.  \*(gt is the upper case version
of the record name in the \f3.g\f1 file.
For simple records (records with no indented groups),
\f2type_specifier\f1 will be a simple type;
otherwise, \f2type_specifier\f1 will be a structure type.
.IP "\f4istream& operator>>(istream& is,\*(gt& t);\f1"
Stream extraction operator.
Scans \f4istream is\f1 until it encounters
a G2++ record of type \*(gt and maps the
record contents into \f4t\f1.
If a record of type \*(gt cannot be 
found before the stream is exhausted,
the stream will test as null after the operation and
the contents of \f4t\f1 will be undefined.
The mapping obeys the following rules 
(see \f3G2++(4C++)\f1 for definitions of italicized terms):
.RS
\(bu\ A \f2group\f1 with an unknown \f2name\f1 
will be ignored.
.br
\(bu\ If a \f2group\f1 is missing,
each member of the corresponding \f2group\f1 
will be assigned the null value of its respective type.
.br
\(bu\ If a \f2value\f1 has been defined as a \f2fixed
size string\f1, characters in excess of the defined size
will be ignored.
.br
\(bu\ If a \f2value\f1 has been defined as a \f2fixed
size array\f1,
elements with an out-of-bounds \f2index\f1 
will be ignored.
.br
\(bu\ An out-of-order \f2name\f1 will be recognized 
as long as it occurs within its proper \f2group\f1.
.br
\(bu\ A \f2string\f1 is terminated by 
the first non-printable character.
If the remaining characters of the \f2string\f1 
still cannot be converted to a value of its defined type, 
the null value for that type will 
be assigned to the corresponding structure member.
Otherwise, the \f2string\f1 will be converted to the
appropriate type and assigned to the corresponding
structure member.  
.RE
.IP "\f4ostream& operator<<(ostream& os,const \*(gt& t);\f1"
Stream insertion operator.
Maps the values in \f4t\f1 into a G2++ record
and inserts the record into \f4os\f1.
The mapping obeys the following rules:
.RS
\(bu Only members containing non-null strings or 
non-zero integers will be inserted
.br
\(bu Fixed size strings and arrays 
will be truncated if they exceed their defined 
sizes.
.RE
.SH EXAMPLE
Using \f3g2++comp(1C++)\f1 to 
compile the following \f3person.g\f1 file:
.Bf

        Time    USER
                .header Time.h
                .header Timeio.h
                .null   Time::MIN

        person
                id      *
                age     SHORT
                b_day   Time
                hobbies
                        *       *

.Be
produces the following \f3person.h\f1 file:
.Bf

        #ifndef PERSONH
        #define PERSONH

        #include <g2++.h>
        #include <Vblock.h>
        #include <String.h>
        #include "Time.h"
        #include "Timeio.h"

        class istream;
        class ostream;

        typedef struct PERSON{
                String  id;
                short   age;
                Time    b_day;
                Vblock<String> hobbies;  \f2see Vblock(.)\fP
                PERSON();
        }PERSON;

        istream& operator>>(istream& is, PERSON& x);
        ostream& operator<<(ostream& os, const PERSON& x);

        #endif


.Be
The following "batch" update program adds 1 
to the age of every person whose birthday is today.
.Bf
        #include "person.h"
        #include <time.h>
        #include <Time.h>

        main(){
            PERSON p;
            Time today = make_time(time(0));

            while(cin >> p){
                if(p.b_day==today){
                     p.age += 1;
                }
                cout << p;
            }
        }
.Be
.SH NOTES
Applications without \f2a priori\f1 knowledge
of record types must use \f2untyped I/O\f1 (see
\f3untyped_io(.)\f1.
.SH SEE ALSO
.Bf
\f3G2++(4C++)\f1
\f3g2++comp(1C++)\f1
\f3intro(.)\f1
\f3String(3C++)\f1
\f3untyped_io(.)\f1
\f3Vblock(.)\f1
.Be