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

Include dependency graph for datetime.h:

This graph shows which files directly or indirectly include 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 133 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
  const 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 62 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(), substituteLatexKeywords(), and writeDefaultStyleSheet().

◆ 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 174 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; };
  QCString result;
  result.reserve(256);
  auto addInt = [&result](const char *fmt,int value) {
    char tmp[50];
    qsnprintf(tmp,50,fmt,value);
    result+=tmp;
  };
  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 '%': result+='%';                                                                                       break;
          case 'y': addInt(fmt_selected,getYear(dt)%100);                              formatUsed|=SF_Date;    break;
          case 'Y': addInt("%d",getYear(dt));                                          formatUsed|=SF_Date;    break;
          case 'm': addInt(fmt_selected,getMonth(dt));                                 formatUsed|=SF_Date;    break;
          case 'b': result+=theTranslator->trMonth(getMonth(dt),false,false);          formatUsed|=SF_Date;    break;
          case 'B': result+=theTranslator->trMonth(getMonth(dt),false,true);           formatUsed|=SF_Date;    break;
          case 'd': addInt(fmt_selected,getDay(dt));                                   formatUsed|=SF_Date;    break;
          case 'u': addInt("%d",getDayOfWeek(dt));   /* Monday = 1 ... Sunday = 7 */   formatUsed|=SF_Date;    break;
          case 'w': addInt("%d",getDayOfWeek(dt)%7); /* Sunday = 0 ... Saturday = 6 */ formatUsed|=SF_Date;    break;
          case 'a': result+=theTranslator->trDayOfWeek(getDayOfWeek(dt),false,false);  formatUsed|=SF_Date;    break;
          case 'A': result+=theTranslator->trDayOfWeek(getDayOfWeek(dt),false,true);   formatUsed|=SF_Date;    break;
          case 'H': addInt(fmt_selected,dt.tm_hour);                                   formatUsed|=SF_Time;    break;
          case 'I': addInt(fmt_selected,dt.tm_hour%12);                                formatUsed|=SF_Time;    break;
          case 'p': result+=theTranslator->trDayPeriod(dt.tm_hour>=12);                formatUsed|=SF_Time;    break;
          case 'M': addInt(fmt_selected,dt.tm_min);                                    formatUsed|=SF_Time;    break;
          case 'S': addInt(fmt_selected,dt.tm_sec);                                    formatUsed|=SF_Seconds; break;
          default:
            result+=c;
            if (*(p-1)=='-') result+='-';
            result+=nc;
            break;
        }
        p++;
        break;
      default:
        result+=c;
        break;
    }
  }
  return result;
}

References QCString::data(), qsnprintf, QCString::reserve(), 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 29 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 '{}'\n",
            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(), 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 75 of file datetime.cpp.

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

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

Referenced by substituteLatexKeywords(), and writeDefaultStyleSheet().

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().

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ DateTimeType

Function Documentation

◆ dateTimeFromString()

◆ dateToString()

◆ formatDateTime()

◆ getCurrentDateTime()

◆ SF_bit2str()

◆ yearToString()

Variable Documentation

◆ SF_Date

◆ SF_NumBits

◆ SF_Seconds

◆ SF_Time