OpenEuphoria

8.4 Date/Time

8.4.1 Localized Variables

8.4.1.1 month_names

include std/datetime.e
namespace datetime
public sequence month_names

Names of the months

8.4.1.2 month_abbrs

include std/datetime.e
namespace datetime
public sequence month_abbrs

Abbreviations of month names

8.4.1.3 day_names

include std/datetime.e
namespace datetime
public sequence day_names

Names of the days

8.4.1.4 day_abbrs

include std/datetime.e
namespace datetime
public sequence day_abbrs

Abbreviations of day names

8.4.1.5 ampm

include std/datetime.e
namespace datetime
public sequence ampm

AM/PM

8.4.2 Date/Time type Accessors

These accessors can be used with the datetime type.

8.4.2.1 YEAR

include std/datetime.e
namespace datetime
public enum YEAR

Year (full year, i.e. 2010, 1922, )

8.4.2.2 MONTH

include std/datetime.e
namespace datetime
public enum MONTH

Month (1-12)

8.4.2.3 DAY

include std/datetime.e
namespace datetime
public enum DAY

Day (1-31)

8.4.2.4 HOUR

include std/datetime.e
namespace datetime
public enum HOUR

Hour (0-23)

8.4.2.5 MINUTE

include std/datetime.e
namespace datetime
public enum MINUTE

Minute (0-59)

8.4.2.6 SECOND

include std/datetime.e
namespace datetime
public enum SECOND

Second (0-59)

8.4.3 Intervals

These constant enums are to be used with the add and subtract routines.

8.4.3.1 YEARS

include std/datetime.e
namespace datetime
public enum YEARS

Years

8.4.3.2 MONTHS

include std/datetime.e
namespace datetime
public enum MONTHS

Months

8.4.3.3 WEEKS

include std/datetime.e
namespace datetime
public enum WEEKS

Weeks

8.4.3.4 DAYS

include std/datetime.e
namespace datetime
public enum DAYS

Days

8.4.3.5 HOURS

include std/datetime.e
namespace datetime
public enum HOURS

Hours

8.4.3.6 MINUTES

include std/datetime.e
namespace datetime
public enum MINUTES

Minutes

8.4.3.7 SECONDS

include std/datetime.e
namespace datetime
public enum SECONDS

Seconds

8.4.3.8 DATE

include std/datetime.e
namespace datetime
public enum DATE

Date

8.4.4 Types

8.4.4.1 datetime

include std/datetime.e
namespace datetime
public type datetime(object o)

datetime type

Parameters:

1. obj : any object, so no crash takes place.

Comments:

A datetime type consists of a sequence of length 6 in the form {year, month, day_of_month, hour, minute, second}. Checks are made to guarantee those values are in range.

Note:

All components must be integers except seconds, as those can also be floating point values.

8.4.5 Routines

8.4.5.1 time

<built-in> function time()

Return the number of seconds since some fixed point in the past.

Returns:

An atom, which represents an absolute number of seconds.

Comments:

Take the difference between two readings of time(), to measure, for example, how long a section of code takes to execute.

On some machines, time() can return a negative number. However, you can still use the difference in calls to time() to measure elapsed time.

Example 1:

constant ITERATIONS = 1000000
integer p
atom t0, loop_overhead

t0 = time()
for i = 1 to ITERATIONS do
    -- time an empty loop
end for
loop_overhead = time() - t0

t0 = time()
for i = 1 to ITERATIONS do
    p = power(2, 20)
end for
? (time() - t0 - loop_overhead)/ITERATIONS
-- calculates time (in seconds) for one call to power

See Also:

date, now

8.4.5.2 date

<built-in> function date()

Return a sequence with information on the current date.

Returns:

A sequence of length 8, laid out as follows:

1. year -- since 1900
2. month -- January = 1
3. day -- day of month, starting at 1
4. hour -- 0 to 23
5. minute -- 0 to 59
6. second -- 0 to 59
7. day of the week -- Sunday = 1
8. day of the year -- January 1st = 1

Comments:

The value returned for the year is actually the number of years since 1900 (not the last 2 digits of the year). In the year 2000 this value was 100. In 2001 it was 101, etc.

Example 1:

