CurrentDateTime

Header:	STD.h
Namespace:	avl

Returns current date and time in multiple formats.

Applications: Combines the most commonly used date and time filters into one tool.

Syntax

void avl::CurrentDateTime
(
	avl::TimezoneKind::Type inTimezone,
	const atl::String& inFormat,
	const int inDecimalPlaces,
	const atl::String& inLocale,
	avl::Timestamp& outTimestamp,
	avl::DateTime& outDateTime,
	atl::String& outString
)

Parameters

Name	Type	Range	Default	Description
inTimezone	TimezoneKind::Type			Timezone to convert to
inFormat	const String&		\"%x %X\"	Date and time format to use
inDecimalPlaces	const int	0 - 9		Number of decimal places to use when printing seconds
inLocale	const String&			Locale to use when converting
outTimestamp	Timestamp&			Current UTC timestamp
outDateTime	DateTime&			Date and time in selected timezone
outString	String&			Date and time converted to string

Description

inFormat string can contain format specifiers which will be replaced with corresponding values. The most commonly used format specifiers are:

Specifier	Example output	Description
%a	Sun	locale-dependent weekday name, short
%A	Sunday	locale-dependent weekday name, long
%b	Jan	locale-dependent month name, short
%B	January	locale-dependent month name, long
%c	1/31/2021 3:04:05 PM	locale-dependent date and time. Warning: on some locales it can also print current timezone name, which may be different from timezone in passed DateTime object.
%C	20	year divided by 100
%d	31	day of month, <01;31>
%H	15	hour, <00;23>
%I	03	hour, <01;12>
%m	01	month, <01;12>
%M	04	minute, <00;59>
%p	PM	"AM" or "PM" (locale-dependent)
%r	3:04:05 PM	locale-dependent 12-hour time
%S	05.6780000	seconds, <00;59>, use inDecimalPlaces to set precision (decimal separator is locale-dependent)
%u	7	weekday, <1;7> (Sunday is 7)
%w	0	weekday, <0;6> (Sunday is 0)
%x	1/31/2021	locale-dependent date
%X	3:04:05 PM	locale-dependent time
%y	21	last two digits of year, <00;99>
%Y	2021	year (left padded with "0" to 4 digits)
%z	+0500	offset from UTC, e.g. "+0500" for UTC+5 timezone
%Z	local	timezone name: "UTC" if offset is 0, otherwise "local"
%%	%	"%" character

For a full list of format specifiers, see https://howardhinnant.github.io/date/date.html#to_stream_formatting.

inLocale can be used to choose how locale-dependent values are formatted. It can have values such as:

Locale	Example output for format "%x, %A"	Description
(empty string)	2021-01-31, niedziela	use locale set as system default
C	01/31/21, Sunday	use "C locale"
de_DE.utf8	31.01.2021, Sonntag	German language in Germany
pt_BR.utf8	31/01/2021, domingo	Portuguese language in Brazil

Note that the requested locale must be installed on the operating system.

Remarks

Assumptions about date and time calculations:

Timestamp should always be in UTC (Coordinated Universal Time).
Timestamp can be converted to DateTime using either UTC or local timezone. Other timezones are not supported. However, the timezone offset is saved in DateTime so one can always convert back to UTC.
Conversion to local time should take into account daylight saving time (summer/winter time), if configured in the operating system. However, usually only currently applicable DST rules are used, so calculations may be incorrect if they refer to a period when the rules were different.
Timestamp resolution is 100 nanoseconds.
Timestamp is 64-bit, so should support dates about 29000 years in the past or future. However, the whole range may not be supported when converting to local timezone.
Dates are calculated in proleptic Gregorian calendar.
Leap seconds are ignored, like in Unix time.

Errors

List of possible exceptions:

Error type	Description
RuntimeError	Couldn't convert time to local timezone This could mean the date is out of supported range. Set inTimezone to UTC to skip the conversion.
SystemError	Couldn't find locale: exception message