36.1 Timing Utilities

Octave’s core set of functions for manipulating time values are
patterned after the corresponding functions from the standard C library.
Several of these functions use a data structure for time that includes
the following elements:

usec

Microseconds after the second (0-999999).

sec

Seconds after the minute (0-60). This number can be 60 to account
for leap seconds.

min

Minutes after the hour (0-59).

hour

Hours since midnight (0-23).

mday

Day of the month (1-31).

mon

Months since January (0-11).

year

Years since 1900.

wday

Days since Sunday (0-6).

yday

Days since January 1 (0-365).

isdst

Daylight Savings Time flag.

zone

Time zone.

In the descriptions of the following functions, this structure is
referred to as a tm_struct.

Built-in Function: seconds =time()

Return the current time as the number of seconds since the epoch. The
epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan
1970. For example, on Monday February 17, 1997 at 07:15:06 CUT, the
value returned by time was 856163706.

Convert a value returned from time (or any other non-negative
integer), to the local time and return a string of the same form as
asctime. The function ctime (time) is equivalent to
asctime (localtime (time)). For example:

Format the time structure tm_struct in a flexible way using the
format string fmt that contains ‘%’ substitutions
similar to those in printf. Except where noted, substituted
fields have a fixed size; numeric fields are padded if necessary.
Padding is with zeros by default; for fields that display a single
number, padding can be changed or inhibited by following the ‘%’
with one of the modifiers described below. Unknown field specifiers are
copied as normal characters. All other characters are copied to the
output without change. For example:

Most of the remaining functions described in this section are not
patterned after the standard C library. Some are available for
compatibility with MATLAB and others are provided because they are
useful.

Function File: clock()

Return the current local date and time as a date vector. The date vector
contains the following fields: current year, month (1-12), day (1-31),
hour (0-23), minute (0-59), and second (0-61). The seconds field has
a fractional part after the decimal point for extended accuracy.

For example:

fix (clock ())
⇒ [ 1993, 8, 20, 4, 56, 1 ]

The function clock is more accurate on systems that have the
gettimeofday function.

Return the CPU time used by your Octave session. The first output is
the total time spent executing your process and is equal to the sum of
second and third outputs, which are the number of CPU seconds spent
executing in user mode and the number of CPU seconds spent executing in
system mode, respectively. If your system does not have a way to report
CPU time usage, cputime returns 0 for each of its output values.
Note that because Octave used some CPU time to start, it is reasonable
to check to see if cputime works by checking to see if the total
CPU time used is nonzero.

Set or check a wall-clock timer. Calling tic without an
output argument sets the internal timer state. Subsequent calls
to toc return the number of seconds since the timer was set.
For example,

tic ();
# many computations later…
elapsed_time = toc ();

will set the variable elapsed_time to the number of seconds since
the most recent call to the function tic.

If called with one output argument, tic returns a scalar
of type uint64 that may be later passed to toc.

id = tic; sleep (5); toc (id)
⇒ 5.0010

Calling tic and toc this way allows nested timing calls.

If you are more interested in the CPU time that your process used, you
should use the cputime function instead. The tic and
toc functions report the actual wall clock time that elapsed
between the calls. This may include time spent processing other jobs or
doing nothing at all.

Suspend the execution of the program. If invoked without any arguments,
Octave waits until you type a character. With a numeric argument, it
pauses for the given number of seconds. For example, the following
statement prints a message and then waits 5 seconds before clearing the
screen.

fprintf (stderr, "wait please...\n");
pause (5);
clc;

Built-in Function: sleep(seconds)

Suspend the execution of the program for the given number of seconds.

Built-in Function: usleep(microseconds)

Suspend the execution of the program for the given number of
microseconds. On systems where it is not possible to sleep for periods
of time less than one second, usleep will pause the execution for
round (microseconds / 1e6) seconds.

Function File: days =datenum(datevec)

Function File: days =datenum(year, month, day)

Function File: days =datenum(year, month, day, hour)

Function File: days =datenum(year, month, day, hour, minute)

Function File: days =datenum(year, month, day, hour, minute, second)

Function File: days =datenum("datestr")

Function File: days =datenum("datestr", p)

Function File: [days, secs] =datenum(…)

Return the date/time input as a serial day number, with Jan 1, 0000
defined as day 1.

The integer part, floor (days) counts the number of
complete days in the date input.

The fractional part, rem (days, 1) corresponds to the time
on the given day.

The input may be a date vector (see datevec),
datestr (see datestr), or directly specified as input.