now = date()
-- now has: {95,3,24,23,47,38,6,83}
-- i.e. Friday March 24, 1995 at 11:47:38pm, day 83 of the year

See Also:

time, now

8.4.5.3 from_date

include std/datetime.e
namespace datetime
public function from_date(sequence src)

Convert a sequence formatted according to the built-in date() function to a valid datetime sequence.

Parameters:

1. src : a sequence which date() might have returned

Returns:

A sequence, more precisely a datetime corresponding to the same moment in time.

Example 1:

d = from_date(date())
-- d is the current date and time

See Also:

date, from_unix, now, new

8.4.5.4 now

include std/datetime.e
namespace datetime
public function now()

Create a new datetime value initialized with the current date and time

Returns:

A sequence, more precisely a datetime corresponding to the current moment in time.

Example 1:

dt = now()
-- dt is the current date and time

See Also:

from_date, from_unix, new, new_time, now_gmt

8.4.5.5 now_gmt

include std/datetime.e
namespace datetime
public function now_gmt()

Create a new datetime value that falls into the Greenwich Mean Time (GMT) timezone. This function will return a datetime that is GMT, no matter what timezone the system is running under.

Example 1:

dt = now_gmt()
-- If local time was July 16th, 2008 at 10:34pm CST
-- dt would be July 17th, 2008 at 03:34pm GMT

See Also:

now

8.4.5.6 new

include std/datetime.e
namespace datetime
public function new(integer year = 0, integer month = 0, integer day = 0, integer hour = 0,
        integer minute = 0, atom second = 0)

Create a new datetime value.

Parameters:

1. year -- the full year.
2. month -- the month (1-12).
3. day -- the day of the month (1-31).
4. hour -- the hour (0-23) (defaults to 0)
5. minute -- the minute (0-59) (defaults to 0)
6. second -- the second (0-59) (defaults to 0)

Example 1:

dt = new(2010, 1, 1, 0, 0, 0)
-- dt is Jan 1st, 2010

See Also:

from_date, from_unix, now, new_time

8.4.5.7 new_time

include std/datetime.e
namespace datetime
public function new_time(integer hour, integer minute, atom second)

Create a new datetime value with a date of zeros.

Parameters:

1. hour : is the hour (0-23)
2. minute : is the minute (0-59)
3. second : is the second (0-59)

Example 1:

dt = new_time(10, 30, 55)
dt is 10:30:55 AM

See Also:

from_date, from_unix, now, new

8.4.5.8 weeks_day

include std/datetime.e
namespace datetime
public function weeks_day(datetime dt)

Get the day of week of the datetime dt.

Parameters:

1. dt : a datetime to be queried.

Returns:

An integer, between 1 (Sunday) and 7 (Saturday).

Example 1:

d = new(2008, 5, 2, 0, 0, 0)
day = weeks_day(d) -- day is 6 because May 2, 2008 is a Friday.

8.4.5.9 years_day

include std/datetime.e
namespace datetime
public function years_day(datetime dt)

Get the Julian day of year of the supplied date.

Parameters:

1. dt : a datetime to be queried.

Returns:

An integer, between 1 and 366.

Comments:

For dates earlier than 1800, this routine may give inaccurate results if the date applies to a country other than United Kingdom or a former colony thereof. The change from Julian to Gregorian calendar took place much earlier in some other European countries.

Example 1:

d = new(2008, 5, 2, 0, 0, 0)
day = years_day(d) -- day is 123

8.4.5.10 is_leap_year

include std/datetime.e
namespace datetime
public function is_leap_year(datetime dt)

Determine if dt falls within leap year.

Parameters:

1. dt : a datetime to be queried.

Returns:

An integer, of 1 if leap year, otherwise 0.

Example 1:

d = new(2008, 1, 1, 0, 0, 0)
? is_leap_year(d) -- prints 1
d = new(2005, 1, 1, 0, 0, 0)
? is_leap_year(d) -- prints 0

See Also:

days_in_month

8.4.5.11 days_in_month

include std/datetime.e
namespace datetime
public function days_in_month(datetime dt)

Return the number of days in the month of dt.

This takes into account leap year.

Parameters:

1. dt : a datetime to be queried.

Example 1:

