PlotFile Class Reference

The PlotFile supports loading of data series from a CSV style text file. More...

#include <plotfile.h>

Public Types
enum	OptionFlag { OptUseLocale = (1 << 0) }
	Enumeration of option flags used to control file loading. More...

Public Member Functions
	PlotFile (const QString &fileName, unsigned options=0)
	Create a plot file opening fileName. More...
	~PlotFile ()
	Destructor.
bool	isOpen () const
	Returns true if a file is currently open. More...
qint64	fileSize () const
	Returns the overall file size in bytes. More...
qint64	filePos () const
	Returns the current buffered byte position in the file. More...
qint64	streamPos () const
	Returns the current byte position in the stream. More...
void	streamSeek (qint64 pos)
	Sets the stream position to pos. More...
bool	readLine ()
	Reads the next line from the file, caching it. More...
bool	generateHeadings (QStringList &headings)
	Generates headings for the plot file. More...
const QString &	currentLine () const
	Returns the last line read from the file (after readLine()). More...
void	dataLine (std::vector< double > &data)
	Converts the currently cached line into double precision data values. More...

Static Public Member Functions
static void	dataLine (QString &line, std::vector< double > &data, bool useSystemLocale)
	A static implementation of dataLine() above, supporting generalised parsing of data text. More...

Protected Attributes
QFile	_file
	The file object.
QTextStream	_stream
	Stream wrapping the file object.
QString	_line
	Last read line (readLine()).
unsigned	_options
	Option flags.

Detailed Description

The PlotFile supports loading of data series from a CSV style text file.

While data files are CSV like, they can be whitespace delimited. Any number of whitespace characters may separate data values.

The supported file format details are:

• Each line is delimited into distinct sample quantities, where each quantity evolves overtime with one sample per line.
• Each line represents a discrete sample point.
• The first line is an optional line of column names or headings.
• The file may contain a time stamp or time value quantity.
• Each line must contain the same number of items.

The presence or absence of headings is inferred by checking if the first line can be split and converted into numeric values. The line is deemed to be headings should that fail. If there is no heading line, then heading names are generated as "Column 1", "Column 2", etc.

Heading parsing and delimiting differs from data line parsing. Heading names may contain spaces, with heading parsing using the following rules.

• Try parse headings with the same delimiters as data (whitespace and comma).
• Parse the next line (first data line) and validate the number of items on each line. We stop if these two match and generate the headings from the first line as is.
• Otherwise:
  1. Allow tab-delimited, but not space delimited columns.
  2. Allow general whitespace delimiting, but extend names to include any bracketed text which follows it. E.g., "speed (m/s)" is treated as a single heading name.

Unicode formats are supported through Qt's QTextStream class.

Member Enumeration Documentation

enum PlotFile::OptionFlag

Enumeration of option flags used to control file loading.

Enumerator
OptUseLocale	Use the current QLocale for parsing rather than the C locale. The system locale may be set such that the digit separator is '.' and the decimal separator is ',' as in much of Europe.

Constructor & Destructor Documentation

PlotFile::PlotFile	(	const QString &	fileName,
		unsigned	options = 0
	)

Create a plot file opening fileName.

Parameters

fileName	The file to open.
options	Combination of OptionFlag values to load with.

Member Function Documentation

const QString& PlotFile::currentLine

(

)

const

Returns the last line read from the file (after readLine()).

Returns

The currently cached line as a QString.

void PlotFile::dataLine

(

std::vector< double > &

data

)

Converts the currently cached line into double precision data values.

The current line is split by the delimiters and data populated with the data items. The data array is resize to the number of data items in the current line. The number of items should be consistent line to line.

Uses a std::vector because QVector releases memory on clear().

Parameters

data	Populated with the data items of the current line.

static void PlotFile::dataLine ( QString &  line, std::vector< double > &  data, bool  useSystemLocale  )

static

A static implementation of dataLine() above, supporting generalised parsing of data text.

Parsing has been optimised for best data conversion speed.

Uses a std::vector because QVector releases memory on clear().

Parameters

line	The data line to parse. Mutable to maximise parsing performance. The content is only temporarily modified and restored before exiting.
data	Populated with the loaded data. The element count is set to the number of items parsed from line.
useSystemLocale	Use the system locale for parsing (true), or the C locale (false).

qint64 PlotFile::filePos

(

)

const

Returns the current buffered byte position in the file.

This can be ahead of the stream as the stream is buffered, but is much faster than streamPos(). Do not use the result with as the buffered position is not the read position.

Returns

The file position.

qint64 PlotFile::fileSize

(

)

const

Returns the overall file size in bytes.

Returns

The file size in bytes.

bool PlotFile::generateHeadings

(

QStringList &

headings

)

Generates headings for the plot file.

Headings are read from the first line if possible.

Headings are deduces from the first line of the file. Headings may be delimited by either tabs, commas or spaces. Headings may contain spaces when:

• Headings are tab or comma delimited
• Headings are of the form "heading (unit)". Heading and unit are arbitrary strings, but are intended as they are named.

If no headings line is present, then this method counts columns in the first line and generates headings as "Column #" where # is the one base column index.

The file position is first reset to the start of the file and is left at the first data line (possibly the start of the file).

Parameters

headings

Populated with headings

Returns

False if no data was read from the file.

bool PlotFile::isOpen

(

)

const

Returns true if a file is currently open.

Returns

True if the file is open for reading.

bool PlotFile::readLine

(

)

Reads the next line from the file, caching it.

Returns

True if another line was successfully read, false at end of file.

qint64 PlotFile::streamPos

(

)

const

Returns the current byte position in the stream.

This can be a slow operation as the stream may need to re-buffer to detemine a valid position. Use filePos() in tight loops, but use streamPos() when there is a need to reset to the current file position with streamSeek().

void PlotFile::streamSeek

(

qint64

pos

)

Sets the stream position to pos.

Do not use with results from filePos(), preferring streamPos().

Parameters

pos	The position to seek.

---

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

• plotfile.h