datetime.h File Reference

#include <ctime>
#include "qcstring.h"

Include dependency graph for datetime.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum class	DateTimeType { DateTime , Date , Time }

Functions
constexpr const char *	SF_bit2str (int bitNumber)
	Helper function that returns the name related one of the SF bits.
QCString	dateTimeFromString (const QCString &spec, std::tm &dt, int &format)
	Returns the filled in std::tm for a given string representing a date and/or time.
QCString	formatDateTime (const QCString &format, const std::tm &dt, int &formatUsed)
	Return a string representation for a given std::tm value that is formatted according to the pattern given by a format.
std::tm	getCurrentDateTime ()
	Returns the filled in std::tm for the current date and time.
QCString	yearToString ()
	Returns the current year as a string.
QCString	dateToString (DateTimeType includeTime)
	Returns the current date, when includeTime is set also the time is provided.

Variables
constexpr int	SF_Date = 1<<0
	Date and time related functions.
constexpr int	SF_Time = 1<<1
	a time is presenting in the format string
constexpr int	SF_Seconds = 1<<2
	the seconds are presenting in the format string
constexpr int	SF_NumBits = 3
	number of bits in SF vector

Enumeration Type Documentation

DateTimeType

enum class DateTimeType

strong

Enumerator
DateTime
Date
Time

Definition at line 38 of file datetime.h.

                        { DateTime,
                          Date,
                          Time
                        };

Function Documentation

dateTimeFromString()

QCString dateTimeFromString	(	const QCString &	spec,
		std::tm &	dt,
		int &	format )

Returns the filled in std::tm for a given string representing a date and/or time.

Parameters

[in]	spec	The string representation of the date and/or time Possible formats: the empty string: the current date and time is returned YYYY-MM-DD HH:MM:SS: the date and time are fully specified YYYY-MM-DD HH:MM: the date and time without seconds YYYY-MM-DD: the date without time HH:MM:SS: the time with seconds but without date HH:MM: the time without seconds and without date
[out]	dt	The corresponding datetime value.
[out]	format	The parts that have been found in spec; a bitwise or of SF_Date, SF_Time and SF_Seconds.

Returns

An empty string if the spec has a supported format, or an error message if the format is invalid.

Definition at line 134 of file datetime.cpp.

{
  // for an empty spec field return the current date and time
  dt = getCurrentDateTime();
  if (spec.isEmpty())
  {
    format = SF_Date | SF_Time | SF_Seconds;
    return QCString();
  }
 
  // find a matching pattern
  std::string s = spec.str();
  for (const auto &fmt : g_specFormats)
  {
    reg::Match m;
    if (reg::match(s,m,fmt.re)) // match found
    {
      for (int i=0; i<fmt.count; i++)
      {
        int value = std::atoi(m[i+1].str().c_str());
        const DateTimeField &dtf = g_assignValues[i+fmt.offset];
        if (value<dtf.minVal || value>dtf.maxVal) // check if the value is in the expected range
        {
          return QCString().sprintf("value for %s is %d which is outside of the value range [%d..%d]",
              dtf.name, value, dtf.minVal, dtf.maxVal);
        }
        dtf.assigner(dt,value);
      }
      format = fmt.format;
      if (format&SF_Date) // if we have a date also determine the weekday
      {
        determine_weekday(dt);
      }
      return QCString();
    }
  }
 
  // no matching pattern found
  return "invalid or non representable date/time argument";
}

References DateTimeField::assigner, determine_weekday(), g_assignValues, g_specFormats, getCurrentDateTime(), QCString::isEmpty(), reg::match(), DateTimeField::maxVal, DateTimeField::minVal, DateTimeField::name, SF_Date, SF_Seconds, SF_Time, QCString::sprintf(), and QCString::str().

Referenced by DocPara::handleShowDate(), and showDate().

dateToString()

QCString dateToString

(

DateTimeType

includeTime

)

Returns the current date, when includeTime is set also the time is provided.

Parameters

[in]

includeTime

include the time in the output

Definition at line 63 of file datetime.cpp.

