octave: 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 Savings 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 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.
 
DONTPRINTYET       See also: Seestrftime XREFstrftime, *notestrptime:
DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, *notegmtime:
DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seegmtime

      XREFgmtime, Seemktime XREFmktime, Seenow XREFnow, *noteDONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seegmtime

      XREFgmtime, Seemktime XREFmktime, Seenow XREFnow, See
      date XREFdate, Seeclock XREFclock, Seedatenum XREFdatenum,
DONTPRINTYET       Seedatestr XREFdatestr, Seedatevec XREFdatevec, *noteDONTPRINTYET       Seedatestr XREFdatestr, Seedatevec XREFdatevec, See
      calendar XREFcalendar, Seeweekday XREFweekday.
 
  -- : 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.
 
DONTPRINTYET       See also: Seeclock XREFclock, Seedate XREFdate, *noteDONTPRINTYET       See also: Seeclock XREFclock, Seedate XREFdate, See
      datenum XREFdatenum.
 
  -- : 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"
 
DONTPRINTYET       See also: Seeasctime XREFasctime, Seetime XREFtime, *noteDONTPRINTYET       See also: Seeasctime XREFasctime, Seetime XREFtime, See
      localtime XREFlocaltime.
 
  -- : TM_STRUCT = gmtime (T)
      Given a value returned from ‘time’, or any non-negative integer,
      return a time structure corresponding to CUT (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
                   }
 
DONTPRINTYET       See also: Seestrftime XREFstrftime, *notestrptime:
DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, *notemktime:
DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seemktime

      XREFmktime, Seetime XREFtime, Seenow XREFnow, *notedate:
DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seemktime

      XREFmktime, Seetime XREFtime, Seenow XREFnow, Seedate

      XREFdate, Seeclock XREFclock, Seedatenum XREFdatenum, *noteDONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seemktime

      XREFmktime, Seetime XREFtime, Seenow XREFnow, Seedate

      XREFdate, Seeclock XREFclock, Seedatenum XREFdatenum, See
      datestr XREFdatestr, Seedatevec XREFdatevec, *notecalendar:
DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seemktime

      XREFmktime, Seetime XREFtime, Seenow XREFnow, Seedate

      XREFdate, Seeclock XREFclock, Seedatenum XREFdatenum, See
      datestr XREFdatestr, Seedatevec XREFdatevec, Seecalendar

      XREFcalendar, Seeweekday XREFweekday.
 
  -- : 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
                   }
 
DONTPRINTYET       See also: Seestrftime XREFstrftime, *notestrptime:
DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seegmtime XREFgmtime, Seemktime XREFmktime,
      Seetime XREFtime, Seenow XREFnow, Seedate XREFdate,
DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, *notedatestr:
DONTPRINTYET DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, Seedatestr

      XREFdatestr, Seedatevec XREFdatevec, *notecalendar:
DONTPRINTYET DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, Seedatestr

      XREFdatestr, Seedatevec XREFdatevec, Seecalendar

      XREFcalendar, Seeweekday XREFweekday.
 
  -- : 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
 
DONTPRINTYET       See also: Seestrftime XREFstrftime, *notestrptime:
DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, *notegmtime:
DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seegmtime

      XREFgmtime, Seetime XREFtime, Seenow XREFnow, *notedate:
DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seegmtime

      XREFgmtime, Seetime XREFtime, Seenow XREFnow, Seedate

      XREFdate, Seeclock XREFclock, Seedatenum XREFdatenum, *noteDONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seegmtime

      XREFgmtime, Seetime XREFtime, Seenow XREFnow, Seedate

      XREFdate, Seeclock XREFclock, Seedatenum XREFdatenum, See
      datestr XREFdatestr, Seedatevec XREFdatevec, *notecalendar:
DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET DONTPRINTYET       See also: Seestrftime XREFstrftime, Seestrptime

      XREFstrptime, Seelocaltime XREFlocaltime, Seegmtime

      XREFgmtime, Seetime XREFtime, Seenow XREFnow, Seedate

      XREFdate, Seeclock XREFclock, Seedatenum XREFdatenum, See
      datestr XREFdatestr, Seedatevec XREFdatevec, Seecalendar

      XREFcalendar, Seeweekday XREFweekday.
 
  -- : 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: Seectime XREFctime, Seelocaltime XREFlocaltime,
      Seetime XREFtime.
 
  -- : 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-).
 
DONTPRINTYET       See also: Seestrptime XREFstrptime, *notelocaltime:
DONTPRINTYET       See also: Seestrptime XREFstrptime, Seelocaltime

      XREFlocaltime, Seegmtime XREFgmtime, Seemktime XREFmktime,
      Seetime XREFtime, Seenow XREFnow, Seedate XREFdate,
DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, *notedatestr:
DONTPRINTYET DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, Seedatestr

      XREFdatestr, Seedatevec XREFdatevec, *notecalendar:
DONTPRINTYET DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, Seedatestr

      XREFdatestr, Seedatevec XREFdatevec, Seecalendar

      XREFcalendar, Seeweekday XREFweekday.
 
  -- : [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.
 
DONTPRINTYET       See also: Seestrftime XREFstrftime, *notelocaltime:
DONTPRINTYET       See also: Seestrftime XREFstrftime, Seelocaltime

      XREFlocaltime, Seegmtime XREFgmtime, Seemktime XREFmktime,
      Seetime XREFtime, Seenow XREFnow, Seedate XREFdate,
DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, *notedatestr:
DONTPRINTYET DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, Seedatestr

      XREFdatestr, Seedatevec XREFdatevec, *notecalendar:
DONTPRINTYET DONTPRINTYET       Seeclock XREFclock, Seedatenum XREFdatenum, Seedatestr

      XREFdatestr, Seedatevec XREFdatevec, Seecalendar

      XREFcalendar, Seeweekday XREFweekday.
 
    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.
 
DONTPRINTYET       See also: Seenow XREFnow, Seedate XREFdate, *notedatevec:
DONTPRINTYET       See also: Seenow XREFnow, Seedate XREFdate, Seedatevec

      XREFdatevec.
 
  -- : date ()
      Return the current date as a character string in the form
      DD-MMM-YYYY.
 
      For example:
 
           date ()
             ⇒ "20-Aug-1993"
 
DONTPRINTYET       See also: Seenow XREFnow, Seeclock XREFclock, *noteDONTPRINTYET       See also: Seenow XREFnow, Seeclock XREFclock, See
      datestr XREFdatestr, Seelocaltime XREFlocaltime.
 
  -- : 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.
 
DONTPRINTYET       See also: Seetic XREFtic, Seetoc XREFtoc, *noteclock:
DONTPRINTYET DONTPRINTYET       See also: Seetic XREFtic, Seetoc XREFtoc, Seeclock

      XREFclock, Seecputime XREFcputime, *noteaddtodate:
DONTPRINTYET DONTPRINTYET       See also: Seetic XREFtic, Seetoc XREFtoc, Seeclock

      XREFclock, Seecputime XREFcputime, Seeaddtodate

      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: Seetic XREFtic, Seetoc XREFtoc.
 
  -- : 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: Seeweekday XREFweekday, Seeeomday XREFeomday,
      Seecalendar XREFcalendar.
 
  -- : tic ()
  -- : ID = tic ()
  -- : toc ()
  -- : toc (ID)
  -- : VAL = toc (...)
      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; pause (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.
 
      See also: Seetoc XREFtoc, Seecputime XREFcputime.
 
  -- : 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: Seekbhit XREFkbhit.
 
  -- : 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: Seedatestr XREFdatestr, Seedatevec XREFdatevec,
      Seenow XREFnow, Seeclock XREFclock, Seedate XREFdate.
 
  -- : 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: Seedatenum XREFdatenum, Seedatevec XREFdatevec,
      Seedate XREFdate, Seenow XREFnow, Seeclock XREFclock.
 
  -- : 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: Seedatenum XREFdatenum, Seedatestr XREFdatestr,
      Seeclock XREFclock, Seenow XREFnow, Seedate XREFdate.
 
  -- : 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: Seedatenum XREFdatenum, Seedatevec XREFdatevec,
      Seeetime XREFetime.
 
  -- : 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: Seedatenum XREFdatenum, Seedatestr XREFdatestr.
 
  -- : [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
 
DONTPRINTYET       See also: Seeeomday XREFeomday, *noteis_leap_year:
DONTPRINTYET DONTPRINTYET       See also: Seeeomday XREFeomday, Seeis_leap_year

      XREFis_leap_year, Seecalendar XREFcalendar, *notedatenum:
DONTPRINTYET DONTPRINTYET       See also: Seeeomday XREFeomday, Seeis_leap_year

      XREFis_leap_year, Seecalendar XREFcalendar, Seedatenum

      XREFdatenum, Seedatevec XREFdatevec.
 
  -- : E = eomday (Y, M)
      Return the last day of the month M for the year Y.
 
      See also: Seeweekday XREFweekday, Seedatenum XREFdatenum,
      Seedatevec XREFdatevec, Seeis_leap_year XREFis_leap_year,
      Seecalendar XREFcalendar.
 
  -- : 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: Seedatenum XREFdatenum, Seedatestr XREFdatestr.