d = new(2008, 1, 1, 0, 0, 0)
? days_in_month(d) -- 31
d = new(2008, 2, 1, 0, 0, 0) -- Leap year
? days_in_month(d) -- 29

See Also:

is_leap_year

8.4.5.12 days_in_year

include std/datetime.e
namespace datetime
public function days_in_year(datetime dt)

Return the number of days in the year of dt.

This takes into account leap year.

Parameters:

1. dt : a datetime to be queried.

Example 1:

d = new(2007, 1, 1, 0, 0, 0)
? days_in_year(d) -- 365
d = new(2008, 1, 1, 0, 0, 0) -- leap year
? days_in_year(d) -- 366

See Also:

is_leap_year, days_in_month

8.4.5.13 to_unix

include std/datetime.e
namespace datetime
public function to_unix(datetime dt)

Convert a datetime value to the unix numeric format (seconds since EPOCH_1970)

Parameters:

1. dt : a datetime to be queried.

Returns:

An atom, so this will not overflow during the winter 2038-2039.

Example 1:

secs_since_epoch = to_unix(now())
-- secs_since_epoch is equal to the current seconds since epoch

See Also:

from_unix, format

8.4.5.14 from_unix

include std/datetime.e
namespace datetime
public function from_unix(atom unix)

Create a datetime value from the unix numeric format (seconds since EPOCH)

Parameters:

1. unix : an atom, counting seconds elapsed since EPOCH.

Returns:

A sequence, more precisely a datetime representing the same moment in time.

Example 1:

d = from_unix(0)
-- d is 1970-01-01 00:00:00  (zero seconds since EPOCH)

See Also:

to_unix, from_date, now, new

8.4.5.15 format

include std/datetime.e
namespace datetime
public function format(datetime d, sequence pattern = "%Y-%m-%d %H:%M:%S")

Format the date according to the format pattern string

Parameters:

1. d : a datetime which is to be printed out
2. pattern : a format string, similar to the ones sprintf() uses, but with some Unicode encoding. The default is "%Y-%m-%d %H:%M:%S".

Returns:

A string, with the date d formatted according to the specification in pattern.

Comments:

Pattern string can include the following specifiers:

• %% -- a literal %
• %a -- locale's abbreviated weekday name (e.g., Sun)
• %A -- locale's full weekday name (e.g., Sunday)
• %b -- locale's abbreviated month name (e.g., Jan)
• %B -- locale's full month name (e.g., January)
• %C -- century; like %Y, except omit last two digits (e.g., 21)
• %d -- day of month (e.g, 01)
• %H -- hour (00..23)
• %I -- hour (01..12)
• %j -- day of year (001..366)
• %k -- hour ( 0..23)
• %l -- hour ( 1..12)
• %m -- month (01..12)
• %M -- minute (00..59)
• %p -- locale's equivalent of either AM or PM; blank if not known
• %P -- like %p, but lower case
• %s -- seconds since 1970-01-01 00:00:00 UTC
• %S -- second (00..60)
• %u -- day of week (1..7); 1 is Monday
• %w -- day of week (0..6); 0 is Sunday
• %y -- last two digits of year (00..99)
• %Y -- year

Example 1:

d = new(2008, 5, 2, 12, 58, 32)
s = format(d, "%Y-%m-%d %H:%M:%S")
-- s is "2008-05-02 12:58:32"

Example 2:

d = new(2008, 5, 2, 12, 58, 32)
s = format(d, "%A, %B %d '%y %H:%M%p")
-- s is "Friday, May 2 '08 12:58PM"

See Also:

to_unix, parse

8.4.5.16 parse

include std/datetime.e
namespace datetime
public function parse(sequence val, sequence fmt = "%Y-%m-%d %H:%M:%S",
        integer yylower = - 80)

Parse a datetime string according to the given format.

Parameters:

1. val : string datetime value
2. fmt : datetime format. Default is "%Y-%m-%d %H:%M:%S"
3. yysplit : Set the maximum difference from the current year when parsing a two digit year. Defaults to -80/+20.

Returns:

A datetime, value.

Comments:

Only a subset of the format specification is currently supported:

• %d -- day of month (e.g, 01)
• %H -- hour (00..23)
• %m -- month (01..12)
• %M -- minute (00..59)
• %S -- second (00..60)
• %y -- 2-digit year (YY)
• %Y -- 4-digit year (CCYY)

