(octave.info)Timing Utilities
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 saving time flag.
‘gmtoff’
Seconds offset from UTC.
‘zone’
Time zone.
In the descriptions of the following functions, this structure is
referred to as a TM_STRUCT.
-- : SECONDS = time ()
Return the current time as the number of seconds since the epoch.
The epoch is referenced to 00:00:00 UTC (Coordinated Universal
Time) 1 Jan 1970. For example, on Monday February 17, 1997 at
07:15:06 UTC, the value returned by ‘time’ was 856163706.
See also: Note: strftime, *note strptime:
XREFstrptime, Note: localtime, *note gmtime:
XREFgmtime, Note: mktime, Note: now, Note:
date, Note: clock, Note: datenum,
Note: datestr, Note: datevec, Note:
calendar, Note: weekday.
-- : t = now ()
Return the current local date/time as a serial day number (see
‘datenum’).
The integral part, ‘floor (now)’ corresponds to the number of days
between today and Jan 1, 0000.
The fractional part, ‘rem (now, 1)’ corresponds to the current
time.
See also: Note: clock, Note: date, Note:
datenum.
-- : ctime (T)
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:
ctime (time ())
⇒ "Mon Feb 17 01:15:06 1997\n"
See also: Note: asctime, Note: time, Note:
localtime.
-- : TM_STRUCT = gmtime (T)
Given a value returned from ‘time’, or any non-negative integer,
return a time structure corresponding to UTC (Coordinated Universal
Time).
For example:
gmtime (time ())
⇒ {
usec = 0
sec = 6
min = 15
hour = 7
mday = 17
mon = 1
year = 97
wday = 1
yday = 47
isdst = 0
gmtoff = 0
zone = GMT
}
See also: Note: strftime, *note strptime:
XREFstrptime, Note: localtime, *note mktime:
XREFmktime, Note: time, Note: now, *note date:
XREFdate, Note: clock, Note: datenum, Note:
datestr, Note: datevec, *note calendar:
XREFcalendar, Note: weekday.
-- : TM_STRUCT = localtime (T)
Given a value returned from ‘time’, or any non-negative integer,
return a time structure corresponding to the local time zone.
localtime (time ())
⇒ {
usec = 0
sec = 6
min = 15
hour = 1
mday = 17
mon = 1
year = 97
wday = 1
yday = 47
isdst = 0
gmtoff = -21600
zone = CST
}
See also: Note: strftime, *note strptime:
XREFstrptime, Note: gmtime, Note: mktime,
Note: time, Note: now, Note: date,
Note: clock, Note: datenum, *note datestr:
XREFdatestr, Note: datevec, *note calendar:
XREFcalendar, Note: weekday.
-- : SECONDS = mktime (TM_STRUCT)
Convert a time structure corresponding to the local time to the
number of seconds since the epoch.
For example:
mktime (localtime (time ()))
⇒ 856163706
See also: Note: strftime, *note strptime:
XREFstrptime, Note: localtime, *note gmtime:
XREFgmtime, Note: time, Note: now, *note date:
XREFdate, Note: clock, Note: datenum, Note:
datestr, Note: datevec, *note calendar:
XREFcalendar, Note: weekday.
-- : asctime (TM_STRUCT)
Convert a time structure to a string using the following format:
"ddd mmm mm HH:MM:SS yyyy\n".
For example:
asctime (localtime (time ()))
⇒ "Mon Feb 17 01:15:06 1997\n"
This is equivalent to ‘ctime (time ())’.
See also: Note: ctime, Note: localtime,
Note: time.
-- : strftime (FMT, TM_STRUCT)
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:
strftime ("%r (%Z) %A %e %B %Y", localtime (time ()))
⇒ "01:15:06 AM (CST) Monday 17 February 1997"
Octave’s ‘strftime’ function supports a superset of the ANSI C
field specifiers.
Literal character fields:
‘%%’
% character.
‘%n’
Newline character.
‘%t’
Tab character.
Numeric modifiers (a nonstandard extension):
‘- (dash)’
Do not pad the field.
‘_ (underscore)’
Pad the field with spaces.
Time fields:
‘%H’
Hour (00-23).
‘%I’
Hour (01-12).
‘%k’
Hour (0-23).
‘%l’
Hour (1-12).
‘%M’
Minute (00-59).
‘%p’
Locale’s AM or PM.
‘%r’
Time, 12-hour (hh:mm:ss [AP]M).
‘%R’
Time, 24-hour (hh:mm).
‘%s’
Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard
extension).
‘%S’
Second (00-61).
‘%T’
Time, 24-hour (hh:mm:ss).
‘%X’
Locale’s time representation (%H:%M:%S).
‘%z’
Offset from UTC (±hhmm), or nothing if no time zone is
determinable.
‘%Z’
Time zone (EDT), or nothing if no time zone is determinable.
Date fields:
‘%a’
Locale’s abbreviated weekday name (Sun-Sat).
‘%A’
Locale’s full weekday name, variable length (Sunday-Saturday).
‘%b’
Locale’s abbreviated month name (Jan-Dec).
‘%B’
Locale’s full month name, variable length (January-December).
‘%c’
Locale’s date and time (Sat Nov 04 12:02:33 EST 1989).
‘%C’
Century (00-99).
‘%d’
Day of month (01-31).
‘%e’
Day of month ( 1-31).
‘%D’
Date (mm/dd/yy).
‘%h’
Same as %b.
‘%j’
Day of year (001-366).
‘%m’
Month (01-12).
‘%U’
Week number of year with Sunday as first day of week (00-53).
‘%w’
Day of week (0-6).
‘%W’
Week number of year with Monday as first day of week (00-53).
‘%x’
Locale’s date representation (mm/dd/yy).
‘%y’
Last two digits of year (00-99).
‘%Y’
Year (1970-).
See also: Note: strptime, *note localtime:
XREFlocaltime, Note: gmtime, Note: mktime,
Note: time, Note: now, Note: date,
Note: clock, Note: datenum, *note datestr:
XREFdatestr, Note: datevec, *note calendar:
XREFcalendar, Note: weekday.
-- : [TM_STRUCT, NCHARS] = strptime (STR, FMT)
Convert the string STR to the time structure TM_STRUCT under the
control of the format string FMT.
If FMT fails to match, NCHARS is 0; otherwise, it is set to the
position of last matched character plus 1. Always check for this
unless you’re absolutely sure the date string will be parsed
correctly.
See also: Note: strftime, *note localtime:
XREFlocaltime, Note: gmtime, Note: mktime,
Note: time, Note: now, Note: date,
Note: clock, Note: datenum, *note datestr:
XREFdatestr, Note: datevec, *note calendar:
XREFcalendar, Note: weekday.
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.
-- : 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 ]
‘clock’ is more accurate on systems that have the ‘gettimeofday’
function.
See also: Note: now, Note: date, *note datevec:
XREFdatevec.
-- : date ()
Return the current date as a character string in the form
DD-MMM-YYYY.
For example:
date ()
⇒ "20-Aug-1993"
See also: Note: now, Note: clock, Note:
datestr, Note: localtime.
-- : etime (T2, T1)
Return the difference in seconds between two time values returned
from ‘clock’ (T2 - T1).
For example:
t0 = clock ();
# many computations later...
elapsed_time = etime (clock (), t0);
will set the variable ‘elapsed_time’ to the number of seconds since
the variable ‘t0’ was set.
See also: Note: tic, Note: toc, *note clock:
XREFclock, Note: cputime, *note addtodate:
XREFaddtodate.
-- : [TOTAL, USER, SYSTEM] = cputime ();
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.
See also: Note: tic, Note: toc.
-- : is_leap_year ()
-- : is_leap_year (YEAR)
Return true if YEAR is a leap year and false otherwise.
If no year is specified, ‘is_leap_year’ uses the current year.
For example:
is_leap_year (2000)
⇒ 1
See also: Note: weekday, Note: eomday,
Note: calendar.
-- : tic ()
-- : ID = tic ()
Initialize a wall-clock timer.
Calling ‘tic’ without an output argument resets the internal timer.
Subsequent calls to ‘toc’ return the number of seconds since the
timer was set.
If called with one output argument, ‘tic’ creates a new timer
instance and returns a timer identifier ID. The ID is a scalar of
type ‘uint64’ that may be passed to ‘toc’ to check elapsed time on
this timer, rather than the default internal timer.
Example 1 : benchmarking code with internal timer
tic;
# many computations later...
elapsed_time = toc;
Example 2 : mixed timer id and internal timer
tic;
pause (1);
toc
⇒ Elapsed time is 1.0089 seconds.
id = tic;
pause (2);
toc (id)
⇒ Elapsed time is 2.01142 seconds.
toc
Elapsed time is 3.02308 seconds.
Calling ‘tic’ and ‘toc’ in 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.
See also: Note: toc, Note: cputime.
-- : toc ()
-- : toc (ID)
-- : ELAPSED_TIME = toc (...)
Measure elapsed time on a wall-clock timer.
With no arguments, return the number of seconds elapsed on the
internal timer since the last call to ‘tic’.
When given the identifier ID of a specific timer, return the number
of seconds elapsed since the timer ID was initialized.
Note: tic, for examples of the use of ‘tic’/‘toc’.
See also: Note: tic, Note: cputime.
-- : pause ()
-- : pause (N)
Suspend the execution of the program for N seconds.
If invoked without an input arguments then the program is suspended
until a character is typed.
N is a positive real value and may be a fraction of a second, for
example:
tic; pause (0.05); toc
⊣ Elapsed time is 0.05039 seconds.
The following example prints a message and then waits 5 seconds
before clearing the screen.
disp ("wait please...");
pause (5);
clc;
See also: Note: kbhit.
-- : DAYS = datenum (DATEVEC)
-- : DAYS = datenum (YEAR, MONTH, DAY)
-- : DAYS = datenum (YEAR, MONTH, DAY, HOUR)
-- : DAYS = datenum (YEAR, MONTH, DAY, HOUR, MINUTE)
-- : DAYS = datenum (YEAR, MONTH, DAY, HOUR, MINUTE, SECOND)
-- : DAYS = datenum ("datestr")
-- : DAYS = datenum ("datestr", F)
-- : DAYS = datenum ("datestr", P)
-- : [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, F is the format string used to
interpret date strings (see ‘datestr’). If no format F 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.
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.
See also: Note: datestr, Note: datevec,
Note: now, Note: clock, Note: date.
-- : STR = datestr (DATE)
-- : STR = datestr (DATE, F)
-- : STR = datestr (DATE, F, P)
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 3:38:09 PM
15 HH:MM 15:38
16 HH:MM PM 3: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, 09:00
or padded with spaces if PM is set 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.
See also: Note: datenum, Note: datevec,
Note: date, Note: now, Note: clock.
-- : V = datevec (DATE)
-- : V = datevec (DATE, F)
-- : V = datevec (DATE, P)
-- : V = datevec (DATE, F, P)
-- : [Y, M, D, H, MI, S] = datevec (...)
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.
See also: Note: datenum, Note: datestr,
Note: clock, Note: now, Note: date.
-- : D = addtodate (D, Q, F)
Add Q amount of time (with units F) to the serial datenum, D.
F must be one of "year", "month", "day", "hour", "minute",
"second", or "millisecond".
See also: Note: datenum, Note: datevec,
Note: etime.
-- : C = calendar ()
-- : C = calendar (D)
-- : C = calendar (Y, M)
-- : calendar (...)
Return the current monthly calendar in a 6x7 matrix.
If D is specified, return the calendar for the month containing the
date D, which must be a serial date number or a date string.
If Y and M are specified, return the calendar for year Y and month
M.
If no output arguments are specified, print the calendar on the
screen instead of returning a matrix.
See also: Note: datenum, Note: datestr.
-- : [N, S] = weekday (D)
-- : [N, S] = weekday (D, FORMAT)
Return the day of the week as a number in N and as a string in S.
The days of the week are numbered 1–7 with the first day being
Sunday.
D is a serial date number or a date string.
If the string FORMAT is not present or is equal to "short" then S
will contain the abbreviated name of the weekday. If FORMAT is
"long" then S will contain the full name.
Table of return values based on FORMAT:
N "short" "long"
----------------------------
1 Sun Sunday
2 Mon Monday
3 Tue Tuesday
4 Wed Wednesday
5 Thu Thursday
6 Fri Friday
7 Sat Saturday
See also: Note: eomday, *note is_leap_year:
XREFis_leap_year, Note: calendar, *note datenum:
XREFdatenum, Note: datevec.
-- : E = eomday (Y, M)
Return the last day of the month M for the year Y.
See also: Note: weekday, Note: datenum,
Note: datevec, Note: is_leap_year,
Note: calendar.
-- : datetick ()
-- : datetick (AXIS_STR)
-- : datetick (DATE_FORMAT)
-- : datetick (AXIS_STR, DATE_FORMAT)
-- : datetick (..., "keeplimits")
-- : datetick (..., "keepticks")
-- : datetick (HAX, ...)
Add date-formatted tick labels to an axis.
The axis to apply the ticks to is determined by AXIS_STR which can
take the values "x", "y", or "z". The default value is "x".
The formatting of the labels is determined by the variable
DATE_FORMAT, which can either be a string or positive integer that
‘datestr’ accepts.
If the first argument HAX is an axes handle, then plot into this
axes, rather than the current axes returned by ‘gca’.
See also: Note: datenum, Note: datestr.
automatically generated by info2www version 1.2.2.9