Description:

This class represents a point in time as a set of calendar and clock values (year, month, day, hour, ...). It provides methods to convert to and from objects of type DateTime. In addition, a method to format the date and time into human-readable string value is available.

Note

The conversion from and into objects of type Ticks is intentionally not supported. In the case that such objects should be used with this class, an additional conversion step has to be performed using class TickConverter. In other words, conversion can be performed as follows:

   CalendarDateTime <=> DateTime <=> Ticks

This class is using system-specific calendar methods and relies on the locale and time zone settings of the machine.

Definition at line 29 of file calendar.inl.

Collaboration diagram for alib::strings::util::CalendarDateTime:

[legend]

Public Static Field Index:
static ALIB_DLL String	DAY_NAMES [7]

static ALIB_DLL String	MONTH_NAMES [12]

Public Field Index:
int	Day
	The calendar day (1..31).

int	DayOfWeek

int	Hour
	The calendar hour (0..23).

int	Millisecond
	The calendar millisecond (0..999).

int	Minute
	The calendar minute (0..59).

int	Month
	The calendar month (1..12).

int	Second
	The calendar second (0..59).

int	Year
	The calendar year (e.g., 2022).

Public Method Index:
	CalendarDateTime (const DateTime &timeStamp, lang::Timezone timezone=lang::Timezone::Local)

	CalendarDateTime (int year, int month=1, int day=1, int hour=0, int minute=0, int second=0, int millisecond=0)

	CalendarDateTime (lang::Initialization init=lang::Initialization::Default)

ALIB_DLL void	Clear ()
	Sets all public values to `0`.

ALIB_DLL AString &	Format (Substring format, AString &target, lang::CurrentData targetData=lang::CurrentData::Keep) const

ALIB_DLL DateTime	Get (lang::Timezone timezone=lang::Timezone::Local) const

ALIB_DLL void	Set (const DateTime &timeStamp, lang::Timezone timezone=lang::Timezone::Local)

Field Details:

◆ Day

int alib::strings::util::CalendarDateTime::Day

The calendar day (1..31).

Definition at line 56 of file calendar.inl.

◆ DAY_NAMES

ALIB_DLL String alib::strings::util::CalendarDateTime::DAY_NAMES[7]

static

A list of day names used with the method CalendarDateTime::Format.

If module ALib Camp is not included in the ALib Build, the values default to:

={ A_CHAR("Sunday"   ),  A_CHAR("Monday"   ),
   A_CHAR("Tuesday"  ),  A_CHAR("Wednesday"),
   A_CHAR("Thursday" ),  A_CHAR("Friday"   ),
   A_CHAR("Saturday" )                        };

In case the module is included, the same values are resourced in alib::BASECAMP under key "Days". In both cases a user might change this during bootstrap.

Definition at line 47 of file calendar.inl.

◆ DayOfWeek

int alib::strings::util::CalendarDateTime::DayOfWeek

The calendar day of week (0==Sunday..6==Saturday).

Attention: This value is only set when constructed with a DateTime object and set to -1 if constructed with single values, or if method Clear is invoked.

Definition at line 74 of file calendar.inl.

◆ Hour

int alib::strings::util::CalendarDateTime::Hour

The calendar hour (0..23).

Definition at line 59 of file calendar.inl.

◆ Millisecond

int alib::strings::util::CalendarDateTime::Millisecond

The calendar millisecond (0..999).

Definition at line 68 of file calendar.inl.

◆ Minute

int alib::strings::util::CalendarDateTime::Minute

The calendar minute (0..59).

Definition at line 62 of file calendar.inl.

◆ Month

int alib::strings::util::CalendarDateTime::Month

The calendar month (1..12).

Definition at line 53 of file calendar.inl.

◆ MONTH_NAMES

ALIB_DLL String alib::strings::util::CalendarDateTime::MONTH_NAMES[12]

static

A list of month names used with the method CalendarDateTime::Format.

If module ALib Camp is not included in the ALib Build, the values default to:

={ A_CHAR("January"  ),  A_CHAR("February" ),
   A_CHAR("March"    ),  A_CHAR("April"    ),
   A_CHAR("May"      ),  A_CHAR("June"     ),
   A_CHAR("July"     ),  A_CHAR("August"   ),
   A_CHAR("September"),  A_CHAR("October"  ),
   A_CHAR("November" ),  A_CHAR("December" )  };

In case the module is included, the same values are resourced in alib::BASECAMP under key "Months". In both cases a user might change this during bootstrap.

Definition at line 39 of file calendar.inl.

◆ Second

int alib::strings::util::CalendarDateTime::Second

The calendar second (0..59).

Definition at line 65 of file calendar.inl.

◆ Year

int alib::strings::util::CalendarDateTime::Year

The calendar year (e.g., 2022).

Definition at line 50 of file calendar.inl.

Constructor(s) / Destructor Details:

◆ CalendarDateTime() [1/3]

alib::strings::util::CalendarDateTime::CalendarDateTime ( lang::Initialization init = lang::Initialization::Default )

inline

