OpenEuphoria

Pastey std/datetime.e || creole

• Posted by _tom (admin) Sep 24, 2019

Date and Time

GMT is "Greenwich Mean Time." UTC is "Universal Coordinated Time."

GMT is for nostalgic sailors that remember square rigged vessels. UTC is the modern standard. (GMT and UTC are not exactly equivalent.)

Localized Variables

month_names

include datetime.e 
namespace datetime 
public sequence month_names 

Month Names

month_abbrs

include datetime.e 
namespace datetime 
public sequence month_abbrs 

Abbreviations of Month Names

day_names

include datetime.e 
namespace datetime 
public sequence day_names 

Day Names

day_abbrs

include datetime.e 
namespace datetime 
public sequence day_abbrs 

Abbreviations of Day Names

ampm

include datetime.e 
namespace datetime 
public sequence ampm 

AM and PM

Date and Time Type Accessors

These accessors can be used with the datetime type.

YEAR

include datetime.e 
namespace datetime 
public enum YEAR 

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

MONTH

include datetime.e 
namespace datetime 
public enum MONTH 

Month (1-12)

DAY

include datetime.e 
namespace datetime 
public enum DAY 

Day (1-31)

HOUR

include datetime.e 
namespace datetime 
public enum HOUR 

Hour (0-23)

MINUTE

include datetime.e 
namespace datetime 
public enum MINUTE 

Minute (0-59)

SECOND

include datetime.e 
namespace datetime 
public enum SECOND 

Second (0-59)

Intervals

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

YEARS

include datetime.e 
namespace datetime 
public enum YEARS 

Years

MONTHS

include datetime.e 
namespace datetime 
public enum MONTHS 

Months

WEEKS

include datetime.e 
namespace datetime 
public enum WEEKS 

Weeks

DAYS

include datetime.e 
namespace datetime 
public enum DAYS 

Days

HOURS

include datetime.e 
namespace datetime 
public enum HOURS 

Hours

MINUTES

include datetime.e 
namespace datetime 
public enum MINUTES 

Minutes

SECONDS

include datetime.e 
namespace datetime 
public enum SECONDS 

Seconds

DATE

include datetime.e 
namespace datetime 
public enum DATE 

Date

Types

datetime

include 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 is a sequence of length six in the form {year, month, day_of_month, hour, minute, second}. Checks are made to guarantee those values are in range.

datetime can be used to declare a variable as a datetime type, or used to check if a variable is a datetime type.

Note:

All items must be integers except for seconds which could either integer or atom values.

Example 1:

include std/datetime.e   
datetime x = now() -- x is a datetime variable, and now() returns a datetime  
? x 
--> {2019,9,8,3,23,23} 
 
? datetime(x) -- is it a datetime variable?   
--> 1         -- True  

Example 2:

include std/datetime.e   
object y = {2019,1,10} -- y is not a datetime variable, just a sequence containing a date {year,month,day} 
? y 
--> {2019,1,10}   
 
? datetime(y) -- is it a datetime variable?   
--> 0         -- False   

Example 3:

include std/datetime.e   
datetime z = {2019,1,10} -- z is declared as a datetime type; it is validated on assignment 
-- Since what we assigned was not a valid datetime variable, we get an error. 
 
Result: 
type_check failure, z is {2019,1,1} 

Routines

time

<built-in> function time() 

returns 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

date

<built-in> function date() 

returns 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, and so on.

Example 1:

include std/datetime.e 
sequence now = date() 
? now 
--> {95,3,24,23,47,38,6,83} 
-- Friday March 24, 1995 at 11:47:38pm, day 83 of the year 

See Also:

time, now

from_date

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

converts 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:

include std/datetime.e 
 
sequence a_date 
datetime today 
 
a_date = date() 
today = from_date(a_date) 
 
? a_date 
--> {119,9,20,21,0,57,6,263} 
 
? today 
--> {2019,9,20,21,0,57} 

See Also:

date, from_unix, now, new

now

include datetime.e 
namespace datetime 
public function now() 

creates 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:

include std/datetime.e 
datetime dt = now() 
? dt 
--> {2019,09,19,8,47,13} 

See Also:

