<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class TimeStamp - Class TimeStamp</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class TimeStamp</h1>
<p class="faldoc_brief">Representation of times in the system. </p>
<p class="faldoc_funcdecl">
<b>class</b> TimeStamp( date )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#day">day</a></td><td>Day of month, starting from 1.</td></tr>
<tr><td><a href="#hour">hour</a></td><td>Hour in range 0 - 23.</td></tr>
<tr><td><a href="#minute">minute</a></td><td>Minute in range 0 - 59.</td></tr>
<tr><td><a href="#month">month</a></td><td>Month of the year, starting from 1.</td></tr>
<tr><td><a href="#msec">msec</a></td><td>Millisecond in range 0 - 999.</td></tr>
<tr><td><a href="#second">second</a></td><td>Second in range 0 - 59.</td></tr>
<tr><td><a href="#timezone">timezone</a></td><td>A timezone code (see class).</td></tr>
<tr><td><a href="#year">year</a></td><td>Timestamp year, absolute value.</td></tr>
<tr><td><a href="#add">add()</a></td><td>Adds a date value to this value (altering it). </td></tr>
<tr><td><a href="#changeZone">changeZone()</a></td><td>Change the time zone in this timestamp, maintaing the same absolute value. </td></tr>
<tr><td><a href="#compare">compare()</a></td><td>Compare another TimeStamp against this one. </td></tr>
<tr><td><a href="#currentTime">currentTime()</a></td><td>Fills this item with current time. </td></tr>
<tr><td><a href="#dayOfWeek">dayOfWeek()</a></td><td>Returns the weekday in which this TimeStamp falls. </td></tr>
<tr><td><a href="#dayOfYear">dayOfYear()</a></td><td>Returns the days passed since the beginning of the year in this TimeStamp </td></tr>
<tr><td><a href="#distance">distance()</a></td><td>Determines the distance between this item and a target timestamp. </td></tr>
<tr><td><a href="#fromLongFormat">fromLongFormat()</a></td><td>Sets this date using a compressed opaque "long format" data. </td></tr>
<tr><td><a href="#fromRFC2822">fromRFC2822()</a></td><td>Sets this date from a RFC 2822 string. </td></tr>
<tr><td><a href="#isLeapYear">isLeapYear()</a></td><td>Checks if the year in this TimeStamp is a LeapYear. </td></tr>
<tr><td><a href="#isValid">isValid()</a></td><td>Checks the validity of this TimeStamp. </td></tr>
<tr><td><a href="#toLongFormat">toLongFormat()</a></td><td>Returns a compressed date representation. </td></tr>
<tr><td><a href="#toRFC2822">toRFC2822()</a></td><td>Format this TimeStamp in RFC 2822 format. </td></tr>
<tr><td><a href="#toString">toString()</a></td><td>Converts the current timestamp to a string. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> TimeStamp( date )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">date</td><td class="faldoc_paramdesc">Other TimeStamp instance from which to copy the new instance. </td></tr>
</table>
<br/>
<p class="item_brief">Representation of times in the system. </p>
<p class="faldoc_text"> The TimeStamp class can be used to retrieve the system time and date. It is also used by other entities in the RTL to return informations about the date (i.e. the <a href="./class_FileStat.html">FileStat</a>). </p>
<p class="faldoc_text"> The instance is created empty and unset, unless the <b>date</b> parameter is provided. In that case, the new instance is copied from a previously created one. </p>
<p class="faldoc_text"> The provided parameter may also be a "long opaque format" generated by the <a href="./class_TimeStamp.html#toLongFormat">TimeStamp.toLongFormat</a> method. </p>
<p class="faldoc_text"> To update the instance with the current system time, use <a href="./class_TimeStamp.html#currentTime">TimeStamp.currentTime</a></p>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="day">day</a></h3>
<p class="item_brief">Day of month, starting from 1.</p>
<h3 class="faldoc_funcname"><a name="hour">hour</a></h3>
<p class="item_brief">Hour in range 0 - 23.</p>
<h3 class="faldoc_funcname"><a name="minute">minute</a></h3>
<p class="item_brief">Minute in range 0 - 59.</p>
<h3 class="faldoc_funcname"><a name="month">month</a></h3>
<p class="item_brief">Month of the year, starting from 1.</p>
<h3 class="faldoc_funcname"><a name="msec">msec</a></h3>
<p class="item_brief">Millisecond in range 0 - 999.</p>
<h3 class="faldoc_funcname"><a name="second">second</a></h3>
<p class="item_brief">Second in range 0 - 59.</p>
<h3 class="faldoc_funcname"><a name="timezone">timezone</a></h3>
<p class="item_brief">A timezone code (see class).</p>
<h3 class="faldoc_funcname"><a name="year">year</a></h3>
<p class="item_brief">Timestamp year, absolute value.</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="add">add()</a></h3>
<p class="item_brief">Adds a date value to this value (altering it). </p>
<p class="faldoc_funcdecl">TimeStamp.add( timestamp )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">timestamp</td><td class="faldoc_paramdesc">A timestamp to add </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">itself. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Alters this timestamp by adding another one to itself. Years, months, days, hours, minutes, seconds and milliseconds from the parameters are added, and the target date is re-validated. </p>
<p class="faldoc_text">To use this functionality without changing the contents of this instance, use the clone semantic: </p>
<pre class="faldoc_code">
added = orig.clone().add(addend)
</pre>
</p>
<h3 class="faldoc_funcname"><a name="changeZone">changeZone()</a></h3>
<p class="item_brief">Change the time zone in this timestamp, maintaing the same absolute value. </p>
<p class="faldoc_funcdecl">TimeStamp.changeZone( zone )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">zone</td><td class="faldoc_paramdesc">The new time zone. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This methods shifts forward or backward this timestamp according with the relative shift between the <a href="./class_TimeStamp.html#timezone">TimeStamp.timezone</a> member and the <b>zone</b> parameter. After the shift is performed, the new zone is set in the timezone property of this object. </p>
<p class="faldoc_text">For example, to convert the local time in GMT: </p>
<pre class="faldoc_code">
now = CurrentTime()
> "Local time: ", now
now.changeZone( TimeZone.GMT )
> "GMT: ", now
</pre>
<p class="faldoc_text"> As assigning a new time zone to the <b>timezone</b> property is not subject to any control, it is possible to set an arbitrary time and timezone by normal assignment, and then convert it to another time zone using this method. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
a_gmt_time = decodeTime( "..." )
// let's say we know the timestamp is GMT.
a_gmt_time.timezone = TimeZone.GMT
// to convert in local time:
localTime = a_gmt_time
localTime.changeZone( TimeZone.local )
</pre>
<p class="faldoc_text"> The "local" zone is a special zone which is automatically converted in the system timezone; it can also be directly assigned to a timestamp, but it's preferable to determine the system timezone through <a href="./class_TimeZone.html#getLocal">TimeZone.getLocal</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="compare">compare()</a></h3>
<p class="item_brief">Compare another TimeStamp against this one. </p>
<p class="faldoc_funcdecl">TimeStamp.compare( timestamp )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">timestamp</td><td class="faldoc_paramdesc">The TimeStamp to be compared. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">-1, 0 or 1. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The given timestamp is compared to this object. If this object is greater than the target timestamp, 1 is returned; if it's smaller (before), -1 is returned. If the two timestamp are exactly the same, 0 is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="currentTime">currentTime()</a></h3>
<p class="item_brief">Fills this item with current time. </p>
<p class="faldoc_funcdecl">TimeStamp.currentTime( )</p>
<p class="faldoc_text"><p class="faldoc_text">Fills the value of the date with the current local time on the system. Timezone management is still not implemented. </p>
</p>
<h3 class="faldoc_funcname"><a name="dayOfWeek">dayOfWeek()</a></h3>
<p class="item_brief">Returns the weekday in which this TimeStamp falls. </p>
<p class="faldoc_funcdecl">TimeStamp.dayOfWeek( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A number representing a day in the week. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the day of week calculated on this object. The returned number is in range 0 to 6 included, 0 being Sunday and 6 being Saturday. The function is reliable only for dates past January the first 1700. </p>
</p>
<h3 class="faldoc_funcname"><a name="dayOfYear">dayOfYear()</a></h3>
<p class="item_brief">Returns the days passed since the beginning of the year in this TimeStamp </p>
<p class="faldoc_funcdecl">TimeStamp.dayOfYear( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A number of days in the year. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the day in the year represented by the current object. The returned number will range between 1 for January the first and 365 or 366 (if the current year is leap) for December the 31th. </p>
</p>
<h3 class="faldoc_funcname"><a name="distance">distance()</a></h3>
<p class="item_brief">Determines the distance between this item and a target timestamp. </p>
<p class="faldoc_funcdecl">TimeStamp.distance( timestamp )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">timestamp</td><td class="faldoc_paramdesc">The timestamp from which to calculate the distance. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">itself </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The parameter is subtracted from the current object; the number of days, hours, minutes, seconds and milliseconds between the two dates is stored in the current object. The values may be negative if the given timestamp parameter is greater than this object. </p>
<p class="faldoc_text">To use this functionality without changing the contents of this instance, use the clone semantic: </p>
<pre class="faldoc_code">
distance = currentDate.clone().distance( baseDate )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="fromLongFormat">fromLongFormat()</a></h3>
<p class="item_brief">Sets this date using a compressed opaque "long format" data. </p>
<p class="faldoc_funcdecl">TimeStamp.fromLongFormat( )</p>
<p class="faldoc_text"><p class="faldoc_text">Fills the data in this object using a binary packed data which can be stored in a Falcon integer value (64 bits). A valid value can be only obtained with the toLongFormat() method. This two methods are just meant for easier serialization; timestamps in long format cannot be compared or summed. </p>
</p>
<h3 class="faldoc_funcname"><a name="fromRFC2822">fromRFC2822()</a></h3>
<p class="item_brief">Sets this date from a RFC 2822 string. </p>
<p class="faldoc_funcdecl">TimeStamp.fromRFC2822( sTimestamp )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sTimestamp</td><td class="faldoc_paramdesc">A string containing a date in RFC 2822 format. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True on success, false on failure. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">RFC 2822 format is the textual descriptive format used in Internet transactions. It's composed with: </p>
<ul>
<li>Day of the week signature </li><li>Month signature </li><li>Day in the current month </li><li>4 digits year </li><li>Time in HH:MM:SS format </li><li>Timezone name or displacement. </li>
</ul>
<p class="faldoc_text">A sample looks like: </p>
<pre class="faldoc_code">
Thu, 01 May 2008 23:52:34 +0200
</pre>
<p class="faldoc_text">If the given string is not a valid timestamp in the RFC 2822 format, the function will return false. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Part of this timestamp may be corrupted after a faulty try; be sure to save this TimeStamp before trying the conversion, if it is needed. </p>
</p>
<h3 class="faldoc_funcname"><a name="isLeapYear">isLeapYear()</a></h3>
<p class="item_brief">Checks if the year in this TimeStamp is a LeapYear. </p>
<p class="faldoc_funcdecl">TimeStamp.isLeapYear( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if this timestamp is in a leap year, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns true if year member of this timestamp is leap, false otherwise. Calculation is reliable only for years past 1700. </p>
</p>
<h3 class="faldoc_funcname"><a name="isValid">isValid()</a></h3>
<p class="item_brief">Checks the validity of this TimeStamp. </p>
<p class="faldoc_funcdecl">TimeStamp.isValid( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if this timestamp represents a valid moment in time. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns true if the data in the timestamp represents a valid date. The function takes into consideration leap years. </p>
</p>
<h3 class="faldoc_funcname"><a name="toLongFormat">toLongFormat()</a></h3>
<p class="item_brief">Returns a compressed date representation. </p>
<p class="faldoc_funcdecl">TimeStamp.toLongFormat( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A date in an opaque "long format". </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns a Falcon integer which contains packed binary data representing this object. The returned data is opaque and should not be used to compare different dates. </p>
</p>
<h3 class="faldoc_funcname"><a name="toRFC2822">toRFC2822()</a></h3>
<p class="item_brief">Format this TimeStamp in RFC 2822 format. </p>
<p class="faldoc_funcdecl">TimeStamp.toRFC2822( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string with this timestamp converted, or nil if this TimeStamp is not valid. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="toString">toString()</a></h3>
<p class="item_brief">Converts the current timestamp to a string. </p>
<p class="faldoc_funcdecl">TimeStamp.toString( [format] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">format</td><td class="faldoc_optparamdesc"> Date formatting pattern in <b>strftime</b> format. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The formatted timestamp. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns a string representation of the time stamp. The returned format is YYYY-MM-DD HH:MM:SS.mmm. This function is just meant as a basic way to represent timestamps on output. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> In version 0.8.x, The extra format parameter is internally passed to strftime() C standard function. Some compiler/C libraries may abort the program if the given format string is malformed. An internal re-implementation of the method will be available in the next versions; it will be granted to be compatible with strftime() and will offer falcon-specific formattings. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Some specific extra formats available in 0.8.x: %q (milliseconds), %Q (zero-padded milliseconds) and %i (Internet format, RFC-2822). </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
