casacore
FITSHistoryUtil.h
Go to the documentation of this file.
1 //# FITSHistoryUtil.h: Class of static functions to help with FITS History cards.
2 //# Copyright (C) 2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //#
27 //# $Id$
28 
29 
30 #ifndef FITS_FITSHISTORYUTIL_H
31 #define FITS_FITSHISTORYUTIL_H
32 
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/ArrayFwd.h>
35 #include <vector>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 class ConstFitsKeywordList;
40 class FitsKeywordList;
41 class String;
42 class LoggerHolder;
43 
44 // <summary>
45 // A class with static functions to help deal with FITS History cards.
46 // </summary>
47 
48 // <use visibility=export>
49 
50 // <reviewed reviewer="Eric Sessoms" date="2002/08/19" tests="tFITSHistoryUtil.cc">
51 // </reviewed>
52 
53 // <prerequisite>
54 // <li> General knowledge of FITS, and particularly FITS keywords, is
55 // assumed.
56 // <li> Presumably you are using this class in conjunction
57 // with the "native"
58 // <linkto class=FitsKeywordList>FitsKeywordList</linkto>
59 // </prerequisite>
60 //
61 // <etymology>
62 // This is a collection of static utility functions for use with FITS
63 // HISTORY keywords.
64 // </etymology>
65 //
66 // <synopsis>
67 // Manipulate HISTORY information. FITS HISTORY cards are interconverted with
68 // String as follows:
69 // <ul>
70 // <li> 'HISTORY ' and trailing blanks are removed from each card.
71 // <li> Continuation cards are CARDS that have '>' in the first line.
72 // <li> A string is made by concatenating the leading card and all continuation
73 // cards.
74 // </ul>
75 // For example:
76 // <srcblock>
77 // HISTORY Every good
78 // HISTORY > boy deserves
79 // HISTORY >fudge.
80 // </srcblock>
81 // Becomes the C++ String: "Every good boy deservesfudge." Note the lack of
82 // a space between deserves and fudge.
83 //
84 // History cards are broken into groups. A group is delimited by
85 // <srcblock>
86 // HISTORY AIPS++ START TYPE
87 // HISTORY AIPS++ END [TYPE]
88 // </srcblock>
89 // Where type might be, e.g., LOGTABLE. HISTORY cards not enclosed between
90 // START/END pairs are implicitly of type "" (i.e. the empty string).
91 // The TYPE is optional on the END statement. It is essentially a comment.
92 //
93 // At present, START/END pairs cannot be nested, although this would be an
94 // obvious extension.
95 // </synopsis>
96 //
97 // <motivation>
98 // The FitsKeywordList class can be somewhat tedious to use, as it deals with,
99 // e.g., char* pointers rather than Strings. This class makes it easy to
100 // interconvert between the HISTORY keywords and a Vector of related history
101 // information.
102 // </motivation>
103 //
104 
106 {
107 public:
108  // Get the strings in the next keyword group. Returns the number of
109  // strings found (0 when no history remains). If necessary, strings will be
110  // resized larger. in must be set to the first card before the first call to
111  // getHistoryGroup, and should not be reset until all history is extracted
112  // (otherwise the same history will be extracted more than once). This method
113  // can be used as follows:
114  // <srcBlock>
115  // uInt n;
116  // Vector<String> group;
117  // String type;
118  // ConstFITSKeywordList keys(...);
119  // ...
120  // keys.first();
121  // while ((n = FITSHistoryUtil::getHistoryGroup(group, type, keys)) != 0) {
122  // ... process this history group
123  // }
124  // </srcBlock>
125  // strings will have no embedded newlines. strings is not resized if it is more
126  // than large enough to hold the number of history cards in the group (i.e. there
127  // may be values at the end of strings which are not part of the requested group.
128  static uInt getHistoryGroup(Vector<String> &strings, String &groupType,
130 
131  // Add history strings of the specified groupType to an existing FitsKeywordList.
132  // This function will split long strings across HISTORY cards and set
133  // up the group START/END keywords if necessary. nstrings must be specified
134  // because strings might have come from something like getHistoryGroup, i.e.
135  // it might have garbage entries at the end. The strings may have embedded
136  // newlines, but they must have no other non-printable characters.
138  const std::vector<String> &strings,
139  uInt nstrings, const String &groupType);
140 
141  // Some functions to help convert between log tables and FITS HISTORY cards.
142  // It is intended that these functions will only be used by the functions in
143  // classes like ImageFITSConverter.
144  //
145  // Table rows are in Casacore format if they have a valid time and priority,
146  // otherwise they are in the standard FITS HISTORY format. The history lines
147  // are processed by contiguous groups where all lines in that group are
148  // either in Casacore or HISTORY format. Note that history.nelements() might
149  // be greater than nstrings for efficiency (i.e. the history vector will
150  // not be shrunk unnecessarily).
151  //
152  // Note that these functions are in a separate .cc file so that if they
153  // are not used the table function is not linked in if other functions in
154  // this class are used.
155  //
156  // The strings are assumed to be from or going to the get/addHistoryGroup
157  // functions, i.e. strings that span multiple lines are joined,
158  // AIPS++ START/END cards are stripped, etc.
159  //
160  // The Casacore format is: the first line DATE PRIORITY [SRCCODE='xxx']
161  // [OBJID='xxx'] and the second lins is the message. These entries are in
162  // an AIPS++ START LOGTABLE history sequence.
163  // <group>
164  static void fromHISTORY(LoggerHolder& logSink,
165  const Vector<String>& history,
166  uInt nstrings, Bool aipsppFormat);
167 
168  // toHistory signals that it is done by setting nstrings to 0.
169  // The returned value is firstLine + n_lines_read, i.e. use
170  // it as firstLine in your next call.
171  static uInt toHISTORY(std::vector<String>& history, Bool& aipsppFormat,
172  uInt& nstrings, uInt firstLine,
173  const LoggerHolder& logSink);
174  // </group>
175 
176 };
177 
178 
179 } //# NAMESPACE CASACORE - END
180 
181 #endif
list of read-only FITS keywords
Definition: fits.h:951
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 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 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.
static uInt getHistoryGroup(Vector< String > &strings, String &groupType, ConstFitsKeywordList &in)
Get the strings in the next keyword group.
linked list of FITS keywords
Definition: fits.h:737
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42