octave_packages/m/time/addtodate.m

   1 ## Copyright (C) 2008-2012 Bill Denney
   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{d} =} addtodate (@var{d}, @var{q}, @var{f})
  21 ## Add @var{q} amount of time (with units @var{f}) to the serial datenum,
  22 ## @var{d}.
  23 ##
  24 ## @var{f} must be one of "year", "month", "day", "hour", "minute", "second",
  25 ## or "millisecond".
  26 ## @seealso{datenum, datevec, etime}
  27 ## @end deftypefn
  28
  29 ## Author: Bill Denney <bill@denney.ws>
  30
  31 function d = addtodate (d, q, f)
  32
  33   persistent mult = struct ("day", 1, "hour", 1/24, "minute", 1/1440, ...
  34                             "second", 1/86400, "millisecond", 1/86400000);
  35
  36   if (nargin != 3)
  37     print_usage ();
  38   elseif (! (ischar (f) && isrow (f)))
  39     error ("addtodate: F must be a single character string");
  40   endif
  41
  42   if (isscalar (d) && ! isscalar (q))
  43     ## expand d to size of q to make later addition easier.
  44     d = repmat (d, size (q));
  45   endif
  46
  47   ## in case the user gives f as a plural, remove the 's'
  48   if ("s" == f(end))
  49     f(end) = [];
  50   endif
  51
  52   if (any (strcmpi ({"year" "month"}, f)))
  53     dtmp = datevec (d);
  54     if (strcmpi ("year", f))
  55       dtmp(:,1) += q(:);
  56     elseif (strcmpi ("month", f))
  57       dtmp(:,2) += q(:);
  58       ## adjust the years and months if the date rolls over a year
  59       dtmp(:,1) += floor ((dtmp(:,2)-1)/12);
  60       dtmp(:,2) = mod (dtmp(:,2)-1, 12) + 1;
  61     endif
  62     dnew = datenum (dtmp);
  63     ## make the output the right shape
  64     if (numel (d) == numel (dnew))
  65       d = reshape (dnew, size (d));
  66     else
  67       d = reshape (dnew, size (q));
  68     endif
  69   elseif (any (strcmpi ({"day" "hour" "minute" "second", "millisecond"}, f)))
  70     d += q .* mult.(f);
  71   else
  72     error ("addtodate: Invalid time unit: %s", f);
  73   endif
  74
  75 endfunction
  76
  77
  78 ## tests
  79 %!shared d
  80 %!  d = datenum (2008, 1, 1);
  81 ## Identity
  82 %!assert (addtodate (d, 0, "year"), d)
  83 %!assert (addtodate (d, 0, "month"), d)
  84 %!assert (addtodate (d, 0, "day"), d)
  85 %!assert (addtodate (d, 0, "hour"), d)
  86 %!assert (addtodate (d, 0, "minute"), d)
  87 %!assert (addtodate (d, 0, "second"), d)
  88 %!assert (addtodate (d, 0, "millisecond"), d)
  89 ## Add one of each
  90 ## leap year
  91 %!assert (addtodate (d, 1, "year"), d+366)
  92 %!assert (addtodate (d, 1, "month"), d+31)
  93 %!assert (addtodate (d, 1, "day"), d+1)
  94 %!assert (addtodate (d, 1, "hour"), d+1/24)
  95 %!assert (addtodate (d, 1, "minute"), d+1/1440)
  96 %!assert (addtodate (d, 1, "second"), d+1/86400)
  97 %!assert (addtodate (d, 1, "millisecond"), d+1/86400000)
  98 ## substract one of each
  99 %!assert (addtodate (d, -1, "year"), d-365)
 100 %!assert (addtodate (d, -1, "month"), d-31)
 101 %!assert (addtodate (d, -1, "day"), d-1)
 102 %!assert (addtodate (d, -1, "hour"), d-1/24)
 103 %!assert (addtodate (d, -1, "minute"), d-1/1440)
 104 %!assert (addtodate (d, -1, "second"), d-1/86400)
 105 %!assert (addtodate (d, -1, "millisecond"), d-1/86400000)
 106 ## rollover
 107 %!assert (addtodate (d, 12, "month"), d+366)
 108 %!assert (addtodate (d, 13, "month"), d+366+31)
 109 ## multiple inputs and output orientation
 110 %!assert (addtodate ([d d], [1 13], "month"), [d+31 d+366+31])
 111 %!assert (addtodate ([d;d], [1;13], "month"), [d+31;d+366+31])
 112 %!assert (addtodate (d, [1;13], "month"), [d+31;d+366+31])
 113 %!assert (addtodate (d, [1 13], "month"), [d+31 d+366+31])
 114 %!assert (addtodate ([d;d+1], 1, "month"), [d+31;d+1+31])
 115 %!assert (addtodate ([d d+1], 1, "month"), [d+31 d+1+31])
 116
 117 %% Test input validation
 118 %!error addtodate ()
 119 %!error addtodate (1)
 120 %!error addtodate (1,2)
 121 %!error addtodate (1,2,3,4)
 122 %!error <F must be a single character string> addtodate (1,2,3)
 123 %!error <F must be a single character string> addtodate (1,2,"month"')
 124 %!error <Invalid time unit> addtodate (1,2,"abc")
 125