{
  auto current = getCurrentDateTime();
  return theTranslator->trDateTime(current.tm_year + 1900,
                                   current.tm_mon + 1,
                                   current.tm_mday,
                                   (current.tm_wday+6)%7+1, // map: Sun=0..Sat=6 to Mon=1..Sun=7
                                   current.tm_hour,
                                   current.tm_min,
                                   current.tm_sec,
                                   includeTime);
}

References getCurrentDateTime(), and theTranslator.

Referenced by RTFGenerator::endIndexSection(), ManGenerator::endTitleHead(), recordMetadata(), substituteHtmlKeywords(), substituteKeywords(), substituteLatexKeywords(), and HtmlGenerator::writeLogoAsString().

formatDateTime()

QCString formatDateTime	(	const QCString &	format,
		const std::tm &	dt,
		int &	formatUsed )

Return a string representation for a given std::tm value that is formatted according to the pattern given by a format.

Parameters

[in]	format	the string used for format the date and time, e.g. Y-m-d
[in]	dt	the date and time value to fill in
[out]	formatUsed	A bitwise OR of SF_Date, SF_Time and SF_Seconds representing the the types of markers found in the format string.

Definition at line 175 of file datetime.cpp.

{
  formatUsed = 0;
  auto getYear      = [](const std::tm &dat) { return dat.tm_year+1900;    };
  auto getMonth     = [](const std::tm &dat) { return dat.tm_mon+1;        };
  auto getDay       = [](const std::tm &dat) { return dat.tm_mday;         };
  auto getDayOfWeek = [](const std::tm &dat) { return (dat.tm_wday+6)%7+1; };
  GrowBuf growBuf;
  char c = 0;
  const char *p            = format.data();
  const char *fmt_zero     = "%02d";
  const char *fmt_nonzero  = "%d";
  const char *fmt_selected = nullptr;
  if (p==nullptr) return QCString();
  while ((c=*p++))
  {
    char nc = *p;
    switch (c)
    {
      case '%':
        fmt_selected = nc=='-' ? fmt_nonzero : fmt_zero; // %-H produces 1 and %H produces 01
        if (nc=='-') nc=*++p; // skip over -
        switch (nc)
        {
          case '%': growBuf.addChar('%');                                                                              break;
          case 'y': growBuf.addInt(fmt_selected,getYear(dt)%100);                              formatUsed|=SF_Date;    break;
          case 'Y': growBuf.addInt("%d",getYear(dt));                                          formatUsed|=SF_Date;    break;
          case 'm': growBuf.addInt(fmt_selected,getMonth(dt));                                 formatUsed|=SF_Date;    break;
          case 'b': growBuf.addStr(theTranslator->trMonth(getMonth(dt),false,false));          formatUsed|=SF_Date;    break;
          case 'B': growBuf.addStr(theTranslator->trMonth(getMonth(dt),false,true));           formatUsed|=SF_Date;    break;
          case 'd': growBuf.addInt(fmt_selected,getDay(dt));                                   formatUsed|=SF_Date;    break;
          case 'u': growBuf.addInt("%d",getDayOfWeek(dt));   /* Monday = 1 ... Sunday = 7 */   formatUsed|=SF_Date;    break;
          case 'w': growBuf.addInt("%d",getDayOfWeek(dt)%7); /* Sunday = 0 ... Saturday = 6 */ formatUsed|=SF_Date;    break;
          case 'a': growBuf.addStr(theTranslator->trDayOfWeek(getDayOfWeek(dt),false,false));  formatUsed|=SF_Date;    break;
          case 'A': growBuf.addStr(theTranslator->trDayOfWeek(getDayOfWeek(dt),false,true));   formatUsed|=SF_Date;    break;
          case 'H': growBuf.addInt(fmt_selected,dt.tm_hour);                                   formatUsed|=SF_Time;    break;
          case 'I': growBuf.addInt(fmt_selected,dt.tm_hour%12);                                formatUsed|=SF_Time;    break;
          case 'p': growBuf.addStr(theTranslator->trDayPeriod(dt.tm_hour>=12));                formatUsed|=SF_Time;    break;
          case 'M': growBuf.addInt(fmt_selected,dt.tm_min);                                    formatUsed|=SF_Time;    break;
          case 'S': growBuf.addInt(fmt_selected,dt.tm_sec);                                    formatUsed|=SF_Seconds; break;
          default:
            growBuf.addChar(c);
            if (*(p-1)=='-') growBuf.addChar('-');
            growBuf.addChar(nc);
            break;
        }
        p++;
        break;
      default:
        growBuf.addChar(c);
        break;
    }
  }
  growBuf.addChar(0);
  return growBuf.get();
}

