Back to Aurora Vision Library Lite website

You are here: Start » System » Time » FormatDateTimeToString

FormatDateTimeToString


Header: STD.h
Namespace: avl

Returns a string containing date and time information in selected format.

Syntax

C++
Python
 
void avl::FormatDateTimeToString
(
	const avl::DateTime& inDateTime,
	const atl::String& inFormat,
	const int inDecimalPlaces,
	const atl::String& inLocale,
	atl::String& outString
)

Parameters

Name Type Range Default Description
Input value inDateTime const DateTime& Date and time with timezone offset
Input value inFormat const String& \"%x %X\" Date and time format to use
Input value inDecimalPlaces const int 0 - 9 Number of decimal places to use when printing seconds
Input value inLocale const String& Locale to use when converting
Output value 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:

SpecifierExample outputDescription
%aSunlocale-dependent weekday name, short
%ASundaylocale-dependent weekday name, long
%bJanlocale-dependent month name, short
%BJanuarylocale-dependent month name, long
%c1/31/2021 3:04:05 PMlocale-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.
%C20year divided by 100
%d31day of month, <01;31>
%H15hour, <00;23>
%I03hour, <01;12>
%m01month, <01;12>
%M04minute, <00;59>
%pPM"AM" or "PM" (locale-dependent)
%r3:04:05 PMlocale-dependent 12-hour time
%S05.6780000seconds, <00;59>, use inDecimalPlaces to set precision (decimal separator is locale-dependent)
%u7weekday, <1;7> (Sunday is 7)
%w0weekday, <0;6> (Sunday is 0)
%x1/31/2021locale-dependent date
%X3:04:05 PMlocale-dependent time
%y21last two digits of year, <00;99>
%Y2021year (left padded with "0" to 4 digits)
%z+0500offset from UTC, e.g. "+0500" for UTC+5 timezone
%Zlocaltimezone 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:

LocaleExample output
for format "%x, %A"		Description
(empty string)2021-01-31, niedzielause locale set as system default
C01/31/21, Sundayuse "C locale"
de_DE.utf831.01.2021, SonntagGerman language in Germany
pt_BR.utf831/01/2021, domingoPortuguese language in Brazil

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

Remarks

inDateTime.DayOfWeek field is ignored and computed from the other fields.

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
DomainError Date or time field out of range
DomainError Invalid inDecimalPlaces value
SystemError Couldn't find locale: exception message