from_date, from_unix, new, new_time, now_gmt

now_gmt

include datetime.e 
namespace datetime 
public function now_gmt() 

create a new datetime value that falls into the Greenwich Mean Time (GMT) timezone.

Comments:

This function will return a datetime that is GMT no matter what timezone the system is running under.

Example 1:

include std/datetime.e 
datetime lt = now() -- local time 
datetime gmt = now_gmt() 
? lt 
--> {2019,9,23,11,3,42} 
  
? gmt 
--> {2019,9,23,16,3,42} 
 
Note: that this example was run by someone 
in the Central Standard Timezone. 

See Also:

now

new

include 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) 

creates 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

new_time

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

creates 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:

include std/datetime.e 
sequence dt = new_time(10, 30, 55) 
-- dt is 10:30:55 AM 

See Also:

from_date, from_unix, now, new

weeks_day

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

gets 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:

include std/datetime.e 
sequence d = new(2008, 5, 2, 0, 0, 0) 
atom day = weeks_day(d)  
? day 
-- day is 6 because May 2, 2008 is a Friday. 

years_day

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

gets 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:

include std/datetime.e 
sequence d = new(2008, 5, 2, 0, 0, 0) 
atom day = years_day(d) 
-- day is 123 

is_leap_year

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

determines 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:

include std/datetime.e 
sequence d = new(2008, 1, 1, 0, 0, 0) 
? is_leap_year(d) -->  prints 1  -- True 
 
d = new(2005, 1, 1, 0, 0, 0) 
? is_leap_year(d) -- prints 0    -- False 

See Also:

days_in_month

days_in_month

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

returns the number of days in the month of dt.

Comments:

This takes into account leap year.

Parameters:

1. dt : a datetime to be queried.

Example 1:

include std/datetime.e 
sequence d = new(2008, 1, 1, 0, 0, 0) 
? days_in_month(d) --> 31 
 
d = new(2008, 2, 1, 0, 0, 0) -- a leap year 
? days_in_month(d) --> 29 

See Also:

is_leap_year

days_in_year

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

returns the number of days in the year of dt.

Comments:

This takes into account leap year.

Parameters:

1. dt : a datetime to be queried.

Example 1:

include std/datetime.e 
sequence d = new(2007, 1, 1, 0, 0, 0) 
? days_in_year(d) --> 365 
 
d = new(2008, 1, 1, 0, 0, 0) -- a leap year 
? days_in_year(d) --> 366 

See Also:

is_leap_year, days_in_month

to_unix

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

converts 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:

include std/datetime.e 
atom secs_since_epoch = to_unix(now()) 
? secs_since_epoch 
--> secs_since_epoch is equal to the current seconds since epoch 

See Also:

from_unix, format

from_unix

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

creates 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:

include std/datetime.e 
atom d = from_unix(0) 
? d 
--> d is 1970-01-01 00:00:00  (zero seconds since EPOCH) 

See Also:

to_unix, from_date, now, new

format

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

formats 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:

include std/datetime.e 
sequence d = new(2008, 5, 2, 12, 58, 32) 
sequence s = format(d, "%Y-%m-%d %H:%M:%S") 
--> s is "2008-05-02 12:58:32" 

Example 2:

include std/datetime.e 
sequence d = new(2008, 5, 2, 12, 58, 32) 
sequence s = format(d, "%A, %B %d '%y %H:%M%p") 
--> s is "Friday, May 2 '08 12:58PM" 

See Also:

to_unix, parse

parse

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

parses 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

Note:

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

Example 1:

include std/datetime.e 
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:

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

See Also:

format

add

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

adds 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 and Time for a reference of valid intervals.

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

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:

include std/datetime.e 
datetime d1, d2 
d1 = now() 
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

subtract

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

subtracts 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 and Time for a reference of valid intervals.

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

Example 1:

include std/datetime.e 
datetime dt1, dt2 
dt1 = now() 
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

diff

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

computes 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:

include std/datetime.e 
datetime d1 = now() 
sleep(15)  -- sleep for 15 seconds 
datetime d2 = now() 
 
integer i = diff(d1, d2) -- i is 15 

See Also:

add, subtract