References GrowBuf::addChar(), GrowBuf::addInt(), GrowBuf::addStr(), QCString::data(), GrowBuf::get(), SF_Date, SF_Seconds, SF_Time, and theTranslator.

Referenced by DocPara::handleShowDate(), and showDate().

getCurrentDateTime()

std::tm getCurrentDateTime

(

)

Returns the filled in std::tm for the current date and time.

Definition at line 30 of file datetime.cpp.

{
  QCString sourceDateEpoch = Portable::getenv("SOURCE_DATE_EPOCH");
  if (!sourceDateEpoch.isEmpty()) // see https://reproducible-builds.org/specs/source-date-epoch/
  {
    bool ok = false;
    uint64_t epoch = sourceDateEpoch.toUInt64(&ok);
    if (!ok)
    {
      static bool warnedOnce=FALSE;
      if (!warnedOnce)
      {
        warn_uncond("Environment variable SOURCE_DATE_EPOCH does not contain a valid number; value is '%s'\n",
            qPrint(sourceDateEpoch));
        warnedOnce=TRUE;
      }
    }
    else // use given epoch value as current 'built' time
    {
      auto epoch_start    = std::chrono::time_point<std::chrono::system_clock>{};
      auto epoch_seconds  = std::chrono::seconds(epoch);
      auto build_time     = epoch_start + epoch_seconds;
      std::time_t time    = std::chrono::system_clock::to_time_t(build_time);
      return *gmtime(&time);
    }
  }
 
  // return current local time
  auto now = std::chrono::system_clock::now();
  std::time_t time = std::chrono::system_clock::to_time_t(now);
  return *localtime(&time);
}

References FALSE, Portable::getenv(), QCString::isEmpty(), qPrint(), QCString::toUInt64(), TRUE, and warn_uncond.

Referenced by dateTimeFromString(), dateToRTFDateString(), dateToString(), and yearToString().

SF_bit2str()

const char * SF_bit2str ( int bitNumber )

constexpr

Helper function that returns the name related one of the SF bits.

Used for generating warnings.

Parameters

[in]

bitNumber

bit value in range [0..SF_NumBits) for which to return the string value.

Definition at line 32 of file datetime.h.

{
  constexpr const char *partNames[] = { "date", "time", "seconds" };
  return bitNumber>=0 && bitNumber<SF_NumBits ? partNames[bitNumber] : "";
}

References SF_NumBits.

Referenced by DocPara::handleShowDate().

yearToString()

QCString yearToString

(

)

Returns the current year as a string.

Definition at line 76 of file datetime.cpp.

{
  auto current = getCurrentDateTime();
  return QCString().setNum(current.tm_year+1900);
}

References getCurrentDateTime(), and QCString::setNum().

Referenced by substituteKeywords().

Variable Documentation

SF_Date

int SF_Date = 1<<0

constexpr

Date and time related functions.

a date is presenting in the format string

Definition at line 24 of file datetime.h.

Referenced by dateTimeFromString(), and formatDateTime().

SF_NumBits

int SF_NumBits = 3

constexpr

number of bits in SF vector

Definition at line 27 of file datetime.h.

Referenced by DocPara::handleShowDate(), and SF_bit2str().

SF_Seconds

int SF_Seconds = 1<<2

constexpr

the seconds are presenting in the format string

Definition at line 26 of file datetime.h.

Referenced by dateTimeFromString(), and formatDateTime().

SF_Time

int SF_Time = 1<<1

constexpr

a time is presenting in the format string

Definition at line 25 of file datetime.h.

Referenced by dateTimeFromString(), and formatDateTime().