Representation of times in the system.
Class TimeStamp( date )
| date | Other TimeStamp instance from which to copy the new instance. |
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 FileStat).
The instance is created empty and unset, unless the date parameter is provided. In that case, the new instance is copied from a previously created one.
The provided parameter may also be a "long opaque format" generated by the TimeStamp.toLongFormat method.
To update the instance with the current system time, use TimeStamp.currentTime
| Properties | |
| day | Day of month, starting from 1. |
| hour | Hour in range 0 - 23. |
| minute | Minute in range 0 - 59. |
| month | Month of the year, starting from 1. |
| msec | Millisecond in range 0 - 999. |
| second | Second in range 0 - 59. |
| timezone | A timezone code (see class). |
| year | Timestamp year, absolute value. |
| Methods | |
| add | Adds a date value to this value (altering it). |
| changeZone | Change the time zone in this timestamp, maintaing the same absolute value. |
| compare | Compare another TimeStamp against this one. |
| currentTime | Fills this item with current time. |
| dayOfWeek | Returns the weekday in which this TimeStamp falls. |
| dayOfYear | Returns the days passed since the beginning of the year in this TimeStamp |
| distance | Determines the distance between this item and a target timestamp. |
| fromLongFormat | Sets this date using a compressed opaque "long format" data. |
| fromRFC2822 | Sets this date from a RFC 2822 string. |
| isLeapYear | Checks if the year in this TimeStamp is a LeapYear. |
| isValid | Checks the validity of this TimeStamp. |
| toLongFormat | Returns a compressed date representation. |
| toRFC2822 | Format this TimeStamp in RFC 2822 format. |
| toString | Converts the current timestamp to a string. |
Day of month, starting from 1.
Day of month, starting from 1.
Hour in range 0 - 23.
Hour in range 0 - 23.
Minute in range 0 - 59.
Minute in range 0 - 59.
Month of the year, starting from 1.
Month of the year, starting from 1.
Millisecond in range 0 - 999.
Millisecond in range 0 - 999.
Second in range 0 - 59.
Second in range 0 - 59.
A timezone code (see class).
A timezone code (see TimeZone class).
Timestamp year, absolute value.
Timestamp year, absolute value.
Adds a date value to this value (altering it).
TimeStamp.add( timestamp )
| timestamp | A timestamp to add |
| Return | itself. |
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.
To use this functionality without changing the contents of this instance, use the clone semantic:
added = orig.clone().add(addend)
Change the time zone in this timestamp, maintaing the same absolute value.
TimeStamp.changeZone( zone )
| zone | The new time zone. |
This methods shifts forward or backward this timestamp according with the relative shift between the TimeStamp.timezone member and the zone parameter. After the shift is performed, the new zone is set in the timezone property of this object.
For example, to convert the local time in GMT:
now = CurrentTime()
> "Local time: ", now
now.changeZone( TimeZone.GMT )
> "GMT: ", now
As assigning a new time zone to the timezone 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.
For example:
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 )
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 TimeZone.getLocal.
See also: TimeZone.
Compare another TimeStamp against this one.
TimeStamp.compare( timestamp )
| timestamp | The TimeStamp to be compared. |
| Return | -1, 0 or 1. |
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.
Fills this item with current time.
TimeStamp.currentTime()
Fills the value of the date with the current local time on the system. Timezone management is still not implemented.
Returns the weekday in which this TimeStamp falls.
TimeStamp.dayOfWeek()
| Return | A number representing a day in the week. |
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.
Returns the days passed since the beginning of the year in this TimeStamp
TimeStamp.dayOfYear()
| Return | A number of days in the year. |
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.
Determines the distance between this item and a target timestamp.
TimeStamp.distance( timestamp )
| timestamp | The timestamp from which to calculate the distance. |
| Return | itself |
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.
To use this functionality without changing the contents of this instance, use the clone semantic:
distance = currentDate.clone().distance( baseDate )
Sets this date using a compressed opaque "long format" data.
TimeStamp.fromLongFormat()
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.
Sets this date from a RFC 2822 string.
TimeStamp.fromRFC2822( sTimestamp )
| sTimestamp | A string containing a date in RFC 2822 format. |
| Return | True on success, false on failure. |
RFC 2822 format is the textual descriptive format used in Internet transactions. It's composed with:
A sample looks like:
Thu, 01 May 2008 23:52:34 +0200
If the given string is not a valid timestamp in the RFC 2822 format, the function will return false.
Note: 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.
Checks if the year in this TimeStamp is a LeapYear.
TimeStamp.isLeapYear()
| Return | True if this timestamp is in a leap year, false otherwise. |
Returns true if year member of this timestamp is leap, false otherwise. Calculation is reliable only for years past 1700.
Checks the validity of this TimeStamp.
TimeStamp.isValid()
| Return | True if this timestamp represents a valid moment in time. |
Returns true if the data in the timestamp represents a valid date. The function takes into consideration leap years.
Returns a compressed date representation.
TimeStamp.toLongFormat()
| Return | A date in an opaque "long format". |
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.
Format this TimeStamp in RFC 2822 format.
TimeStamp.toRFC2822()
| Return | A string with this timestamp converted, or nil if this TimeStamp is not valid. |
See also: TimeStamp.
Converts the current timestamp to a string.
TimeStamp.toString( [format] )
| format | Date formatting pattern in strftime format. |
| Return | The formatted timestamp. |
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.
Note: 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.
Note: Some specific extra formats available in 0.8.x: %q (milliseconds), %Q (zero-padded milliseconds) and %i (Internet format, RFC-2822).