Extended streams

Useful functions

A few useful functions are available:

• exists tests whether a file exists.
• file_size returns the length (in bytes) of a file.
• stream_size returns the length (in bytes) of a stream.
• is_empty tests whether a stream is empty.
• has_element tests whether a stream has still elements to be extracted with operator<<.

Class ExtStream

Class ExtStream derives from ifstream and brings extended features to input streams. Main features may be:

• The file name is stored. The method GetFileName returns it.
• Comment lines can be discarded when the stream is read. The characters that denote a comment line may be chosen.
• Delimiters are defined so that one may extract elements one by one.
• It is possible to search for a given element in the stream. See the method Find.
• One may search a the value of a given field in the stream. Refer to GetValue and PeekValue.

Example

file.dat:

# France exports and imports (%) in 2003.
# Source: INSEE.

# Country, exports, imports (annual means).
Germany: 14.9, 17.4
Spain: 10.2, 7.6
UK: 9.7, 6.8
Italy: 9.3, 9.3
B/L: 8.3, 7.4 # Economic union Belgium/Luxembourg
USA: 6.9, 6.5

Number of countries: 6

read.cpp:

#include "Talos.hxx"
using namespace Talos;

int main()
{
  ExtStream file("file.dat");

  cout << "Reading " << file.GetFileName() << "..." << endl;

  // Searches for the number of countries.
  file.Find("countries");
  int N=6;
  file.GetNumber(N);
  cout << "Number of countries: " << N << "." << endl;
  
  // Move to the beginning.
  file.Rewind();

  for (int i = 0; i < N; i++)
    {
      cout << file.GetElement();
      cout << '\t' << file.GetNumber();
      cout << '\t' << file.GetNumber() << endl;
    }

  return 0;
}

Result:

Reading file.dat...
Number of countries: 6.
Germany 14.9    17.4
Spain   10.2    7.6
UK      9.7     6.8
Italy   9.3     9.3
B/L     8.3     7.4
USA     6.9     6.5

makefile (launch make read):

CC	=	g++
INCPATH	=	Talos # Put the path to Talos.
LINK	=	g++

TARGETS	=	read read_config read_configs exceptions dates

all: $(TARGETS)

$(TARGETS): % : %.o
	$(LINK) -o $@ $<

%.o : %.cpp
	$(CC) -I$(INCPATH) -c -o $@ $<

clean:
	rm -f $(TARGETS) $(TARGETS:%=%.o)

Comments

ExtStream mainly extracts elements from the stream. An element is a string surrounded by delimiters. By default, delimiters are spaces, tabulations and line breaks. So, by default, elements are simply words. GetElement is used to extract elements, as shown in the previous example.

The method Find searches for an element. It means that, if spaces are delimiters (default), one is only able to search for words. As a consequence, in the previous example, files.Find("Number of countries") would have failed.

GetNumber searches for the first element that is also a number.

Exceptions

A exception may be thrown if:

• GetValue is unable to find the element associated with a given value in the stream.
• Find fails.

The object thrown is a string that explains what happened. One may use the macros TRY and END to catch exceptions:

exceptions.cpp (launch make exceptions):

#include "Talos.hxx"
using namespace Talos;

int main()
{
  TRY; // Opens a 'try' block.

  ExtStream file("file.dat");

  file.Find("Finland");

  END; // Catches exceptions.

  return 0;
}

Result:

Error in ExtStream::Find: "Finland" not found in "file.dat".

END also returns 1. Here is its definition:

#define END \
}\
catch (std::exception& Err)\
{\
cout << "C++ exception: " << Err.what() << endl;\
return 1;\
}\
catch (std::string& str)\
{\
cout << str << endl;\
return 1;\
}\
catch (const char* str)\
{\
cout << str << endl;\
return 1;\
}\
catch(...)\
{\
cout << "Unknown exception..." <<endl;\
return 1;\
}