1.36Class TimeStamp

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
addAdds a date value to this value (altering it).
changeZoneChange the time zone in this timestamp, maintaing the same absolute value.
compareCompare another TimeStamp against this one.
currentTimeFills this item with current time.
dayOfWeekReturns the weekday in which this TimeStamp falls.
dayOfYearReturns the days passed since the beginning of the year in this TimeStamp
distanceDetermines the distance between this item and a target timestamp.
fromLongFormatSets this date using a compressed opaque "long format" data.
fromRFC2822Sets this date from a RFC 2822 string.
isLeapYearChecks if the year in this TimeStamp is a LeapYear.
isValidChecks the validity of this TimeStamp.
toLongFormatReturns a compressed date representation.
toRFC2822Format this TimeStamp in RFC 2822 format.
toStringConverts the current timestamp to a string.

Properties

day

Day of month, starting from 1.

Day of month, starting from 1.

hour

Hour in range 0 - 23.

Hour in range 0 - 23.

minute

Minute in range 0 - 59.

Minute in range 0 - 59.

month

Month of the year, starting from 1.

Month of the year, starting from 1.

msec

Millisecond in range 0 - 999.

Millisecond in range 0 - 999.

second

Second in range 0 - 59.

Second in range 0 - 59.

timezone

A timezone code (see class).

A timezone code (see TimeZone class).

year

Timestamp year, absolute value.

Timestamp year, absolute value.

Methods

add

Adds a date value to this value (altering it).

TimeStamp.add( timestamp )
timestamp A timestamp to add
Returnitself.

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)

changeZone

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

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.

currentTime

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.

dayOfWeek

Returns the weekday in which this TimeStamp falls.

TimeStamp.dayOfWeek()
ReturnA 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.

dayOfYear

Returns the days passed since the beginning of the year in this TimeStamp

TimeStamp.dayOfYear()
ReturnA 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.

distance

Determines the distance between this item and a target timestamp.

TimeStamp.distance( timestamp )
timestamp The timestamp from which to calculate the distance.
Returnitself

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 )

fromLongFormat

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.

fromRFC2822

Sets this date from a RFC 2822 string.

TimeStamp.fromRFC2822( sTimestamp )
sTimestamp A string containing a date in RFC 2822 format.
ReturnTrue 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.

isLeapYear

Checks if the year in this TimeStamp is a LeapYear.

TimeStamp.isLeapYear()
ReturnTrue 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.

isValid

Checks the validity of this TimeStamp.

TimeStamp.isValid()
ReturnTrue 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.

toLongFormat

Returns a compressed date representation.

TimeStamp.toLongFormat()
ReturnA 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.

toRFC2822

Format this TimeStamp in RFC 2822 format.

TimeStamp.toRFC2822()
ReturnA string with this timestamp converted, or nil if this TimeStamp is not valid.

See also: TimeStamp.

toString

Converts the current timestamp to a string.

TimeStamp.toString( [format] )
format Date formatting pattern in strftime format.
ReturnThe 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).

Made with http://www.falconpl.org