Diffpack Documentation

---

              Search  

---

Is Class Reference

generalized input class, covers streams, files, strings etc. More...

#include <IsOs.h>

List of all members.

Public Methods
	Is ()
	Is (const char *s)
	Is (const String &s)
	Is (istream &is)
	Is (ifstream &ifs)
	Is (const Is &is)
	Is (const String &filename, enum FileMode mode)
	Is (const String &filename, enum Format_type format, enum FileMode mode, bool xdr_format=true)
	~Is ()
void	rebind (const char *s)
void	rebind (const String &s)
void	rebind (istream &is)
void	rebind (ifstream &ifs)
void	rebind (const Is &is)
void	rebind (const String &filename, enum FileMode mode)
void	rebind (const String &filename, enum Format_type format, enum FileMode mode, bool xdr_format=true)
void	operator= (const Is &is)
void	init ()
bool	ok () const
Is_base*	operator-> ()
Is_base*	getPtr ()
Is_base&	getRef ()
bool	isString ()
String	getString ()
Friends
Is&	operator>> (Is &is, double &a)
Is&	operator>> (Is &is, float &a)
Is&	operator>> (Is &is, int &i)
Is&	operator>> (Is &is, long int &i)
Is&	operator>> (Is &is, char &c)
Is&	operator>> (Is &is, char *s)
Is&	operator>> (Is &is, String &s)
Is&	operator>> (Is &is, const char *s)

---

Detailed Description

generalized input class, covers streams, files, strings etc.

NAME: Is - generalized input class, covers streams, files, strings etc

DESCRIPTION:

The classes "Is" (for input) and "Os" (for output) represent generalizations of input and output in C++ programs. Instead of using the standard "istream" and "ostream" classes one can use "Is" and "Os". The advantages are:

1) more advanced reading and writing procedures, including command reading,

2) a generalized interface to various sources of IO, for example iostreams, files, strings, binary xdr-format files,

3) binary or ascii format is hidden for the programmer. Hence, if a programmer makes class "X" and equips it with "X scan(Is)" and "X print(Os)" functions, the class can be initialized easily by a string, by an istream, by a file, the input/output can be in either binary or ascii format and so on.

The code in the print and scan functions are as simple as, or simpler than, the corresponding code employing the standard "iostream" package. Moreover, the code in for example "X scan(Is)" is independent of the input source as long as this source is represented by an "Is" object. Recall that ordinary C++ programming requires different code for different I/O sources: Reading from "istream" requires another syntax than reading from a string. There are automatic type conversion from standard sources, such as "istream", "ostream", "ifstream", "ofstream", "String" and "char*", to "Is" and "Os". Thus one can call "X scan(cin)" or "X::scan(""a string...."")". The call "X scan(""FILE=t1.cp0"")" causes the file "t1.cp0" to be the input source. Read appendix B.3.3 in H P Langtangen "Computatational Partial Differential Equations; Numerical Methods and Diffpack Programming" for more information on "Is" and "Os".

In "operator<<" and "operator>>" one should use references for the "Is" and "Os" arguments. In all other cases, one is recommended to use ""pass by value"", and not ""pass by reference"", as the former type allows automatic type conversion. For example, "print(Os&)" will give rise to a warning message if it is called by "print(cout)", since then a temporary argument is made ("Os(cout)"), but any modifications of this argument in "print" will not be visible because the "Os" object is temporary. If the "Os&" is declared as "const" "Os&", no warning is issued because modifications are then illegal. Likewise, if "Os" is passed by value, modifications are not meant to be seen outside the "print" function.

The standard input and output sources, "cin" and "cout" in C++, are redefined in the "Is/Os" library: "s_o" is standard output, "s_i" is standard input, and "s_e" is standard error. It is recommended to use these standard I/O sources since they offer greater flexibility than "cin", "cout" and "cerr", especially with respect to future improvements of the "Diffpack" I/O classes. There is full correspondance between, e.g., "cout" and "s_o". In fact, "s_o" is declared by the constructor "Os": "s_o(cout)". The other standard sources "s_i" and "s_e" are declared likewise. Thus one can mix "Is" and "Os" with the original C++ sources, e.g., output to "s_o" and "cout" can be mixed without achieving inconsistent results. Note that a mixing of "s_o" and the C "printf" function is likely to lead to inconsistent output. Avoid the use of "printf", instead one can use "Os" and the output function "oform" (see the examples). In the future, it may happen that "s_o" and "s_i" will be based on C I/O functions instead of the C++ "isotream" library.

The many examples below demonstrates in detail the use of "Is" and "Os".

Some problems are known to occur with "s_o" and "s_i" because these objects are global. Their proper initialization is carried out from the routine "initDiffpack", which must be called in the first statement of any "main". However, if there are other global objects, their constructors are called before "main" is entered, and if these construtors have some (debug) output using "s_o", an error message will occur (""This Os is not properly initialized""). For this reason: Use "cout" instead of "s_o" in output from constructors that may be called prior to the entering of "main"! And if you experience strange errors and core dump before "main" is entered, examine possible (debug) output to "s_o" in global objects. Normally, a programmer does not declare global objects - it is not recommended - and then the problems described here should never occur.

Now some information on the design of the "Is" (and "Os") class is given. The "Is" class contains a pointer to a class "Is_base". The "Is_base" hierarchy contains the implementation of the functionality offered by class "Is". A particular subclass, class "Is_istream" implements the virtual functions using the standard "istream" library. To invoke these virtual functions from an "Is" object, the overloaded "operator->" is used. The "Is" is hence a handle class (see class "Handle(Type)") but equipped with more specialized constructors for automatic type conversion of input sources.

