octave_packages/m/time/datestr.m

   1 ## Copyright (C) 2000-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{str} =} datestr (@var{date})
  21 ## @deftypefnx {Function File} {@var{str} =} datestr (@var{date}, @var{f})
  22 ## @deftypefnx {Function File} {@var{str} =} datestr (@var{date}, @var{f}, @var{p})
  23 ## Format the given date/time according to the format @code{f} and return
  24 ## the result in @var{str}.  @var{date} is a serial date number (see
  25 ## @code{datenum}) or a date vector (see @code{datevec}).  The value of
  26 ## @var{date} may also be a string or cell array of strings.
  27 ##
  28 ## @var{f} can be an integer which corresponds to one of the codes in
  29 ## the table below, or a date format string.
  30 ##
  31 ## @var{p} is the year at the start of the century in which two-digit years
  32 ## are to be interpreted in.  If not specified, it defaults to the current
  33 ## year minus 50.
  34 ##
  35 ## For example, the date 730736.65149 (2000-09-07 15:38:09.0934) would be
  36 ## formatted as follows:
  37 ##
  38 ## @multitable @columnfractions 0.1 0.45 0.35
  39 ## @headitem Code @tab Format @tab Example
  40 ## @item  0 @tab dd-mmm-yyyy HH:MM:SS   @tab 07-Sep-2000 15:38:09
  41 ## @item  1 @tab dd-mmm-yyyy            @tab 07-Sep-2000
  42 ## @item  2 @tab mm/dd/yy               @tab 09/07/00
  43 ## @item  3 @tab mmm                    @tab Sep
  44 ## @item  4 @tab m                      @tab S
  45 ## @item  5 @tab mm                     @tab 09
  46 ## @item  6 @tab mm/dd                  @tab 09/07
  47 ## @item  7 @tab dd                     @tab 07
  48 ## @item  8 @tab ddd                    @tab Thu
  49 ## @item  9 @tab d                      @tab T
  50 ## @item 10 @tab yyyy                   @tab 2000
  51 ## @item 11 @tab yy                     @tab 00
  52 ## @item 12 @tab mmmyy                  @tab Sep00
  53 ## @item 13 @tab HH:MM:SS               @tab 15:38:09
  54 ## @item 14 @tab HH:MM:SS PM            @tab 03:38:09 PM
  55 ## @item 15 @tab HH:MM                  @tab 15:38
  56 ## @item 16 @tab HH:MM PM               @tab 03:38 PM
  57 ## @item 17 @tab QQ-YY                  @tab Q3-00
  58 ## @item 18 @tab QQ                     @tab Q3
  59 ## @item 19 @tab dd/mm                  @tab 13/03
  60 ## @item 20 @tab dd/mm/yy               @tab 13/03/95
  61 ## @item 21 @tab mmm.dd.yyyy HH:MM:SS   @tab Mar.03.1962 13:53:06
  62 ## @item 22 @tab mmm.dd.yyyy            @tab Mar.03.1962
  63 ## @item 23 @tab mm/dd/yyyy             @tab 03/13/1962
  64 ## @item 24 @tab dd/mm/yyyy             @tab 12/03/1962
  65 ## @item 25 @tab yy/mm/dd               @tab 95/03/13
  66 ## @item 26 @tab yyyy/mm/dd             @tab 1995/03/13
  67 ## @item 27 @tab QQ-YYYY                @tab Q4-2132
  68 ## @item 28 @tab mmmyyyy                @tab Mar2047
  69 ## @item 29 @tab yyyymmdd               @tab 20470313
  70 ## @item 30 @tab yyyymmddTHHMMSS        @tab 20470313T132603
  71 ## @item 31 @tab yyyy-mm-dd HH:MM:SS    @tab 1047-03-13 13:26:03
  72 ## @end multitable
  73 ##
  74 ## If @var{f} is a format string, the following symbols are recognized:
  75 ##
  76 ## @multitable @columnfractions 0.1 0.7 0.2
  77 ## @headitem Symbol @tab Meaning @tab Example
  78 ## @item yyyy @tab Full year                                    @tab 2005
  79 ## @item yy   @tab Two-digit year                               @tab 2005
  80 ## @item mmmm @tab Full month name                              @tab December
  81 ## @item mmm  @tab Abbreviated month name                       @tab Dec
  82 ## @item mm   @tab Numeric month number (padded with zeros)     @tab 01, 08, 12
  83 ## @item m    @tab First letter of month name (capitalized)     @tab D
  84 ## @item dddd @tab Full weekday name                            @tab Sunday
  85 ## @item ddd  @tab Abbreviated weekday name                     @tab Sun
  86 ## @item dd   @tab Numeric day of month (padded with zeros)     @tab 11
  87 ## @item d    @tab First letter of weekday name (capitalized)   @tab S
  88 ## @item HH   @tab Hour of day, padded with zeros if PM is set  @tab 09:00
  89 ## @item      @tab and not padded with zeros otherwise          @tab 9:00 AM
  90 ## @item MM   @tab Minute of hour (padded with zeros)           @tab 10:05
  91 ## @item SS   @tab Second of minute (padded with zeros)         @tab 10:05:03
  92 ## @item FFF  @tab Milliseconds of second (padded with zeros)   @tab 10:05:03.012
  93 ## @item AM   @tab Use 12-hour time format                      @tab 11:30 AM
  94 ## @item PM   @tab Use 12-hour time format                      @tab 11:30 PM
  95 ## @end multitable
  96 ##
  97 ## If @var{f} is not specified or is @code{-1}, then use 0, 1 or 16,
  98 ## depending on whether the date portion or the time portion of
  99 ## @var{date} is empty.
 100 ##
 101 ## If @var{p} is nor specified, it defaults to the current year minus 50.
 102 ##
 103 ## If a matrix or cell array of dates is given, a column vector of date strings
 104 ## is returned.
 105 ##
 106 ## @seealso{datenum, datevec, date, now, clock}
 107 ## @end deftypefn
 108
 109 ## FIXME: parse arbitrary code strings.
 110 ## e.g., for  Wednesday 2001-03-05 09:04:06 AM, use
 111 ##     yy    01
 112 ##     yyyy  2001
 113 ##     m     M
 114 ##     mm    03
 115 ##     mmm   Mar
 116 ##     d     W
 117 ##     dd    05
 118 ##     ddd   Wed
 119 ##     HH    09
 120 ##     MM    04
 121 ##     SS    06
 122 ##     PM    AM
 123 ## FIXME: Vectorize.  It is particularly easy since all the codes are
 124 ##    fixed width.  Just generate the parts in separate arrays and
 125 ##    concatenate.
 126
 127 ## Author: pkienzle <pkienzle@users.sf.net>
 128 ## Created: 10 October 2001 (CVS)
 129 ## Adapted-By: William Poetra Yoga Hadisoeseno <williampoetra@gmail.com>
 130
 131 function retval = datestr (date, f = [], p = [])
 132
 133   persistent dateform names_mmmm names_m names_d;
 134
 135   if (isempty (dateform))
 136     dateform = cell (32, 1);
 137     dateform{1}  = "dd-mmm-yyyy HH:MM:SS";
 138     dateform{2}  = "dd-mmm-yyyy";
 139     dateform{3}  = "mm/dd/yy";
 140     dateform{4}  = "mmm";
 141     dateform{5}  = "m";
 142     dateform{6}  = "mm";
 143     dateform{7}  = "mm/dd";
 144     dateform{8}  = "dd";
 145     dateform{9}  = "ddd";
 146     dateform{10} = "d";
 147     dateform{11} = "yyyy";
 148     dateform{12} = "yy";
 149     dateform{13} = "mmmyy";
 150     dateform{14} = "HH:MM:SS";
 151     dateform{15} = "HH:MM:SS PM";
 152     dateform{16} = "HH:MM";
 153     dateform{17} = "HH:MM PM";
 154     dateform{18} = "QQ-YY";
 155     dateform{19} = "QQ";
 156     dateform{20} = "dd/mm";
 157     dateform{21} = "dd/mm/yy";
 158     dateform{22} = "mmm.dd,yyyy HH:MM:SS";
 159     dateform{23} = "mmm.dd,yyyy";
 160     dateform{24} = "mm/dd/yyyy";
 161     dateform{25} = "dd/mm/yyyy";
 162     dateform{26} = "yy/mm/dd";
 163     dateform{27} = "yyyy/mm/dd";
 164     dateform{28} = "QQ-YYYY";
 165     dateform{29} = "mmmyyyy";
 166     dateform{30} = "yyyy-mm-dd";
 167     dateform{31} = "yyyymmddTHHMMSS";
 168     dateform{32} = "yyyy-mm-dd HH:MM:SS";
 169
 170     names_m = {"J", "F", "M", "A", "M", "J", "J", "A", "S", "O", "N", "D"};
 171     names_d = {"S", "M", "T", "W", "T", "F", "S"};
 172   endif
 173
 174   if (nargin < 1 || nargin > 3)
 175     print_usage ();
 176   endif
 177
 178   ## Guess input type.  We might be wrong.
 179   if (ischar (date) || iscellstr (date) || columns (date) != 6)
 180     v = datevec (date, p);
 181   else
 182     v = [];
 183     if (columns (date) == 6)
 184       ## Make sure that the input really is a datevec.
 185       maxdatevec = [Inf, 12, 31, 23, 59, 60];
 186       if (any (max (date, 1) > maxdatevec) ||
 187           any (date(:,1:5) != floor (date(:,1:5))))
 188         v = datevec (date, p);
 189       endif
 190     endif
 191     if (isempty (v))
 192       v = date;
 193     endif
 194   endif
 195
 196   retval = [];
 197   for i = 1 : rows (v)
 198
 199     if (isempty (f))
 200       if (v(i,4:6) == 0)
 201         f = 1;
 202       elseif (v(i,1:3) == [-1, 12, 31])
 203         f = 16;
 204       else
 205         f = 0;
 206       endif
 207     endif
 208
 209     if (isnumeric (f))
 210       df = dateform{f + 1};
 211     else
 212       df = f;
 213     endif
 214
 215     df_orig = df;
 216     df = strrep (df, 'AM', "%p");
 217     df = strrep (df, 'PM', "%p");
 218     if (strcmp (df, df_orig))
 219       ## PM not set.
 220       df = strrep (df, "HH", "%H");
 221     else
 222       df = strrep (df, "HH", sprintf ("%2d", v(i,4)));
 223     endif
 224
 225     df = regexprep (df, '[Yy][Yy][Yy][Yy]', "%Y");
 226
 227     df = regexprep (df, '[Yy][Yy]', "%y");
 228
 229     df = regexprep (df, '[Dd][Dd][Dd][Dd]', "%A");
 230
 231     df = regexprep (df, '[Dd][Dd][Dd]', "%a");
 232
 233     df = regexprep (df, '[Dd][Dd]', "%d");
 234
 235     wday = weekday (datenum (v(i,1), v(i,2), v(i,3)));
 236     tmp = names_d{wday};
 237     df = regexprep (df, '([^%])[Dd]', sprintf ("$1%s", tmp));
 238     df = regexprep (df, '^[Dd]', sprintf ("%s", tmp));
 239
 240     df = strrep (df, "mmmm", "%B");
 241
 242     df = strrep (df, "mmm", "%b");
 243
 244     df = strrep (df, "mm", "%m");
 245
 246     tmp = names_m{v(i,2)};
 247     pos = regexp (df, '[^%]m') + 1;
 248     df(pos) = tmp;
 249     df = regexprep (df, '^m', tmp);
 250
 251     df = strrep (df, "MM", "%M");
 252
 253     df = regexprep (df, '[Ss][Ss]', "%S");
 254
 255     df = strrep (df, "FFF", sprintf ("%03d", 1000 * (v(i,6) - fix (v(i,6)))));
 256
 257     df = strrep (df, 'QQ', sprintf ("Q%d", fix ((v(i,2) + 2) / 3)));
 258
 259     vi = v(i,:);
 260     tm.year = vi(1) - 1900;
 261     tm.mon = vi(2) - 1;
 262     tm.mday = vi(3);
 263     tm.hour = vi(4);
 264     tm.min = vi(5);
 265     sec = vi(6);
 266     tm.sec = fix (sec);
 267     tm.usec = fix ((sec - tm.sec) * 1e6);
 268     tm.wday = wday - 1;
 269     ## FIXME -- Do we need YDAY and DST?  How should they be computed?
 270     ## We don't want to use "localtime (mktime (tm))" because that
 271     ## doesn't correctly handle dates before 1970-01-01 on some systems.
 272     ## tm.yday = ?;
 273     ## tm.isdst = ?;
 274
 275     str = strftime (df, tm);
 276
 277     retval = [retval; str];
 278
 279   endfor
 280
 281 endfunction
 282
 283
 284 ## demos
 285 %!demo
 286 %! ## Current date and time in default format
 287 %! datestr (now ())
 288 %!demo
 289 %! ## Current date (integer portion of datenum)
 290 %! datestr (fix (now ()))
 291 %!demo
 292 %! ## Current time (fractional portion of datenum)
 293 %! datestr (rem (now (), 1))
 294
 295 %!shared testtime
 296 %! testtime = [2005.0000, 12.0000, 18.0000, 2.0000, 33.0000, 17.3822];
 297 %!assert (datestr (testtime,0), "18-Dec-2005 02:33:17")
 298 %!assert (datestr (testtime,1), "18-Dec-2005")
 299 %!assert (datestr (testtime,2), "12/18/05")
 300 %!assert (datestr (testtime,3), "Dec")
 301 %!assert (datestr (testtime,4), "D")
 302 %!assert (datestr (testtime,5), "12")
 303 %!assert (datestr (testtime,6), "12/18")
 304 %!assert (datestr (testtime,7), "18")
 305 %!assert (datestr (testtime,8), "Sun")
 306 %!assert (datestr (testtime,9), "S")
 307 %!assert (datestr (testtime,10), "2005")
 308 %!assert (datestr (testtime,11), "05")
 309 %!assert (datestr (testtime,12), "Dec05")
 310 %!assert (datestr (testtime,13), "02:33:17")
 311 %!assert (datestr (testtime,14), " 2:33:17 AM")
 312 %!assert (datestr (testtime,15), "02:33")
 313 %!assert (datestr (testtime,16), " 2:33 AM")
 314 %!assert (datestr (testtime,17), "Q4-05")
 315 %!assert (datestr (testtime,18), "Q4")
 316 %!assert (datestr (testtime,19), "18/12")
 317 %!assert (datestr (testtime,20), "18/12/05")
 318 %!assert (datestr (testtime,21), "Dec.18,2005 02:33:17")
 319 %!assert (datestr (testtime,22), "Dec.18,2005")
 320 %!assert (datestr (testtime,23), "12/18/2005")
 321 %!assert (datestr (testtime,24), "18/12/2005")
 322 %!assert (datestr (testtime,25), "05/12/18")
 323 %!assert (datestr (testtime,26), "2005/12/18")
 324 %!assert (datestr (testtime,27), "Q4-2005")
 325 %!assert (datestr (testtime,28), "Dec2005")
 326 %!assert (datestr (testtime,29), "2005-12-18")
 327 %!assert (datestr (testtime,30), "20051218T023317")
 328 %!assert (datestr (testtime,31), "2005-12-18 02:33:17")
 329 %!assert (datestr (testtime+[0 0 3 0 0 0], "dddd"), "Wednesday")
 330 ## Test possible bug where input is a vector of datenums that is exactly 6 wide
 331 %!assert (datestr ([1944, 6, 6, 6, 30, 0], 0), "06-Jun-1944 06:30:00")
 332 ## Test fractional millisecond time extension
 333 %!assert (datestr (testtime, "HH:MM:SS:FFF"), "02:33:17:382")
 334
 335 %% Test input validation
 336 %!error datestr ()
 337 %!error datestr (1, 2, 3, 4)