/doc/time.datetime.html

http://github.com/foodmike/PTypes · HTML · 92 lines · 86 code · 2 blank · 4 comment · 0 complexity · 030a38f1a64f1f70be81cb23ce7283c6 MD5 · raw file

  1. <html><!-- #BeginTemplate "/Templates/tmpl.dwt" --><!-- DW6 -->
  2. <head>
  3. <!-- #BeginEditable "doctitle" -->
  4. <title>PTypes: date/time: datetime</title>
  5. <!-- #EndEditable -->
  6. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  7. <link rel="stylesheet" href="styles.css">
  8. </head>
  9. <body bgcolor="#FFFFFF" leftmargin="40" marginwidth="40">
  10. <p><a href="../index.html"><img src="title-21.png" width="253" height="39" alt="C++ Portable Types Library (PTypes) Version 2.1" border="0"></a>
  11. <hr size="1" noshade>
  12. <!-- #BeginEditable "body" -->
  13. <p class="hpath"><a href="index.html">Top</a>: <a href="basic.html">Basic types</a>:
  14. <a href="time.html">Date/time</a>: Datetime type</p>
  15. <blockquote>
  16. <pre class="lang">#include &lt;ptime.h&gt;
  17. typedef large datetime;
  18. datetime now(bool utc = true);
  19. int days(datetime d);
  20. int msecs(datetime d);
  21. datetime mkdt(int days, int msecs);
  22. bool isvalid(datetime d);
  23. void tzupdate();
  24. int tzoffset();
  25. string dttostring(datetime d, const char* fmt);
  26. string nowstring(const char* fmt, bool utc = true);
  27. datetime utodatetime(time_t u);</pre>
  28. </blockquote>
  29. <p><span class="def">datetime now(bool utc = true)</span> returns the current
  30. date/time. The returned value can be either the local time or the Universal Coordinated
  31. Time (UTC, aka GMT), depending on the parameter <span class="lang">utc</span>.
  32. It is recommended to manipulate with the UTC time internally in your application
  33. whenever possible (f.ex. when it's not needed to display the time to the user),
  34. since in many countries the local time may be automatically adjusted when entering
  35. or leaving the daylight saving period, which may confuse your application. On
  36. the contrary, the UTC time never changes. That's why all modern operating systems
  37. rely on the UTC time internally. (See also <span class="lang">tzupdate()</span>
  38. below for additional notes).</p>
  39. <p><span class="def">int days(datetime d)</span> returns the number of days since
  40. the beginning of the calendar contained in the <span class="lang">datetime</span>
  41. value <span class="lang">d</span>.</p>
  42. <p><span class="def">int msecs(datetime d)</span> returns the number of milliseconds
  43. since midnight contained in the <span class="lang">datetime</span> value <span class="lang">d</span>.</p>
  44. <p><span class="def">datetime mkdt(int days, int msecs)</span> calculates the
  45. datetime value from <span class="lang">days</span> and <span class="lang">msecs</span>
  46. parameters. <span class="lang">Days</span> is the number of days since the beginning
  47. of the calendar, and <span class="lang">msecs</span> is the number of milliseconds
  48. since midnight. No checks are made for validity of these values. There exists
  49. an easier way to build a datetime value using <span class="lang">encodedate()</span>
  50. and <span class="lang">encodetime()</span> functions having the year, month and
  51. day numbers, as well as (not necessarily) the hour, minute, second and millisecond
  52. values.</p>
  53. <p><span class="def">bool isvalid(datetime d)</span> checks a <span class="lang">datetime</span>
  54. value for validity. The value of <span class="lang">d</span> is valid if it holds
  55. a time stamp between 01/01/0001 and 12/31/9999.</p>
  56. <p><span class="def">void tzupdate()</span> updates the internal timezone information,
  57. which affects the value of local time returned by <span class="lang">now()</span>
  58. and <span class="lang">nowstring()</span>. If your application is supposed to
  59. be running infinitely (e.g. if it's a network daemon), you might want to update
  60. the internal timezone information from time to time in order to return correct
  61. local time to the user on DST adjustment days. Depending on the precision of local
  62. time you wish to show to the user, you can call this function, for example, every
  63. minute or every hour. Without this, the local time may become incorrect at the
  64. moment of DST adjustment, which occurs twice a year in most countries.</p>
  65. <p><span class="def">int tzoffset()</span> returns the time zone offset in minutes.
  66. This value is negative in the West. Multiplying this value by 60000 (i.e. the
  67. offset in milliseconds) and adding it to the UTC <span class="lang">datetime</span>
  68. value will give the local time.</p>
  69. <p><span class="def">string dttostring(datetime d, const char* fmt)</span> converts
  70. a <span class="lang">datetime</span> value to string representation as specified
  71. by <span class="lang">fmt</span>. The syntax of the format specifier is the same
  72. as for <span class="lang">strftime()</span> (please, refer to the corresponding
  73. manual pages in your programming environment). Note that there might be slight
  74. incompatibilities between different implementations of <span class="lang">strftime()</span>.
  75. </p>
  76. <p><span class="def">string nowstring(const char* fmt, bool utc = true)</span>
  77. returns a string representing the current time in a format specified by <span class="lang">fmt</span>.
  78. <span class="lang">Utc</span> specifies whether the local time or the UTC time
  79. is required. Like for <span class="lang">dttostring()</span>, the syntax of the
  80. format specifier <span class="lang">fmt</span> is the same as for the system function
  81. <span class="lang">strftime()</span>.</p>
  82. <p><span class="def">datetime utodatetime(time_t u)</span> converts UNIX <span class="lang">time_t</span>
  83. value to PTypes <span class="lang">datetime</span>.</p>
  84. <p class="seealso">See also: <a href="time.calendar.html">Date/calendar manipulation</a>,
  85. <a href="time.time.html">Time manipulation</a></p>
  86. <!-- #EndEditable -->
  87. <hr size="1">
  88. <a href="../index.html" class="ns">PTypes home</a>
  89. </body>
  90. <!-- #EndTemplate --></html>