OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.3 Console | Up: 8 API Reference | 8.5 File System > | 9 Release Notes >>

## 8.4 Date and Time

### 8.4.1 Localized Variables

#### 8.4.1.1 month_names

    include std/datetime.e
    namespace datetime
    public sequence month_names

Month Names

#### 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

Day Names

#### 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 and PM

### 8.4.2 Date and 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 six in the form `{year, month, day_of_month, hour, minute, second}`. Checks are made to guarantee those values are in range.

##### Note:

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

### 8.4.5 Routines

#### 8.4.5.1 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

#### 8.4.5.2 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:

    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)

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:

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

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 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.

##### Comments:

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)

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

#### 8.4.5.7 new_time

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

    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)

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:

    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)

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:

    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)

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:

    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)

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:

    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)

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:

    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)

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:

    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)

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:

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

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:

    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)

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:

    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 }

##### See Also:

format

#### 8.4.5.17 add

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

    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)

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:

    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)

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:

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

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

##### See Also:

add, subtract

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.3 Console | Up: 8 API Reference | 8.5 File System > | 9 Release Notes >>