feat(time): add hour, minute, second time extraction functions (#1305)

nelson-lang · Dec 14, 2024 · 861ec8a · 861ec8a
1 parent c648d20
commit 861ec8a
Show file tree

Hide file tree

Showing 13 changed files with 534 additions and 5 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `join`: Combine strings.
 - [#1292](http://github.com/nelson-lang/nelson/issues/1292) Large Table Display.
 - [#1290](http://github.com/nelson-lang/nelson/issues/1290) `VariableTypes` property for table: Specify the data types of table in Nelson.
+- `hour`, `minute`, `second` component of input date and time.
 
 ### Changed
 

diff --git a/modules/time/builtin/cpp/datevecBuiltin.cpp b/modules/time/builtin/cpp/datevecBuiltin.cpp
@@ -42,13 +42,17 @@ Nelson::TimeGateway::datevecBuiltin(int nLhs, const ArrayOfVector& argIn)
             for (ompIndexType k = 0; k < (ompIndexType)len; k++) {
                 double DT, Y, M, D, H, MN, S, MS;
                 DT = ptd[k];
-                DateVector(DT, Y, M, D, H, MN, S, MS);
+                DateVector(DT, Y, M, D, H, MN, S, MS, false);
                 res[k] = Y;
                 res[k + len] = M;
                 res[k + len * 2] = D;
                 res[k + len * 3] = H;
                 res[k + len * 4] = MN;
-                res[k + len * 5] = S;
+                if (MS > 1) {
+                    res[k + len * 5] = S + (MS / 1000);
+                } else {
+                    res[k + len * 5] = S;
+                }
             }
             Dimensions dim(len, 6);
             retval << ArrayOf(NLS_DOUBLE, dim, res);
@@ -87,7 +91,7 @@ Nelson::TimeGateway::datevecBuiltin(int nLhs, const ArrayOfVector& argIn)
             for (ompIndexType k = 0; k < (ompIndexType)len; k++) {
                 double DT = ptd[k];
                 double V1, V2, V3, V4, V5, V6, V7;
-                DateVector(DT, V1, V2, V3, V4, V5, V6, V7);
+                DateVector(DT, V1, V2, V3, V4, V5, V6, V7, false);
                 Y[k] = V1;
                 M[k] = V2;
                 if (nLhs > 2) {

diff --git a/modules/time/functions/hour.m b/modules/time/functions/hour.m
@@ -0,0 +1,57 @@
+%=============================================================================
+% Copyright (c) 2016-present Allan CORNET (Nelson)
+%=============================================================================
+% This file is part of the Nelson.
+%=============================================================================
+% LICENCE_BLOCK_BEGIN
+% SPDX-License-Identifier: LGPL-3.0-or-later
+% LICENCE_BLOCK_END
+%=============================================================================
+function varargout = hour(varargin)
+  % Extracts the hour component from a given date/time input.
+  %
+  % Usage:
+  %   h = hour(d)
+  %   h = hour(d, formatDate) 
+  %
+  % Input:
+  %   d - Date/time input (can be a string, char, or numeric).
+  %   formatDate - format date (can be a string, char).
+  %
+  % Output:
+  %   h - Hour component of the input date/time.
+
+  narginchk(1, 2); 
+  nargoutchk(0, 1); % Ensure at most one output argument.
+
+  d = varargin{1};
+  d = convertStringsToChars(d); % Convert strings to char for consistency.
+
+  formatDate = '';
+  if nargin == 2
+    formatDate = convertStringsToChars(varargin{2});
+  end
+
+  % Validate input type
+  if ~(ischar(d) || isstring(d) || isnumeric(d) || iscell(d))
+    error('Invalid date/time format. Input must be a string, char, or numeric.');
+  end
+  % Convert char inputs to numeric using datenum
+  if ~isnumeric(d)
+    d = datenum(d, formatDate); 
+  end
+
+  % Convert numeric or parsed inputs to date vector
+  c = datevec(d(:));
+
+  % Extract hour component
+  h = c(:, 4);
+
+  if ~ischar(d)
+    h = reshape(h, size(d)); % Reshape to match the input size if numeric.
+  end
+
+  varargout{1} = h; % Assign output
+end
+%=============================================================================
+
diff --git a/modules/time/functions/minute.m b/modules/time/functions/minute.m
@@ -0,0 +1,55 @@
+%=============================================================================
+% Copyright (c) 2016-present Allan CORNET (Nelson)
+%=============================================================================
+% This file is part of the Nelson.
+%=============================================================================
+% LICENCE_BLOCK_BEGIN
+% SPDX-License-Identifier: LGPL-3.0-or-later
+% LICENCE_BLOCK_END
+%=============================================================================
+function varargout = minute(varargin)
+  % Extracts the minute component from a given date/time input.
+  %
+  % Usage:
+  %   m = minute(d)
+  %   m = minute(d, formatDate) 
+  %
+  % Input:
+  %   d - Date/time input (can be a string, char, or numeric).
+  %   formatDate - format date (can be a string, char).
+  %
+  % Output:
+  %   m - Minute component of the input date/time.
+
+  narginchk(1, 2);
+  nargoutchk(0, 1);
+
+  inputDate = varargin{1};
+  inputDate = convertStringsToChars(inputDate);
+
+  dateFormat = '';
+  if nargin == 2
+    dateFormat = convertStringsToChars(varargin{2});
+  end
+
+  if ischar(inputDate)
+    inputDate = datenum(inputDate, dateFormat);
+    inputSize = size(inputDate);
+  elseif iscell(inputDate)
+    inputSize = size(inputDate);
+    inputDate = datenum(inputDate, dateFormat);
+  elseif isnumeric(inputDate)
+    inputSize = size(inputDate);
+  else
+    error(_('Invalid date/time format. Input must be a string, char, or numeric.'));
+  end
+
+  dateVector = datevec(inputDate(:));
+  minuteValues = dateVector(:, 5);
+
+  requiresMinuteIncrement = (dateVector(:, 6) > 59.5);
+  minuteValues(requiresMinuteIncrement) = minuteValues(requiresMinuteIncrement) + 1;
+
+  varargout{1} = reshape(minuteValues, inputSize);
+end
+%=============================================================================
diff --git a/modules/time/functions/second.m b/modules/time/functions/second.m
@@ -0,0 +1,53 @@
+%=============================================================================
+% Copyright (c) 2016-present Allan CORNET (Nelson)
+%=============================================================================
+% This file is part of the Nelson.
+%=============================================================================
+% LICENCE_BLOCK_BEGIN
+% SPDX-License-Identifier: LGPL-3.0-or-later
+% LICENCE_BLOCK_END
+%=============================================================================
+function varargout = second(varargin)
+  % Extracts the second component from a given date/time input.
+  %
+  % Usage:
+  %   s = second(d)
+  %   s = second(d, formatDate) 
+  %
+  % Input:
+  %   d - Date/time input (can be a string, char, or numeric).
+  %   formatDate - format date (can be a string, char).
+  %
+  % Output:
+  %   s - Second component of the input date/time.
+
+  narginchk(1, 2);
+  nargoutchk(0, 1);
+
+  inputDate = varargin{1};
+  inputDate = convertStringsToChars(inputDate);
+
+  dateFormat = '';
+  if nargin == 2
+    dateFormat = convertStringsToChars(varargin{2});
+  end
+
+  if ischar(inputDate)
+    inputDate = datenum(inputDate, dateFormat);
+    inputSize = size(inputDate);
+  elseif iscell(inputDate)
+    inputSize = size(inputDate);
+    inputDate = datenum(inputDate, dateFormat);
+  elseif isnumeric(inputDate)
+    inputSize = size(inputDate);
+  else
+    error(_('Invalid date/time format. Input must be a string, char, or numeric.'));
+  end
+
+  dateVector = datevec(inputDate(:));
+  secondValues = dateVector(:, 6);
+
+  secondValues = round(1000 .* secondValues) ./ 1000;
+  varargout{1} = reshape(secondValues, inputSize);
+end
+%=============================================================================
diff --git a/modules/time/help/en_US/xml/hour.xml b/modules/time/help/en_US/xml/hour.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xmldoc>
+  <copyright>SAME AS NELSON SOFTWARE</copyright>
+
+  <language>en_US</language>
+  <keyword>hour</keyword>
+  <short_description>Hours part of the input date and time.</short_description>
+
+  <syntax>
+    <syntax_item>h = hour(t)</syntax_item>
+    <syntax_item>h = hour(t, formatIn)</syntax_item>
+  </syntax>
+
+  <param_input>
+    <param_input_item>
+      <param_name>t</param_name>
+      <param_description>serial date number or text inputs</param_description>
+    </param_input_item>
+    <param_input_item>
+      <param_name>formatIn</param_name>
+      <param_description>valid date format</param_description>
+    </param_input_item>
+   </param_input>
+
+
+  <param_output>
+    <param_output_item>
+      <param_name>h</param_name>
+      <param_description>a double: integer value.</param_description>
+    </param_output_item>
+  </param_output>
+
+  <description>
+  <p><b
+      >h = hour(t)</b> extracts the hour component from each date and time specified in <b
+      >t</b>.</p>
+  <p>The output <b
+      >h</b> is a double array containing integer values ranging from 0 to 23.</p>  
+  </description>
+  <used_function />
+  <bibliography />
+
+<examples>
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data
+      ><![CDATA[h = hour(738427.656845093)
+h = hour("2021/09/28 15:45:51", 'YYYY/M/DD HH:MM:SS')
+]]>
+    </example_item_data>
+  </example_item>
+
+</examples>
+
+  <see_also>
+    <see_also_item>
+      <link linkend="${time}minute">minute</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${time}second">second</link>
+    </see_also_item>
+
+  </see_also>
+
+  <history>
+    <history_item>
+      <history_version>1.10.0</history_version>
+      <history_description>initial version</history_description>
+    </history_item>
+  </history>
+
+  <authors>
+    <author_item>Allan CORNET</author_item>
+  </authors>
+</xmldoc>
diff --git a/modules/time/help/en_US/xml/minute.xml b/modules/time/help/en_US/xml/minute.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xmldoc>
+  <copyright>SAME AS NELSON SOFTWARE</copyright>
+
+  <language>en_US</language>
+  <keyword>minute</keyword>
+  <short_description
+  >Minutes part of the input date and time.</short_description>
+
+  <syntax>
+    <syntax_item>m = minute(t)</syntax_item>
+    <syntax_item>m = minute(t, formatIn)</syntax_item>
+  </syntax>
+
+  <param_input>
+    <param_input_item>
+      <param_name>t</param_name>
+      <param_description>serial date number or text inputs</param_description>
+    </param_input_item>
+    <param_input_item>
+      <param_name>formatIn</param_name>
+      <param_description>valid date format</param_description>
+    </param_input_item>
+   </param_input>
+
+
+  <param_output>
+    <param_output_item>
+      <param_name>m</param_name>
+      <param_description>a double: integer value.</param_description>
+    </param_output_item>
+  </param_output>
+
+  <description>
+  <p><b
+      >m = minute(t)</b> extracts the minute component from each date and time specified in <b
+      >t</b>.</p>
+  <p>The output <b
+      >m</b> is a double array containing integer values ranging from 0 to 59.</p>  
+  </description>
+  <used_function />
+  <bibliography />
+
+<examples>
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data
+      ><![CDATA[m = minute(738427.656845093)
+m = minute("2021/09/28 15:45:51", 'YYYY/M/DD HH:MM:SS')
+]]>
+    </example_item_data>
+  </example_item>
+
+</examples>
+
+  <see_also>
+    <see_also_item>
+      <link linkend="${time}hour">hour</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${time}second">second</link>
+    </see_also_item>
+
+  </see_also>
+
+  <history>
+    <history_item>
+      <history_version>1.10.0</history_version>
+      <history_description>initial version</history_description>
+    </history_item>
+  </history>
+
+  <authors>
+    <author_item>Allan CORNET</author_item>
+  </authors>
+</xmldoc>