More format codes will be added in future versions.

All non-format characters in the format string are ignored and are not matched against the input string.

All non-digits in the input string are ignored.

Parsing Two Digit Years:

When parsing a two digit year parse has to make a decision if a given year is in the past or future. For example, 10/18/44. Is that Oct 18, 1944 or Oct 18, 2044. A common rule has come about for this purpose and that is the -80/+20 rule. Based on research it was found that more historical events are recorded than future events, thus it favors history rather than future. Some other applications may require a different rule, thus the yylower parameter can be supplied.

Assuming today is 12/22/2010 here is an example of the -80/+20 rule

YY	Diff	CCYY
18	-92/+8	2018
95	-15/+85	1995
33	-77/+23	1933
29	-81/+19	2029

Another rule in use is the -50/+50 rule. Therefore, if you supply -50 to the yylower to set the lower bounds, some examples may be (given that today is 12/22/2010)

YY	Diff	CCYY
18	-92/+8	2018
95	-15/+85	1995
33	-77/+23	2033
29	-81/+19	2029

Example 1:

datetime d = parse("05/01/2009 10:20:30", "%m/%d/%Y %H:%M:%S")
-- d is { 2009, 5, 1, 10, 20, 30 }

Example 2:

datetime d = parse("05/01/44", "%m/%d/%y", -50) -- -50/+50 rule
-- d is { 2044, 5, 14, 0, 0, 0 }

Versioning:

• Since 4.0.1 - 2-digit year parsing and yylower parameter

See Also:

format

8.4.5.17 add

include std/datetime.e
namespace datetime
public function add(datetime dt, object qty, integer interval)

Add a number of intervals to a datetime.

Parameters:

1. dt : the base datetime
2. qty : the number of intervals to add. It should be positive.
3. interval : which kind of interval to add.

Returns:

A sequence, more precisely a datetime representing the new moment in time.

Comments:

Please see Constants for Date/Time for a reference of valid intervals.

Do not confuse the item access constants such as YEAR, MONTH, DAY, etc... with the interval constants YEARS, MONTHS, DAYS, etc...

When adding MONTHS, it is a calendar based addition. For instance, a date of 5/2/2008 with 5 MONTHS added will become 10/2/2008. MONTHS does not compute the number of days per each month and the average number of days per month.

When adding YEARS, leap year is taken into account. Adding 4 YEARS to a date may result in a different day of month number due to leap year.

Example 1:

d2 = add(d1, 35, SECONDS) -- add 35 seconds to d1
d2 = add(d1, 7, WEEKS)    -- add 7 weeks to d1
d2 = add(d1, 19, YEARS)   -- add 19 years to d1

See Also:

subtract, diff

8.4.5.18 subtract

include std/datetime.e
namespace datetime
public function subtract(datetime dt, atom qty, integer interval)

Subtract a number of intervals to a base datetime.

Parameters:

1. dt : the base datetime
2. qty : the number of intervals to subtract. It should be positive.
3. interval : which kind of interval to subtract.

Returns:

A sequence, more precisely a datetime representing the new moment in time.

Comments:

Please see Constants for Date/Time for a reference of valid intervals.

See the function add() for more information on adding and subtracting date intervals

Example 1:

dt2 = subtract(dt1, 18, MINUTES) -- subtract 18 minutes from dt1
dt2 = subtract(dt1, 7, MONTHS)   -- subtract 7 months from dt1
dt2 = subtract(dt1, 12, HOURS)   -- subtract 12 hours from dt1

See Also:

add, diff

8.4.5.19 diff

include std/datetime.e
namespace datetime
public function diff(datetime dt1, datetime dt2)

Compute the difference, in seconds, between two dates.

Parameters:

1. dt1 : the end datetime
2. dt2 : the start datetime

Returns:

An atom, the number of seconds elapsed from dt2 to dt1.

Comments:

dt2 is subtracted from dt1, therefore, you can come up with a negative value.

Example 1:

d1 = now()
sleep(15)  -- sleep for 15 seconds
d2 = now()

i = diff(d1, d2) -- i is 15

See Also:

add, subtract