Constructs an unset object.

Parameters

init	If Initialization::Default or nulled, Clear is invoked. Otherwise fields are not initialized. Defaults to `Initialization::Default`.

Definition at line 81 of file calendar.inl.

Here is the call graph for this function:

◆ CalendarDateTime() [2/3]

alib::strings::util::CalendarDateTime::CalendarDateTime	(	const DateTime &	timeStamp,
		lang::Timezone	timezone = lang::Timezone::Local )

inline

Constructs the object according to the given timestamp object and time zone.

Parameters

timeStamp	The point in time to use for setting the public fields
timezone	Denotes if the time that is calculated should be local or UTC. Defaults to `TimeZone::Local`.

Definition at line 93 of file calendar.inl.

Here is the call graph for this function:

◆ CalendarDateTime() [3/3]

alib::strings::util::CalendarDateTime::CalendarDateTime	(	int	year,
		int	month = 1,
		int	day = 1,
		int	hour = 0,
		int	minute = 0,
		int	second = 0,
		int	millisecond = 0 )

inline

Constructs the object according to the given date and time values.

Parameters

year	The year of the calendar time.
month	The month of the calendar time.
day	The day of the calendar time.
hour	The hour of the calendar time.
minute	The minute of the calendar time.
second	The second of the calendar time.
millisecond	The millisecond of the calendar time.

Definition at line 108 of file calendar.inl.

Method Details:

◆ Clear()

void alib::strings::util::CalendarDateTime::Clear ( )

Sets all public values to 0.

Definition at line 63 of file calendar.cpp.

◆ Format()

AString & alib::strings::util::CalendarDateTime::Format	(	Substring	format,
		AString &	target,
		lang::CurrentData	targetData = lang::CurrentData::Keep ) const

Formats the date using a given pattern string. Within the pattern string, different symbols are interpreted as tokens. The format is compatible with C# time format strings, as well as with class SimpleDateFormat of the Java APIs.
Strings within the format text that should not be interpreted as tokens may be surrounded by single quotes. Strings within the format text that should not be interpreted as tokens may be given in single quotes. Two consecutive single quotes will be replaced to one single quote.

Token	Description
y	The year with as many digits as it has (for current dates this is 4).
yy	The year, truncated to 2 digits (modulo 100).
yyy...y	The year with a minimum amount of digits as amount of y-characters given.
M	The month as numbers from 1..12.
MM	The month as numbers from 01..12.
MMM	The month as abbreviated, 3-digit word defined by resourced strings (defaults to English language).
MMMM	The month as word defined by resourced strings (defaults to English language).
d	The day as numbers from 1..31.
dd	The day as numbers from 01..31.
ddd	The day as abbreviated, 3-digit word defined by resourced strings (defaults to English language).
dddd	The day as word defined by resourced strings (defaults to English language).
H	The hour as numbers from 0..23.
HH	The hour as numbers from 00..23.
K	The hour as numbers from 0..11 am/pm.
KK	The hour as numbers from 00..11 am/pm.
m	The minute as numbers from 0..59.
mm	The minute as numbers from 00..59.
s	The second as numbers from 0..59.
ss	The second as numbers from 00..59.

Parameters

format	The format pattern string.
target	A reference to an AString that gets the result of the format processing appended.
targetData	If `CurrentData::Keep` (the default) the string is appended to target. if `CurrentData::Clear`, target is cleared.

Returns: target (for convenience).

Definition at line 319 of file calendar.cpp.

Here is the call graph for this function:

◆ Get()

DateTime alib::strings::util::CalendarDateTime::Get ( lang::Timezone timezone = lang::Timezone::Local ) const

Creates a DateTime object from this calendar date.

Attention: The resolution and possible time range of class DateTime is platform-dependent. This method must not be used if inconsistent values are stored.

Parameters

timezone Denote if the time that is calculated should be local or UTC. Defaults to TimeZone::Local.

Returns: The point in time represented by the public fields of this class.

Definition at line 117 of file calendar.cpp.

Here is the call graph for this function:

◆ Set()

void alib::strings::util::CalendarDateTime::Set	(	const DateTime &	timeStamp,
		lang::Timezone	timezone = lang::Timezone::Local )

Sets the public fields according to the given timestamp object.

Parameters

timeStamp	The point in time to use for setting the public fields
timezone	Denotes if the time that is calculated should be local or UTC. Defaults to `TimeZone::Local`.

Definition at line 75 of file calendar.cpp.

Here is the call graph for this function:

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

Description:

Public Static Field Index:

Public Field Index:

Public Method Index:

Field Details:

◆ Day

◆ DAY_NAMES

◆ DayOfWeek

◆ Hour

◆ Millisecond

◆ Minute

◆ Month

◆ MONTH_NAMES

◆ Second

◆ Year

Constructor(s) / Destructor Details:

◆ CalendarDateTime() [1/3]

◆ CalendarDateTime() [2/3]

◆ CalendarDateTime() [3/3]

Method Details:

◆ Clear()

◆ Format()

◆ Get()

◆ Set()