casa::MVTime

casa::MVTime Class Reference
[Quanta]

#include <MVTime.h>

Collaboration diagram for casa::MVTime:

[legend]List of all members.

Detailed Description

Class to handle date/time type conversions and I/O.

Intended use:

Part of API

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25
Test programs:: tMeasure

Prerequisite

Quantum
MVAngle
ISO8601 standard on dates and time.

Etymology

From Measure, Value and Time

Synopsis

An MVTime is a simple Double for date/time conversions and I/O. Its internal value is in MJD. For high precision the MVEpoch class should be used.
It can be constructed from a Double (in which case MJD are assumed), or from a Quantity (Quantum<Double>). Quantities must be in either angle or time units, or from a MVEpoch
The OS/Time class can be used as both input and output. An MVTime(Time) constructor exists, as well as a Time getTime().
Construction from year, month, day is also supported. Caution: Dates before 16 Oct 1582 are considered to be Julian, rather than Gregorian It has an automatic conversion to Double, so all standard mathematical operations can operate on it.
The class has a number of special functions to obtain data:

Double day() will return value in days
Double hour() will return value in hours
Double minute() will return value in minutes
Double second() will return value in seconds
Quantity get() will return days
Quantity get(Unit) will return in specified units (angle(in which case it will be between -pi and +pi) or time)
uInt weekday() will return day of week (1=Mon, 7=Sun)
uInt month() will return month (1=Jan)
Int year() will return year
uInt monthday() will return day of the month
uInt yearday() will return day of year (Jan01 = 1)
uInt yearweek() will return week of year (week containing Jan04 = 1, week start on Monday). The week before the first week will be called 0, contrary to standard practice (week 53/52 of previous year).
Int ymd() will return yyyymmdd as a single number
const String &dayName() will return name of day (Sun, Mon, Tue, Wed, Thu, Fri, Sat)
const String &monthName() will retrun name of Month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec)

Output formatting is done with the << statement, with the following rules:

standard output is done in the following format: hh:mm:ss.tt. The number of digits presented will be based on the precision attached to the current stream
output can be formatted by using either the setFormat() method for global angle format setting, or the output of MVTime::Format() data for a once off change (see later). Formats have a first argument which determines the type (default, if not given, MVTime::TIME, other possibility MVTime::ANGLE (as +ddd.mm.ss.tt.\.), the second the number of digits wanted (default stream precision), with a value:
- <3 : hh:: only
- <5 : hh:mm:
- <7 : hh:mm:ss
- >6 : with precision-6 t's added
comparable for angle. Tip: The added colons are to enable input checking of the format. Look at the 'clean' types to bypass them. The MVTime::YMD format implies TIME, and will precede the time with 'yyyy/mm/dd/' (or use MVTime::YMD_ONLY to include NO_TIME modifier).
The MVTime::DMY format implies TIME, and will precede the time with 'dd-Mon-yyyy/'.
The MVTime::FITS format implies TIME, and will precede the time with 'ccyy-mm-ddT'.
The output format can be modified with modifiers (specify as MVTime::TIME | MVTime::MOD (or + MVTime::MOD)). Caution: For overloading/casting problems with some compilers, the use of modifiers necessitates either the presence of a precision (i.e. (A|B, prec)), or an explicit cast: ((MVTime::formatTypes)(A|B)), or make use of the provided TIME[_CLEAN][_NO_H[M]] and ANGLE[_CLEAN][_NO_D[M]]. The modifiers can be:
- MVTime::CLEAN to suppress leading or trailing periods (or colons for TIME). Note that he result can not be read automatically.
- MVTime::NO_H (or NO_D) to suppress the output of hours (or degrees): useful for offsets
- MVTime::NO_HM (or NO_DM), to suppress the degrees and minutes.
- MVTime::DAY will precede the output with 'Day-' (e.g. Wed-)
- MVTime::NO_TIME will suppress printing of time.
Output in formats like 20' can be done via the standard Quantum output (e.g. stream << time.get("'") ).
Available formats:
- MVTime::ANGLE in +ddd.mm.ss.ttt format
- MVTime::TIME in hh:mm:ss.ttt format
- MVTime::[ANGLE|TIME]_CLEAN format without superfluous periods
- MVTime::[ANGLE|TIME][_CLEAN]_NO_[D|H][M] in format with leading zero fields left empty.
- MVTime::CLEAN modifier for suppressing superfluous periods
- MVTime::NO_[D|H][M] modifier to suppress first field(s)
- MVTime::DIG2 modifier to get +dd.mm.ss.ttt in angle or time format(i.e. in range -90 - +90 or -12 - +12)
- MVTime::LOCAL modifier to produce local time (as derived from aipsrc time.tzoffset). In FITS mode the time zone will be appended (as <sign>hh:mm). Caution: The adding of the timezone is not part of the FITS standard, but of the underlying ISO standard. It can be used to export local times in standard format.

The default formatting can be overwritten by a MVTime::setFormat(); statement; which returns an MVTime::Format structure, that can be used in a subsequent one to reset to previous. The format set holds for all MVTime output on all streams.
Temporary formats (i.e. for one MVTime output only), can be set by outputting a format (i.e. stream << MVTime::Format() << .\.. ). Caution: A setFormat() will also reset any lingering temporary format. A setFormat(getFormat()) will reset without changing. Problems could arise in parallel processors. Input can be read if the values are in any of the above (non-clean) output formats.
For other formatting practice, the output can be written to a String with the string() member functions.
Strings and input can be converted to an MVTime (or Quantity) by Bool read(Quantity &out, const String &in) and istream >> MVTime &. In the latter case the actual reading is done by the String read, which reads between white-spaces.
The following input formats (note no blanks allowed) are supported (+stands for an optional + or -; v for an unsigned integer; dv for a floating number. [] indicate optional values. Separating codes are case insensitive), numbers(like yyyy) can be of any length:

today -- (UT) time now
today/[time] -- time on today (0:0:0 if omitted)
yyyy/mm/dd[/time] -- date + time. An omitted date (leading /) will be today + time; an omitted month will indicate use of day number in year (1 == 1/1)
dd[-]MMM[-]yyyy[/time] -- date +time If yyyy <100: around 2000. MMM can be at least first three characters of month name; or a month number (1 == Jan). Omitted month indicates day is day number.
ccyy-mm-dd[Ttime[Z|+-hh[:mm]]] -- new FITS format the 'T' as time separator. Time should be UTC. The 'Z' separator (for UTC) is part of an earlier FITS proposal, and will be recognised for backward compatibility. A signed hh or hh:mm can be present to indicate time zone. This value will be subtracted to give UTC. To recognise this format, the year should be greater than 1000. Caution: The time-zone information is not part of the FITS standard, but of the underlying ISO standard.

The time can be expressed as described in MVAngle Examples of valid strings:

        ToDay           note case independence
        1996/11/20      20 November 1996 0h UT
        1996/11/20/5:20 20 November 1996 at 5h20m
        20Nov96-5h20m   same (again no case dependence)
        1996-11-20T5:20 same (FITS format, case dependent)

Example

See synopsis

Motivation

To be able to format date/time-like values in user-required ways.

To Do

Nothing I know of

Definition at line 253 of file MVTime.h.

const String & dayName () const

Get indicated part of the time/date.

const String & monthName () const

uInt weekday () const

Mon = 1; Sun = 7;.

uInt month () const

Jan =1.

uInt monthday () const

Int year () const

Int ymd () const

uInt yearday () const

uInt yearweek () const

static const String & dayName (uInt which)

static const String & monthName (uInt which)

Public Types

enum formatTypes

Format types. More...

Public Member Functions

MVTime ()

Default constructor: generate a zero value.

MVTime (const MVTime &other)

Copy constructor.

MVTime & operator= (const MVTime &other)

Copy assignment.

MVTime (Double d)

Constructor from Double (in MJD).

MVTime (const Quantity &other)

Constructor from Quantum : value can be an angle or time.

MVTime (const Time &other)

Constructor from Time.

MVTime (const MVEpoch &other)

Constructor from MVEpoch;.

MVTime (Int yy, Int mm, Double dd, Double d=0.0)

Constructor from yy, mm, dd, dd (all dd with fractions allowed).

~MVTime ()

operator Double () const

Conversion operator.

Double day () const

Get value of date/time (MJD) in given units.

Double hour () const

Double minute () const

Double second () const

Quantity get () const

Quantity get (const Unit &inunit) const

Time getTime () const

String string () const

Output data.

String string (MVTime::formatTypes intyp, uInt inprec=0) const

String string (uInt intyp, uInt inprec) const

String string (uInt inprec) const

String string (const MVTime::Format &form) const

void print (ostream &oss, const MVTime::Format &form) const

Static Public Member Functions

static Format getFormat ()

Get default format.

static MVTime::formatTypes giveMe (const String &in)

Get code belonging to string.

static Double timeZone ()

Get time zone offset (in days).

static Bool read (Quantity &res, const String &in)

Make res time Quantity from string.

static Bool read (Quantity &res, MUString &in)

static Bool read (Quantity &res, const String &in, Bool chk)

static Bool read (Quantity &res, MUString &in, Bool chk)

static Format setFormat (MVTime::formatTypes intyp, uInt inprec=0)

Set default format.

static Format setFormat (uInt intyp, uInt inprec)

static Format setFormat (uInt inprec=0)

static Format setFormat (const Format &form)

Private Member Functions

void ymd (Int &yyyy, Int &mm, Int &dd) const

Get the y,m,d values.

Private Attributes

Double val

Value.

Static Private Attributes

static MVTime::Format defaultFormat

Default format.

static MVTime::Format interimFormat

Temporary format.

static Bool interimSet

Friends

ostream & operator<< (ostream &os, const MVTime &meas)

Output a date/time.

istream & operator>> (istream &is, MVTime &meas)

Input a date/time.

ostream & operator<< (ostream &os, const MVTime::Format &form)

Set a temporary format.

Classes

class Format

Format structure. More...

Member Enumeration Documentation

enum casa::MVTime::formatTypes

Format types.

Definition at line 259 of file MVTime.h.

Constructor & Destructor Documentation

casa::MVTime::MVTime ( )

Default constructor: generate a zero value.

casa::MVTime::MVTime ( const MVTime & other )

Copy constructor.

casa::MVTime::MVTime ( Double d )

Constructor from Double (in MJD).

casa::MVTime::MVTime ( const Quantity & other )

Constructor from Quantum : value can be an angle or time.

Thrown Exceptions

AipsError if not a time or angle

casa::MVTime::MVTime ( const Time & other )

Constructor from Time.

casa::MVTime::MVTime ( const MVEpoch & other )

Constructor from MVEpoch;.

casa::MVTime::MVTime	(	Int	yy,
		Int	mm,
		Double	dd,
		Double	d = `0.0`
	)

Constructor from yy, mm, dd, dd (all dd with fractions allowed).

casa::MVTime::~MVTime ( )

Member Function Documentation

MVTime& casa::MVTime::operator= ( const MVTime & other )

Copy assignment.

casa::MVTime::operator Double ( ) const

Conversion operator.

static Bool casa::MVTime::read	(	Quantity &	res,
		const String &	in
	)			`[static]`

Make res time Quantity from string.

The String version will accept a time/angle Quantity as well. The chk checks for eos

static Bool casa::MVTime::read	(	Quantity &	res,
		MUString &	in
	)			`[static]`

static Bool casa::MVTime::read	(	Quantity &	res,
		const String &	in,
		Bool	chk
	)			`[static]`

static Bool casa::MVTime::read	(	Quantity &	res,
		MUString &	in,
		Bool	chk
	)			`[static]`

Double casa::MVTime::day ( ) const

Get value of date/time (MJD) in given units.

Double casa::MVTime::hour ( ) const

Double casa::MVTime::minute ( ) const

Double casa::MVTime::second ( ) const

Quantity casa::MVTime::get ( ) const

Quantity casa::MVTime::get ( const Unit & inunit ) const

Time casa::MVTime::getTime ( ) const

const String& casa::MVTime::dayName ( ) const

Get indicated part of the time/date.

static const String& casa::MVTime::dayName ( uInt which ) [static]

const String& casa::MVTime::monthName ( ) const

static const String& casa::MVTime::monthName ( uInt which ) [static]

uInt casa::MVTime::weekday ( ) const

Mon = 1; Sun = 7;.

uInt casa::MVTime::month ( ) const

Jan =1.

uInt casa::MVTime::monthday ( ) const

Int casa::MVTime::year ( ) const

Int casa::MVTime::ymd ( ) const

uInt casa::MVTime::yearday ( ) const

uInt casa::MVTime::yearweek ( ) const

String casa::MVTime::string ( ) const

Output data.

String casa::MVTime::string	(	MVTime::formatTypes	intyp,
		uInt	inprec = `0`
	)			const

String casa::MVTime::string	(	uInt	intyp,
		uInt	inprec
	)			const

String casa::MVTime::string ( uInt inprec ) const

String casa::MVTime::string ( const MVTime::Format & form ) const

void casa::MVTime::print	(	ostream &	oss,
		const MVTime::Format &	form
	)			const

static Format casa::MVTime::setFormat	(	MVTime::formatTypes	intyp,
		uInt	inprec = `0`
	)			`[static]`

Set default format.

static Format casa::MVTime::setFormat	(	uInt	intyp,
		uInt	inprec
	)			`[static]`

static Format casa::MVTime::setFormat ( uInt inprec = 0 ) [static]

static Format casa::MVTime::setFormat ( const Format & form ) [static]

static Format casa::MVTime::getFormat ( ) [static]

Get default format.

static MVTime::formatTypes casa::MVTime::giveMe ( const String & in ) [static]

Get code belonging to string.

0 if not known

static Double casa::MVTime::timeZone ( ) [static]

Get time zone offset (in days).

void casa::MVTime::ymd	(	Int &	yyyy,
		Int &	mm,
		Int &	dd
	)			const `[private]`

Get the y,m,d values.

Friends And Related Function Documentation

ostream& operator<<	(	ostream &	os,
		const MVTime &	meas
	)			`[friend]`

Output a date/time.

istream& operator>>	(	istream &	is,
		MVTime &	meas
	)			`[friend]`

Input a date/time.

ostream& operator<<	(	ostream &	os,
		const MVTime::Format &	form
	)			`[friend]`

Set a temporary format.

Member Data Documentation

Double casa::MVTime::val [private]

Value.

Definition at line 407 of file MVTime.h.

MVTime::Format casa::MVTime::defaultFormat [static, private]

Default format.

Definition at line 409 of file MVTime.h.

MVTime::Format casa::MVTime::interimFormat [static, private]

Temporary format.

Definition at line 412 of file MVTime.h.

Bool casa::MVTime::interimSet [static, private]

Definition at line 413 of file MVTime.h.

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

casa/implement/Quanta/MVTime.h

Generated on Mon Sep 1 22:44:16 2008 for NRAOCASA by

1.5.1


const String &	dayName () const
	Get indicated part of the time/date.
const String &	monthName () const
uInt	weekday () const
	Mon = 1; Sun = 7;.
uInt	month () const
	Jan =1.
uInt	monthday () const
Int	year () const
Int	ymd () const
uInt	yearday () const
uInt	yearweek () const
static const String &	dayName (uInt which)
static const String &	monthName (uInt which)
Public Types
enum	formatTypes
	Format types. More...
Public Member Functions
	MVTime ()
	Default constructor: generate a zero value.
	MVTime (const MVTime &other)
	Copy constructor.
MVTime &	operator= (const MVTime &other)
	Copy assignment.
	MVTime (Double d)
	Constructor from Double (in MJD).
	MVTime (const Quantity &other)
	Constructor from Quantum : value can be an angle or time.
	MVTime (const Time &other)
	Constructor from Time.
	MVTime (const MVEpoch &other)
	Constructor from MVEpoch;.
	MVTime (Int yy, Int mm, Double dd, Double d=0.0)
	Constructor from yy, mm, dd, dd (all dd with fractions allowed).
	~MVTime ()
	operator Double () const
	Conversion operator.

Double	day () const
	Get value of date/time (MJD) in given units.
Double	hour () const
Double	minute () const
Double	second () const
Quantity	get () const
Quantity	get (const Unit &inunit) const
Time	getTime () const

String	string () const
	Output data.
String	string (MVTime::formatTypes intyp, uInt inprec=0) const
String	string (uInt intyp, uInt inprec) const
String	string (uInt inprec) const
String	string (const MVTime::Format &form) const
void	print (ostream &oss, const MVTime::Format &form) const
Static Public Member Functions
static Format	getFormat ()
	Get default format.
static MVTime::formatTypes	giveMe (const String &in)
	Get code belonging to string.
static Double	timeZone ()
	Get time zone offset (in days).

static Bool	read (Quantity &res, const String &in)
	Make res time Quantity from string.
static Bool	read (Quantity &res, MUString &in)
static Bool	read (Quantity &res, const String &in, Bool chk)
static Bool	read (Quantity &res, MUString &in, Bool chk)

static Format	setFormat (MVTime::formatTypes intyp, uInt inprec=0)
	Set default format.
static Format	setFormat (uInt intyp, uInt inprec)
static Format	setFormat (uInt inprec=0)
static Format	setFormat (const Format &form)
Private Member Functions
void	ymd (Int &yyyy, Int &mm, Int &dd) const
	Get the y,m,d values.
Private Attributes
Double	val
	Value.
Static Private Attributes
static MVTime::Format	defaultFormat
	Default format.

static MVTime::Format	interimFormat
	Temporary format.
static Bool	interimSet
Friends
ostream &	operator<< (ostream &os, const MVTime &meas)
	Output a date/time.
istream &	operator>> (istream &is, MVTime &meas)
	Input a date/time.
ostream &	operator<< (ostream &os, const MVTime::Format &form)
	Set a temporary format.
Classes
class	Format
	Format structure. More...

casa::MVTime Class Reference [Quanta]

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

To Do

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Friends