octave_packages/m/time/datenum.m

   1 ## Copyright (C) 2006-2012 Paul Kienzle
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {@var{days} =} datenum (@var{datevec})
  21 ## @deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day})
  22 ## @deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour})
  23 ## @deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute})
  24 ## @deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute}, @var{second})
  25 ## @deftypefnx {Function File} {@var{days} =} datenum ("datestr")
  26 ## @deftypefnx {Function File} {@var{days} =} datenum ("datestr", @var{p})
  27 ## @deftypefnx {Function File} {[@var{days}, @var{secs}] =} datenum (@dots{})
  28 ## Return the date/time input as a serial day number, with Jan 1, 0000
  29 ## defined as day 1.
  30 ##
  31 ## The integer part, @code{floor (@var{days})} counts the number of
  32 ## complete days in the date input.
  33 ##
  34 ## The fractional part, @code{rem (@var{days}, 1)} corresponds to the time
  35 ## on the given day.
  36 ##
  37 ## The input may be a date vector (see @code{datevec}),
  38 ## datestr (see @code{datestr}), or directly specified as input.
  39 ##
  40 ## When processing input datestrings, @var{p} is the year at the start of the
  41 ## century to which two-digit years will be referenced.  If not specified, it
  42 ## defaults to the current year minus 50.
  43 ##
  44 ## The optional output @var{secs} holds the time on the specified day with
  45 ## greater precision than @var{days}.
  46 ##
  47 ## Notes:
  48 ##
  49 ## @itemize
  50 ## @item
  51 ## Years can be negative and/or fractional.
  52 ##
  53 ## @item
  54 ## Months below 1 are considered to be January.
  55 ##
  56 ## @item
  57 ## Days of the month start at 1.
  58 ##
  59 ## @item
  60 ## Days beyond the end of the month go into subsequent months.
  61 ##
  62 ## @item
  63 ## Days before the beginning of the month go to the previous month.
  64 ##
  65 ## @item
  66 ## Days can be fractional.
  67 ## @end itemize
  68 ##
  69 ## @strong{Caution:} this function does not attempt to handle Julian
  70 ## calendars so dates before Octave 15, 1582 are wrong by as much
  71 ## as eleven days.  Also, be aware that only Roman Catholic countries
  72 ## adopted the calendar in 1582.  It took until 1924 for it to be
  73 ## adopted everywhere.  See the Wikipedia entry on the Gregorian
  74 ## calendar for more details.
  75 ##
  76 ## @strong{Warning:} leap seconds are ignored.  A table of leap seconds
  77 ## is available on the Wikipedia entry for leap seconds.
  78 ## @seealso{datestr, datevec, now, clock, date}
  79 ## @end deftypefn
  80
  81 ## Algorithm: Peter Baum (http://vsg.cape.com/~pbaum/date/date0.htm)
  82 ## Author: pkienzle <pkienzle@users.sf.net>
  83
  84 function [days, secs] = datenum (year, month = [], day = [], hour = 0, minute = 0, second = 0)
  85
  86   ## Days until start of month assuming year starts March 1.
  87   persistent monthstart = [306; 337; 0; 31; 61; 92; 122; 153; 184; 214; 245; 275];
  88
  89   if (nargin == 0 || nargin > 6 ||
  90      (nargin > 2 && (ischar (year) || iscellstr (year))))
  91     print_usage ();
  92   endif
  93
  94   if (ischar (year) || iscellstr (year))
  95     [year, month, day, hour, minute, second] = datevec (year, month);
  96   else
  97     if (nargin == 1)
  98       nc = columns (year);
  99       if (nc > 6 || nc < 3)
 100         error ("datenum: expected date vector containing [YEAR, MONTH, DAY, HOUR, MINUTE, SECOND]");
 101       endif
 102       if (nc >= 6) second = year(:,6); endif
 103       if (nc >= 5) minute = year(:,5); endif
 104       if (nc >= 4) hour   = year(:,4); endif
 105       day   = year(:,3);
 106       month = year(:,2);
 107       year  = year(:,1);
 108     endif
 109   endif
 110
 111   month(month<1) = 1; ## For compatibility.  Otherwise allow negative months.
 112
 113   ## Set start of year to March by moving Jan. and Feb. to previous year.
 114   ## Correct for months > 12 by moving to subsequent years.
 115   year += fix ((month-14)/12);
 116
 117   ## Lookup number of days since start of the current year.
 118   if (numel (month) == 1 || numel (day) == 1)
 119     ## Allow month or day to be scalar while other values may be vectors or
 120     ## matrices.
 121     day += monthstart (mod (month-1,12) + 1) + 60;
 122     if (numel (month) > 1)
 123       day = reshape (day, size (month));
 124     endif
 125   else
 126     day += reshape (monthstart (mod (month-1,12) + 1), size (day)) + 60;
 127   endif
 128
 129   ## Add number of days to the start of the current year. Correct
 130   ## for leap year every 4 years except centuries not divisible by 400.
 131   day += 365*year + floor (year/4) - floor (year/100) + floor (year/400);
 132
 133   ## Add fraction representing current second of the day.
 134   days = day + (hour + (minute + second/60)/60)/24;
 135
 136   ## Output seconds if asked so that etime can be more accurate
 137   if (isargout (2))
 138     secs = day*86400 + hour*3600 + minute*60 + second;
 139   endif
 140
 141 endfunction
 142
 143
 144 %!shared part
 145 %! part = 0.514623842592593;
 146 %!assert (datenum (2001,5,19), 730990)
 147 %!assert (datenum ([1417,6,12]), 517712)
 148 %!assert (datenum ([2001,5,19;1417,6,12]), [730990;517712])
 149 %!assert (datenum (2001,5,19,12,21,3.5), 730990+part, eps)
 150 %!assert (datenum ([1417,6,12,12,21,3.5]), 517712+part, eps)
 151 ## Test vector inputs
 152 %!test
 153 %! t = [2001,5,19,12,21,3.5; 1417,6,12,12,21,3.5];
 154 %! n = [730990; 517712] + part;
 155 %! assert (datenum (t), n, 2*eps);
 156 %! ## Check that vectors can have either orientation
 157 %! t = t';
 158 %! n = n';
 159 %! assert (datenum (t(1,:), t(2,:), t(3,:), t(4,:), t(5,:), t(6,:)), n, 2*eps);
 160
 161 ## Test mixed vectors and scalars
 162 %!assert (datenum([2008;2009], 1, 1), [datenum(2008, 1, 1);datenum(2009, 1, 1)]);
 163 %!assert (datenum(2008, [1;2], 1), [datenum(2008, 1, 1);datenum(2008, 2, 1)]);
 164 %!assert (datenum(2008, 1, [1;2]), [datenum(2008, 1, 1);datenum(2008, 1, 2)]);
 165 %!assert (datenum([2008;2009], [1;2], 1), [datenum(2008, 1, 1);datenum(2009, 2, 1)]);
 166 %!assert (datenum([2008;2009], 1, [1;2]), [datenum(2008, 1, 1);datenum(2009, 1, 2)]);
 167 %!assert (datenum(2008, [1;2], [1;2]), [datenum(2008, 1, 1);datenum(2008, 2, 2)]);
 168 ## And the other orientation
 169 %!assert (datenum([2008 2009], 1, 1), [datenum(2008, 1, 1) datenum(2009, 1, 1)]);
 170 %!assert (datenum(2008, [1 2], 1), [datenum(2008, 1, 1) datenum(2008, 2, 1)]);
 171 %!assert (datenum(2008, 1, [1 2]), [datenum(2008, 1, 1) datenum(2008, 1, 2)]);
 172 %!assert (datenum([2008 2009], [1 2], 1), [datenum(2008, 1, 1) datenum(2009, 2, 1)]);
 173 %!assert (datenum([2008 2009], 1, [1 2]), [datenum(2008, 1, 1) datenum(2009, 1, 2)]);
 174 %!assert (datenum(2008, [1 2], [1 2]), [datenum(2008, 1, 1) datenum(2008, 2, 2)]);
 175 ## Test string and cellstr inputs
 176 %!assert (datenum ("5/19/2001"), 730990)
 177 %!assert (datenum ({"5/19/2001"}), 730990)
 178 %!assert (datenum (char ("5/19/2001", "6/6/1944")), [730990; 710189])
 179 %!assert (datenum ({"5/19/2001", "6/6/1944"}), [730990; 710189])
 180
 181 %% Test input validation
 182 %!error datenum ()
 183 %!error datenum (1,2,3,4,5,6,7)
 184 %!error datenum ([1, 2])
 185 %!error datenum ([1,2,3,4,5,6,7])