Loading...
Searching...
No Matches
casacore::MVTime Class Reference
casa package (libcasa_casa) » Quanta_module

More...

`#include <MVTime.h>`

## Classes

class | Format
| Format structure. More...

## Public Types

enum | formatTypes { ANGLE , TIME , CLEAN , NO_D , NO_DM , YMD , DMY , DAY , NO_TIME , MJD , DIG2 , FITS , LOCAL , USE_SPACE , ALPHA , USE_Z , ISO , BOOST , NO_H , NO_HM , ANGLE_CLEAN , ANGLE_NO_D , ANGLE_NO_DM , ANGLE_CLEAN_NO_D , ANGLE_CLEAN_NO_DM , TIME_CLEAN , TIME_NO_H , TIME_NO_HM , TIME_CLEAN_NO_H , TIME_CLEAN_NO_HM , YMD_ONLY , MOD_MASK }
| 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
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
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 Bool | read (Quantity &res, const String &in, Bool chk=True)
| Make res time Quantity from string.
static Bool | read (Quantity &res, MUString &in, Bool chk=True)
static Bool | read (Quantity &res, const String &in, Bool chk, Bool throwExcp)
static Bool | read (Quantity &res, MUString &in, Bool chk, Bool throwExcp)
static const String & | dayName (uInt which)
static const String & | monthName (uInt which)
static Format | setFormat (MVTime::formatTypes intyp, uInt inprec=0)
| Set default format Warning: It is thread-unsafe to print using the setFormat functions because they change a static class member; The only thred-safe way to print a time is to use the print function above; .
static Format | setFormat (uInt intyp, uInt inprec)
static Format | setFormat (uInt inprec=0)
static Format | setFormat (const Format &form)
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).

## 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.

## Detailed Description

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

### Intended use:

Public interface

### 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 MVTime::ISO format implies FITS followed by a Z for the UTC time zone. It uses a space instead of T as separator. It also implies CLEAN. The BOOST format implies DMY and USE_SPACE (space instead of slash between date and time).
  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-). Space delimiter is used for USE_SPACE.
  - 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::USE_SPACE to use a space instead of a slash as delimiter between date and time.
  - MVTime::USE_Z to follow the time by a Z for the UTC time zone.
  - 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.
Note that using a temporary format is inherently thread-unsafe because the format is kept in a static variable. Another thread may overwrite the format just set. The only thread-safe way to format an MVTime is using a print or string that accepts a Format object.

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. The separator between date and time part can be a slash (as shown below), a hyphen, or one or more spaces.

- 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)
casacore::MVTime::FITS
@ FITS
Definition MVTime.h:286

### 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 268 of file MVTime.h.

## Member Enumeration Documentation

## formatTypes

enum casacore::MVTime::formatTypes

Format types.

Enumerator
ANGLE |
TIME |
CLEAN |
NO_D |
NO_DM |
YMD |
DMY |
DAY |
NO_TIME |
MJD |
DIG2 |
FITS |
LOCAL |
USE_SPACE |
ALPHA |
USE_Z |
ISO |
BOOST |
NO_H |
NO_HM |
ANGLE_CLEAN |
ANGLE_NO_D |
ANGLE_NO_DM |
ANGLE_CLEAN_NO_D |
ANGLE_CLEAN_NO_DM |
TIME_CLEAN |
TIME_NO_H |
TIME_NO_HM |
TIME_CLEAN_NO_H |
TIME_CLEAN_NO_HM |
YMD_ONLY |
MOD_MASK |

Definition at line 274 of file MVTime.h.

## Constructor & Destructor Documentation

## MVTime() [1/7]

casacore::MVTime::MVTime | ( |  | ) |

Default constructor: generate a zero value.

Referenced by MVTime(), operator<<, operator=(), and operator>>.

## MVTime() [2/7]

casacore::MVTime::MVTime | ( | const MVTime & | other | ) |

Copy constructor.

References MVTime().

## MVTime() [3/7]

casacore::MVTime::MVTime | ( | Double | d | ) |

Constructor from Double (in MJD).

## MVTime() [4/7]

casacore::MVTime::MVTime | ( | const Quantity & | other | ) |

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

### Thrown Exceptions

- AipsError if not a time or angle

## MVTime() [5/7]

casacore::MVTime::MVTime | ( | const Time & | other | ) |

Constructor from Time.

## MVTime() [6/7]

casacore::MVTime::MVTime | ( | const MVEpoch & | other | ) |

Constructor from MVEpoch;.

## MVTime() [7/7]

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

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

## ~MVTime()

casacore::MVTime::~MVTime | ( |  | ) |

## Member Function Documentation

## day()

Double casacore::MVTime::day | ( |  | ) | const

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

## dayName() [1/2]

const String & casacore::MVTime::dayName | ( |  | ) | const

Get indicated part of the time/date.

## dayName() [2/2]

const String & casacore::MVTime::dayName | ( | uInt | which | ) |