When processing input datestrings, p is the year at the start of the
century to which two-digit years will be referenced. If not specified, it
defaults to the current year minus 50.

The optional output secs holds the time on the specified day with
greater precision than days.

Notes:

Years can be negative and/or fractional.

Months below 1 are considered to be January.

Days of the month start at 1.

Days beyond the end of the month go into subsequent months.

Days before the beginning of the month go to the previous month.

Days can be fractional.

Caution: this function does not attempt to handle Julian
calendars so dates before October 15, 1582 are wrong by as much
as eleven days. Also, be aware that only Roman Catholic countries
adopted the calendar in 1582. It took until 1924 for it to be
adopted everywhere. See the Wikipedia entry on the Gregorian
calendar for more details.

Warning: leap seconds are ignored. A table of leap seconds
is available on the Wikipedia entry for leap seconds.

Format the given date/time according to the format f and return
the result in str. date is a serial date number (see
datenum) or a date vector (see datevec). The value of
date may also be a string or cell array of strings.

f can be an integer which corresponds to one of the codes in
the table below, or a date format string.

p is the year at the start of the century in which two-digit years
are to be interpreted in. If not specified, it defaults to the current
year minus 50.

For example, the date 730736.65149 (2000-09-07 15:38:09.0934) would be
formatted as follows:

Code

Format

Example

0

dd-mmm-yyyy HH:MM:SS

07-Sep-2000 15:38:09

1

dd-mmm-yyyy

07-Sep-2000

2

mm/dd/yy

09/07/00

3

mmm

Sep

4

m

S

5

mm

09

6

mm/dd

09/07

7

dd

07

8

ddd

Thu

9

d

T

10

yyyy

2000

11

yy

00

12

mmmyy

Sep00

13

HH:MM:SS

15:38:09

14

HH:MM:SS PM

03:38:09 PM

15

HH:MM

15:38

16

HH:MM PM

03:38 PM

17

QQ-YY

Q3-00

18

QQ

Q3

19

dd/mm

07/09

20

dd/mm/yy

07/09/00

21

mmm.dd,yyyy HH:MM:SS

Sep.07,2000 15:38:08

22

mmm.dd,yyyy

Sep.07,2000

23

mm/dd/yyyy

09/07/2000

24

dd/mm/yyyy

07/09/2000

25

yy/mm/dd

00/09/07

26

yyyy/mm/dd

2000/09/07

27

QQ-YYYY

Q3-2000

28

mmmyyyy

Sep2000

29

yyyy-mm-dd

2000-09-07

30

yyyymmddTHHMMSS

20000907T153808

31

yyyy-mm-dd HH:MM:SS

2000-09-07 15:38:08

If f is a format string, the following symbols are recognized:

Symbol

Meaning

Example

yyyy

Full year

2005

yy

Two-digit year

05

mmmm

Full month name

December

mmm

Abbreviated month name

Dec

mm

Numeric month number (padded with zeros)

01, 08, 12

m

First letter of month name (capitalized)

D

dddd

Full weekday name

Sunday

ddd

Abbreviated weekday name

Sun

dd

Numeric day of month (padded with zeros)

11

d

First letter of weekday name (capitalized)

S

HH

Hour of day, padded with zeros if PM is set

09:00

and not padded with zeros otherwise

9:00 AM

MM

Minute of hour (padded with zeros)

10:05

SS

Second of minute (padded with zeros)

10:05:03

FFF

Milliseconds of second (padded with zeros)

10:05:03.012

AM

Use 12-hour time format

11:30 AM

PM

Use 12-hour time format

11:30 PM

If f is not specified or is -1, then use 0, 1 or 16,
depending on whether the date portion or the time portion of
date is empty.

If p is nor specified, it defaults to the current year minus 50.

If a matrix or cell array of dates is given, a column vector of date strings
is returned.

Convert a serial date number (see datenum) or date string (see
datestr) into a date vector.

A date vector is a row vector with six members, representing the year,
month, day, hour, minute, and seconds respectively.

f is the format string used to interpret date strings
(see datestr). If date is a string, but no format is
specified, then a relatively slow search is performed through various
formats. It is always preferable to specify the format string f
if it is known. Formats which do not specify a particular time component
will have the value set to zero. Formats which do not specify a date will
default to January 1st of the current year.

p is the year at the start of the century to which two-digit years
will be referenced. If not specified, it defaults to the current year
minus 50.

Add date formatted tick labels to an axis. The axis to apply the
ticks to is determined by axis which can take the values "x",
"y", or "z". The default value is "x". The
formatting of the labels is determined by the variable form, which
can either be a string or positive integer that datestr accepts.