add datevec() for duration and calendarDuration; add multi-argout form for datetime.datevec() (#153)

Also factor out duration's fixed size year size to a duration.FixedSizeYearDays constant property.

Author: apjanke

CHANGES.txt

@@ -5,6 +5,7 @@ Tablicious Changelog
 ------------------
 
 * Date/time fixes
+  * Add datevec() methods for duration and calendarDuration; add multi-argout form for datetime.datevec(). ([#153](https://github.com/apjanke/octave-tablicious/issues/153))
   * Add duration.hms() method.
 
 0.4.6 (2026-02-16)

inst/@calendarDuration/calendarDuration.m

@@ -163,6 +163,36 @@
       out = this.Months;
     endfunction
 
+    ## -*- texinfo -*-
+    ## @node calendarDuration.datevec
+    ## @deftypefn {Method} {[@var{dvec}] =} datevec (@var{obj})
+    ## @deftypefnx {Method} {[@var{Y}, @var{M}, @var{D}, @var{H}, @var{MN}, @var{S}] =} datevec (@var{obj})
+    ##
+    ## Convert a @code{calendarDuration} to a datevec whose elements represent its
+    ## components of. The components are the year, month, day, hour, minute, and
+    ## second quantities of this @code{calendarDuration}.
+    ##
+    ## When nargout is 0 or 1, returns a double array of size n-by-6, where n is
+    ## @code{numel(obj)}. When nargout is 2 or more, returns double arrays the
+    ## same size as @var{obj}.
+    ##
+    ## @end deftypefn
+    function [out, M, D, H, MN, S] = datevec (this)
+      yrs = this.Months / 12;
+      Y = fix (yrs);
+      M = this.Months - (Y * 12);
+      D = this.Days;
+      x = this.Time;
+      [H, x] = deal (fix (x * 24), rem (x * 24, 1));
+      [MN, x] = deal (fix (x * 60), rem (x * 60, 1));
+      S = x * 60;
+      if nargout < 2
+        out = [Y(:) M(:) D(:) H(:) MN(:) S(:)];
+      else
+        out = Y;
+      end
+    endfunction
+
     # Arithmetic
 
     ## -*- texinfo -*-

inst/@datetime/datetime.m

@@ -792,15 +792,22 @@ function disp (this)
     ## -*- texinfo -*-
     ## @node datetime.datevec
     ## @deftypefn {Method} {@var{out} =} datevec (@var{obj})
+    ## @deftypefnx {Method} {[@var{Y}, @var{M}, @var{D}, @var{H}, @var{MN}, @var{S}] =} datevec (@var{obj})
     ##
     ## Convert this to a datevec that represent the same local wall time.
     ##
-    ## Returns double array of size [numel(obj) 6].
+    ## When nargout is 0 or 1, returns a double array of size n-by-6, where n is
+    ## @code{numel(obj)}. When nargout is 2 or more, returns double arrays the
+    ## same size as @var{obj}.
     ##
     ## @end deftypefn
-    function out = datevec (this)
+    function [out, M, D, H, MN, S] = datevec (this)
       dn = datenum (this);
-      out = datevec (dn(:));
+      if nargout < 2
+        out = datevec (this.dnum(:));
+      else
+        [out, M, D, H, MN, S] = datevec (this.dnum);
+      endif
     endfunction
 
     ## -*- texinfo -*-

inst/@duration/duration.m

@@ -58,6 +58,11 @@
     # Display format (currently unsupported)
     Format = 'hh:mm:ss'
   endproperties
+  properties (Constant)
+    # Size of fixed-size years, as a number of days, including a fractional part.
+    # Equal to 365.2425.
+    FixedSizeYearDays = 365.2425
+  endproperties
 
   methods (Static)
     ## -*- texinfo -*-
@@ -171,7 +176,7 @@
     ## @end deftypefn
     function out = years (this)
       #YEARS Number of fixed-length years equivalent to this.
-      out = this.days / 365.2425;
+      out = this.days / duration.FixedSizeYearDays;
     endfunction
 
     # Can't have a days() function as well as a days property or it will cause Octave to crash
@@ -271,6 +276,46 @@
       s = rem(minutes, 1) * 60;
     endfunction
 
+    ## -*- texinfo -*-
+    ## @node duration.datevec
+    ## @deftypefn {Method} {[@var{dvec}] =} datevec (@var{obj})
+    ## @deftypefnx {Method} {[@var{Y}, @var{M}, @var{D}, @var{H}, @var{MN}, @var{S}] =} datevec (@var{obj})
+    ##
+    ## Convert @var{obj} to a datevec whose elements represent the components of
+    ## this duration. The components are the year, month, days, hour, minute, and
+    ## second quantities of this duration. The years are in terms of fixed size
+    ## years that are 365.2425 days long, and days are fixed size 24-hour days.
+    ## The fixed size year size can be found in the FixedSizeYearDays constant
+    ## class property on the duration class. The month component is always zero,
+    ## since months are variable lengths and there is no equivalent fixed size
+    ## month. Thus, the days component may be more than 31.
+    ##
+    ## When nargout is 0 or 1, returns a double array of size n-by-6, where n is
+    ## @code{numel(obj)}. When nargout is 2 or more, returns double arrays the
+    ## same size as @var{obj}.
+    ##
+    ## @end deftypefn
+    function [out, M, D, H, MN, S] = datevec (this)
+      x = this.days;
+      x = x / duration.FixedSizeYearDays;
+      [Y, x] = deal (fix (x), rem (x, 1));
+      x = x * duration.FixedSizeYearDays;
+      M = zeros (size (this));
+      [D, x] = deal (fix (x), rem (x, 1));
+      x = x * 24;
+      [H, x] = deal (fix (x), rem (x, 1));
+      x = x * 60;
+      [MN, x] = deal (fix (x), rem (x, 1));
+      x = x * 60;
+      S = x;
+      if nargout < 2
+        out = [Y(:) M(:) D(:) H(:) MN(:) S(:)];
+      else
+        out = Y;
+        % Other argouts are already in correct format
+      endif
+    endfunction
+
     function [keysA, keysB] = proxyKeys (a, b)
       #PROXYKEYS Proxy key values for sorting and set operations
       keysA = a.days(:);