static

## get() [1/2]

Quantity casacore::MVTime::get | ( |  | ) | const

## get() [2/2]

Quantity casacore::MVTime::get | ( | const Unit & | inunit | ) | const

## getFormat()

Format casacore::MVTime::getFormat | ( |  | ) |

static

Get default format.

## getTime()

Time casacore::MVTime::getTime | ( |  | ) | const

## giveMe()

MVTime::formatTypes casacore::MVTime::giveMe | ( | const String & | in | ) |

static

Get code belonging to string.

0 if not known

## hour()

Double casacore::MVTime::hour | ( |  | ) | const

## minute()

Double casacore::MVTime::minute | ( |  | ) | const

## month()

uInt casacore::MVTime::month | ( |  | ) | const

Jan =1.

## monthday()

uInt casacore::MVTime::monthday | ( |  | ) | const

## monthName() [1/2]

const String & casacore::MVTime::monthName | ( |  | ) | const

## monthName() [2/2]

const String & casacore::MVTime::monthName | ( | uInt | which | ) |

static

## operator Double()

casacore::MVTime::operator Double | ( |  | ) | const

Conversion operator.

## operator=()

MVTime & casacore::MVTime::operator= | ( | const MVTime & | other | ) |

Copy assignment.

References MVTime().

## print()

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

## read() [1/4]

Bool casacore::MVTime::read | ( | Quantity & | res,
|  | const String & | in,
|  | Bool | chk,
|  | Bool | throwExcp )

static

## read() [2/4]

Bool casacore::MVTime::read | ( | Quantity & | res,
|  | const String & | in,
|  | Bool | chk = True )

static

Make res time Quantity from string.

The String version will accept a time/angle Quantity as well. It returns False in case of an error. chk=True means that the entire string should be consumed. throwExcp=True means that an exception is thrown in case of an error.

References casacore::True.

## read() [3/4]

Bool casacore::MVTime::read | ( | Quantity & | res,
|  | MUString & | in,
|  | Bool | chk,
|  | Bool | throwExcp )

static

## read() [4/4]

Bool casacore::MVTime::read | ( | Quantity & | res,
|  | MUString & | in,
|  | Bool | chk = True )

static

References casacore::True.

## second()

Double casacore::MVTime::second | ( |  | ) | const

## setFormat() [1/4]

Format casacore::MVTime::setFormat | ( | const Format & | form | ) |

static

## setFormat() [2/4]

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

static

Set default format
Warning: It is thread-unsafe to print using the setFormat functions because they change a static class member; The only thred-safe way to print a time is to use the print function above;
.

## setFormat() [3/4]

Format casacore::MVTime::setFormat | ( | uInt | inprec = 0 | ) |

static

## setFormat() [4/4]

Format casacore::MVTime::setFormat | ( | uInt | intyp,
|  | uInt | inprec )

static

## string() [1/5]

String casacore::MVTime::string | ( |  | ) | const

Output data.

Warning: The first function below is thread-unsafe because it uses the result of the setFormat function which changes a static class member; The other functions are thread-safe because the format is directly given;

## string() [2/5]

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

## string() [3/5]

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

## string() [4/5]

String casacore::MVTime::string | ( | uInt | inprec | ) | const

## string() [5/5]

String casacore::MVTime::string | ( | uInt | intyp,
|  | uInt | inprec ) const

## timeZone()

Double casacore::MVTime::timeZone | ( |  | ) |

static

Get time zone offset (in days).

## weekday()

uInt casacore::MVTime::weekday | ( |  | ) | const

Mon = 1; Sun = 7;.

## year()

Int casacore::MVTime::year | ( |  | ) | const

## yearday()

uInt casacore::MVTime::yearday | ( |  | ) | const

## yearweek()

uInt casacore::MVTime::yearweek | ( |  | ) | const

## ymd() [1/2]

Int casacore::MVTime::ymd | ( |  | ) | const

## ymd() [2/2]

void casacore::MVTime::ymd | ( | Int & | yyyy,
|  | Int & | mm,
|  | Int & | dd ) const

private

Get the y,m,d values.

## Friends And Related Symbol Documentation

## operator<< [1/2]

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

friend

Output a date/time.

Output

References MVTime().

## operator<< [2/2]

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

friend

Set a temporary format.

## operator>>

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

friend

Input a date/time.

References MVTime().

## Member Data Documentation

## defaultFormat

MVTime::Format casacore::MVTime::defaultFormat

static private

Default format.

Definition at line 440 of file MVTime.h.

## interimFormat

MVTime::Format casacore::MVTime::interimFormat

static private

Temporary format.

Definition at line 443 of file MVTime.h.

## interimSet

Bool casacore::MVTime::interimSet

static private

Definition at line 444 of file MVTime.h.

## val

Double casacore::MVTime::val

private

Value.

Definition at line 438 of file MVTime.h.

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

- casa/Quanta/MVTime.h