Table of Contents
This chapter discusses methods and properties of the time class that support
manipulation of strings representing date and time in various formats.
Before discussing how to initialize and use a time class variable, it
is a good idea to say a few things about how date and time is internally
represented by operating systems.
In general, a certain time point is identified by a computer as the number of seconds (or ticks, one tick is 1/60th of a second) from a certain "time zero" or " epoch time", which varies from system to system. In many UNIX version this corresponds to 00:00:00 GMT (Greenwich Mean Time) of January 1, 1970. On Mac OS time zero is midnight of January 1st, 1904. Biferno adopts the convention of using 00:00:00 of January 1, 1970 as the time zero for the time class.
The above technique to represent an instant in time, i.e. a date including the time with second precision, is called timestamping.
Initializing a time class variable means to create an object associated to
a certain timestamp. The constructor of the time class has the following
prototype:
time(string timeString = current, string formatString)
To associate the current server date and time to a variable, we will write:
<?
now = time()
?>
If we print the now variable we obtain an output similar to the following:
23-07-2001 16:40:49
This is the string representation of the current timestamp when the variable was initialized. This string is returned by the implicit string conversion method of the time class. A time class variable can also be initialized passing to the constructor a string representing a valid date and time, and an optional format string. In this case the created object is associated to the timestamp corresponding to the specified date. If the string supplied to the constructor doe not correspond to a valid date, an error message is generated. An example is:
<?
date1 = time("24-3-1974")
date2 = time("24/3/1974 15:30", "d/m/y")
date3 = time("3-24-1974 15.30.00", "m-d-y h.")
?>
The format string, if present, determines the order in which day (d), month
(m) and year (y) appear in the date string and the separator character used
(typically a dash or slash, other characters can be used). The hours,
minutes, seconds separator can be specified after the h character (see
third line in the previous example). The default format depends on the
default OS settings. This value can be altered by modifying the application
variable DATE_FORMAT in the "Biferno.config.bfr" configuration file and
assigning it the format string that we want as default for our application.
An example is:
DATE_FORMAT = "y/m/d h:"
Dates that fall between Biferno's time zero and December 31st, 2036 are handled correctly by Biferno. A date outside of these bounds can be passed to the constructor of the time class, but some properties and methods, in particular those executing conversions and formatting, may report erroneous data.
Date and time information can be obtained from a time class variable in
several formats. The Date and Hour methods return a string containing the
date and time corresponding, respectively, to the timestamp of the
variable, as in:
<? now = time() ?> <html> <body> Good morning.<br>It is $now.Hour()$ o'clock of $now.Date()$. </body> </html>
This script produces and output similar to the following:
Good morning. It is 10:12:43 o'clock of 24-07-2001.
To obtain more specific information from a time class variable a number of
properties are available that contain the separate numerical values of day
(day), month (month), year (year), hour (hour), minutes (minute) and
seconds (second).
The day of the week that corresponds to a particular date is represented by
the dayOfWeek property, which contains a numerical index ranging from 1
(Sunday) to 7 (Saturday); the indices correspond to the sunday, monday,
tuesday, wednesday, thursday, friday, saturday constants of the time class.
Operations on dates and times are also supported. The individual elements of an object of the time class can be incremented or decremented, and dates and times can be added or subtracted. This example shows how to compute tomorrow's date:
<?
tomorrow = time()
tomorrow.day++ // Increment the current day by 1
?>
An alternative is:
<?
tomorrow = time()
tomorrow.hour += 24 // Add 24 hours to the current time
?>
To add two objects of the time class means to add the respective
timestamps. If the value resulting from an operation is outside of the
allowed range, the value is automatically adjusted, as in:
<?
tomorrow = time("31/1/2001")
tomorrow.day++ //the variable contains the value: 1/2/2001
?>
The ToSecs method of the time class returns the timestamp corresponding to the date
represented by the object, i.e. the number of seconds from Biferno's time zero. Notice that
the result is operating system dependent, and can be relative either to the current time zone
or to the Greenwich time zone (universal time).
The UString method returns a string containing date and time in the
Universal Time format. This method is normally used in combination with the
GMT method, which returns the timestamp value corresponding to the
Greenwich time zone, as in the following example:
<?
now = time()
$now.GMT().UString()
?>
The script will produce a result similar to the following:
Tue, 24 Jul 2001 10:48:25 GMT
Sometimes it is necessary to have the ability to format date and time in
very different ways. Towards this end the time class provides the Strftime
method, with prototype:
string Strftime(string format)
This methods returns a string containing date and time formatted on the
base of the specific format descriptor passed with the format parameter.
Table 14.1, “Format descriptors for the Strftime method” lists all descriptors that can be used with the
Strftime method together with their meaning.
Each descriptor consists in a percent symbol followed by a lowercase or
uppercase letter. Any other text in the format string is not interpreted
and is returned unaltered. A percent sign in the format string must be
escaped by using a percent sign in front of it. The following script shows
how to use the Strftime method and format descriptors.
<?
now = time()
print(now.Strftime("%a %B %d, %Y ore %X") + "<br>\n")
print(now.Strftime("%d-%m-%y %X") + "<br>\n")
print(now.Strftime("%d/%m/%Y %I:%M %p") + "<br>\n")
print(now.Strftime("%x (day %j of the year)") + "<br>\n")
print(now.Strftime("%a %b %d/%y (%W-th week)") + "<br>\n")
?>
This script, run at 15:50 on 30/7/2001, generated the following output:
Mon July 30, 2001 ore 15:50:20
30-07-01 15:50:20
30/07/2001 03:50 pm
Monday July 30 2001 (day 211 of the year)
Mon Jul 30/01 (31-th week)
Table 14.1. Format descriptors for the Strftime method
| Descriptor | Is replaced by... |
|---|---|
| %a | Abbreviated name of day of the week |
| %A | Complete name of day of the week |
| %b | Abbreviated name of month (also obtained with '%h') |
| %B | Complete name of month |
| %c | Date and time in standard format |
| %d | Day of the month as an integer number |
| %H | Time in 24-hour format (from 00 to 23) |
| %I | Time in 12-hour format (from 01 to 12) |
| %j | Day of the year as an integer number (from 001 to 365) |
| %m | Month as an integer number (from 01 to 12) |
| %M | Minutes in decimal format |
| %p | The AM or PM string, depending on the time |
| %S | Seconds in decimal format |
| %U | Week of the current year as an integer number (the first week of the year starts with the first Sunday of the year) |
| %W | Week of the current year as an integer number (the first week of the year starts with the first Monday of the year |
| %w | Day of the year as an integer number (from 0 to 6) |
| %x | Date in standard format |
| %X | Time in standard format |
| %y | Year with two digits |
| %Y | Year with four digits |
| %Z | The time zone or the standard abbreviation for the time zone |