### 34.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-61). This number can be 61 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.

— Loadable Function: 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.

— Function File: ctime (t)

> Convert a value returned from `time` (or any other nonnegative 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"

— Loadable Function: gmtime (t)

> Given a value returned from time (or any nonnegative integer), return a time structure corresponding to CUT. For example,

>               gmtime (time ())
>                    => {
>                          usec = 0
>                          year = 97
>                          mon = 1
>                          mday = 17
>                          sec = 6
>                          zone = CST
>                          min = 15
>                          wday = 1
>                          hour = 7
>                          isdst = 0
>                          yday = 47
>                        }

— Loadable Function: localtime (t)

> Given a value returned from time (or any nonnegative integer), return a time structure corresponding to the local time zone.

>               localtime (time ())
>                    => {
>                          usec = 0
>                          year = 97
>                          mon = 1
>                          mday = 17
>                          sec = 6
>                          zone = CST
>                          min = 15
>                          wday = 1
>                          hour = 1
>                          isdst = 0
>                          yday = 47
>                        }

— Loadable Function: 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

— Function File: asctime (tm_struct)

> Convert a time structure to a string using the following five-field format: Thu Mar 28 08:40:14 1996. For example,

>               asctime (localtime (time ())
>               => "Mon Feb 17 01:15:06 1997\n"

> This is equivalent to `ctime (time ())`.

— Loadable Function: strftime (tm_struct)

> Format a time structure in a flexible way using ``%`' 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`
>   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-).

— Loadable Function: [tm_struct, nchars] = strptime (str, fmt)

> Convert the string str to a time structure under the control of the format fmt.

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

— Function File: clock ()

> Return a vector containing the current year, month (1-12), day (1-31), hour (0-23), minute (0-59) and second (0-61). For example,

>               clock ()
>               => [ 1993, 8, 20, 4, 56, 1 ]

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

— Function File: date ()

> Return the date as a character string in the form DD-MMM-YY. For example,

>               date ()
>               => "20-Aug-93"

— Function File: etime (t1, t2)

> Return the difference (in seconds) between two time values returned from `clock`. 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.

— Function File: [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.

— Function File: is_leap_year (year)

> Return 1 if the given year is a leap year and 0 otherwise. If no arguments are provided, `is_leap_year` will use the current year. For example,

>               is_leap_year (2000)
>               => 1

— Function File: tic ()
— Function File: toc ()

> These functions set and check a wall-clock timer. 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 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. For example,

>               tic (); sleep (5); toc ()
>               => 5
>               t = cputime (); sleep (5); cputime () - t
>               => 0

> (This example also illustrates that the CPU timer may have a fairly coarse resolution.)

— Built-in Function: pause (seconds)

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