The subclass of "Is_base" that implements the functionality when reading from files is called "Is_ifstream". This class makes use of the standard "ifstream" class. Implementation of the "Is_base" functionality in terms of the standard "istream" library is carried out by the subclass "Is_istream". Some of the features of "Is_base", such as searching from the beginning of the input source, are not readily implemented using "istream" and therefore not available in "Is_istream". This is typical for the subclasses of "Is_base": some of the virtual functions are not available in all subclasses. Usually error or warning messages are issued if one attempts to use an unimplemented functionality. If you compare the "istream" class with our "Is_istream" class you will see that a lot of the "istream" functionality is not offered by "Is_istream". This is because the "Is_istream" interface is dictated by "Is" and is common for all input sources. Special "istream" functions that have no meaning for strings or C files have not been chosen as a part of the general "Is" interface. If you know that your "Is" object is actually handling an "Is_istream" object and you would like to take advantage of special "istream" functions that are not offered by "Is", you can easily get an "istream" reference out of "Is". This is examplified below. Similary, if you know that the "Is" is actually a string, the "String" object can be made available for direct manipulation.

---

Constructor & Destructor Documentation

Is::Is ( )

The constructors take ordinary input sources as arguments and enable automatic type conversion. Input source arguments may be "istream", "ifstream", "char*" or "String". Two constructors enable reading from file and have the filename and input mode (and binary/ascii format) as arguments. Hence, to read from file you can either declare an "ifstream" object for the file or just give the filename and filemodes. In the latter case, "Is" will administer the declaration of an "Is_ifstream" object that manages the file in terms of an internal "ifstream" object. The I/O source for an "Is" object can be changed by calling the "rebind" functions. In fact, the constructors just call "rebind". Additional initialization may be a call to the member function "Is_base setFormat" for setting the format to "BINARY" or "ASCII" mode. The default is "ASCII" mode. If one has changed the format and want to reset the format to its state before last call to "setFormat", one can call "resetFormat". This is convenient if one has a source and forces the output to be in "ASCII" format, simply call "setFormat(ASCII)", perform the input, and call "resetFormat"().

Is::Is ( const char * s )

See documentation of one of the overloaded constructor.

Is::Is ( const String & s )

See documentation of one of the overloaded constructor.

Is::Is ( istream & is )

See documentation of one of the overloaded constructor.

Is::Is ( ifstream & ifs )

See documentation of one of the overloaded constructor.

Is::Is ( const Is & is )

See documentation of one of the overloaded constructor.

Is::Is ( const String & filename, enum FileMode mode )

See documentation of one of the overloaded constructor.

Is::Is ( const String & filename, enum Format_type format, enum FileMode mode, bool xdr_format = true )

See documentation of one of the overloaded constructor.

Is::~Is ( )

---

Member Function Documentation

Is_base * Is::getPtr ( ) [inline]

returns a pointer to "Is_base". This function and "getRef" are usually used when casting from an "Is" to an "Is_base" subclass in order to use e.g. "iostream" or "String" functions directly.

Is_base & Is::getRef ( ) [inline]

returns a reference to "Is_base". This function and "getRef" are usually used when casting from an "Is" to an "Is_base" subclass in order to use e.g. "iostream" or "String" functions directly.

String Is::getString ( )

if "isString" returns true, one can call "getString" to get the String that "Is" has read. The functions "isString" and "getString" has little applications when reading data. However, when writing data to strings using class "Os" these functions are very convenient for retrieving the string source.

void Is::init ( )

bool Is::isString ( )

returns a true value if the I/O source handled by "Is" is really a "String".

bool Is::ok ( ) const

determines if the "Is" object is properly initialized, that is, if it has access to an opened I/O source and is ready for reading data.

Is_base * Is::operator-> ( )

"Is_base". See class Is_base for the member function documentation of the functionality that can be accessed through this operator. (If the pointer to "Is_base" is not properly initialized, an error message is issued.)

void Is::operator= ( const Is & is )

void Is::rebind ( const String & filename, enum Format_type format, enum FileMode mode, bool xdr_format = true )

See documentation of one of the overloaded functions.

void Is::rebind ( const String & filename, enum FileMode mode )

See documentation of one of the overloaded functions.

void Is::rebind ( const Is & is )

See documentation of one of the overloaded functions.

void Is::rebind ( ifstream & ifs )

See documentation of one of the overloaded functions.

void Is::rebind ( istream & is )

See documentation of one of the overloaded functions.

void Is::rebind ( const String & s )

See documentation of one of the overloaded functions.

void Is::rebind ( const char * s )

function for attaching or changing input sources such as "istream", "ifstream", "char*" or "String". See the constructors for more information.

---

Friends And Related Function Documentation

Is & operator>> ( Is & is, const char * s ) [friend]

Is & operator>> ( Is & is, String & s ) [friend]

Is & operator>> ( Is & is, char * s ) [friend]

Is & operator>> ( Is & is, char & c ) [friend]

Is & operator>> ( Is & is, long int & i ) [friend]

Is & operator>> ( Is & is, int & i ) [friend]

Is & operator>> ( Is & is, float & a ) [friend]

Is & operator>> ( Is & is, double & a ) [friend]

---

The documentation for this class was generated from the following file:

• IsOs.h

---