A class with static functions to help deal with FITS History cards. More...

#include <FITSHistoryUtil.h>

Static Public Member Functions
static uInt	getHistoryGroup (Vector< String > &strings, String &groupType, ConstFitsKeywordList &in)
	Get the strings in the next keyword group.
static void	addHistoryGroup (FitsKeywordList &out, const std::vector< String > &strings, uInt nstrings, const String &groupType)
	Add history strings of the specified groupType to an existing FitsKeywordList.
static void	fromHISTORY (LoggerHolder &logSink, const Vector< String > &history, uInt nstrings, Bool aipsppFormat)
	Some functions to help convert between log tables and FITS HISTORY cards.
static uInt	toHISTORY (std::vector< String > &history, Bool &aipsppFormat, uInt &nstrings, uInt firstLine, const LoggerHolder &logSink)
	toHistory signals that it is done by setting nstrings to 0.

Detailed Description

A class with static functions to help deal with FITS History cards.

Intended use:

Public interface

Review Status

Reviewed By:: Eric Sessoms
Date Reviewed:: 2002/08/19
Test programs:: tFITSHistoryUtil

Prerequisite

General knowledge of FITS, and particularly FITS keywords, is assumed.
Presumably you are using this class in conjunction with the "native" FitsKeywordList

Etymology

This is a collection of static utility functions for use with FITS HISTORY keywords.

Synopsis

Manipulate HISTORY information. FITS HISTORY cards are interconverted with String as follows:

'HISTORY ' and trailing blanks are removed from each card.
Continuation cards are CARDS that have '>' in the first line.
A string is made by concatenating the leading card and all continuation cards.

For example:

    HISTORY Every good
    HISTORY > boy deserves
    HISTORY >fudge.

Becomes the C++ String: "Every good boy deservesfudge." Note the lack of a space between deserves and fudge.

History cards are broken into groups. A group is delimited by

    HISTORY AIPS++ START TYPE
    HISTORY AIPS++ END [TYPE]

Where type might be, e.g., LOGTABLE. HISTORY cards not enclosed between START/END pairs are implicitly of type "" (i.e. the empty string). The TYPE is optional on the END statement. It is essentially a comment.

At present, START/END pairs cannot be nested, although this would be an obvious extension.

Motivation

The FitsKeywordList class can be somewhat tedious to use, as it deals with, e.g., char* pointers rather than Strings. This class makes it easy to interconvert between the HISTORY keywords and a Vector of related history information.

Definition at line 107 of file FITSHistoryUtil.h.

Member Function Documentation

static void casa::FITSHistoryUtil::addHistoryGroup	(	FitsKeywordList &	out,
		const std::vector< String > &	strings,
		uInt	nstrings,
		const String &	groupType
	)		`[static]`

Add history strings of the specified groupType to an existing FitsKeywordList.

This function will split long strings across HISTORY cards and set up the group START/END keywords if necessary. nstrings must be specified because strings might have come from something like getHistoryGroup, i.e. it might have garbage entries at the end. The strings may have embedded newlines, but they must have no other non-printable characters.

static void casa::FITSHistoryUtil::fromHISTORY	(	LoggerHolder &	logSink,
		const Vector< String > &	history,
		uInt	nstrings,
		Bool	aipsppFormat
	)		`[static]`

Some functions to help convert between log tables and FITS HISTORY cards.

It is intended that these functions will only be used by the functions in classes like ImageFITSConverter.

Table rows are in AIPS++ format if they have a valid time and priority, otherwise they are in the standard FITS HISTORY format. The history lines are processed by contiguous groups where all lines in that group are either in AIPS++ or HISTORY format. Note that history.nelements() might be greater than nstrings for efficiency (i.e. the history vector will not be shrunk unnecessarily).

Note that these functions are in a separate .cc file so that if they are not used the table function is not linked in if other functions in this class are used.

The strings are assumed to be from or going to the get/addHistoryGroup functions, i.e. strings that span multiple lines are joined, AIPS++ START/END cards are stripped, etc.

The AIPS++ format is: the first line DATE PRIORITY [SRCCODE='xxx'] [OBJID='xxx'] and the second lins is the message. These entries are in an AIPS++ START LOGTABLE history sequence.

static uInt casa::FITSHistoryUtil::getHistoryGroup	(	Vector< String > &	strings,
		String &	groupType,
		ConstFitsKeywordList &	in
	)		`[static]`

Get the strings in the next keyword group.

Returns the number of strings found (0 when no history remains). If necessary, strings will be resized larger. in must be set to the first card before the first call to getHistoryGroup, and should not be reset until all history is extracted (otherwise the same history will be extracted more than once). This method can be used as follows:

        uInt n;
        Vector<String> group;
        String type;
        ConstFITSKeywordList keys(...);
        ..\.
        keys.first();
        while ((n = FITSHistoryUtil::getHistoryGroup(group, type, keys)) != 0) {
            ... process this history group
        }

strings will have no embedded newlines. strings is not resized if it is more than large enough to hold the number of history cards in the group (i.e. there may be values at the end of strings which are not part of the requested group.

static uInt casa::FITSHistoryUtil::toHISTORY	(	std::vector< String > &	history,
		Bool &	aipsppFormat,
		uInt &	nstrings,
		uInt	firstLine,
		const LoggerHolder &	logSink
	)		`[static]`

toHistory signals that it is done by setting nstrings to 0.

The returned value is firstLine + n_lines_read, i.e. use it as firstLine in your next call.

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

casacore/fits/FITS/FITSHistoryUtil.h

Static Public Member Functions