Fix #1250 - head, tail functions for table

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.9.0 (UNRELEASED)
+
+### Added
+
+- [#1250](http://github.com/nelson-lang/nelson/issues/1250) `head`, `tail` functions for table and array.
+
 ## 1.8.0 (2024-10-04)
 
 ### Added

modules/table/functions/head.m

@@ -0,0 +1,31 @@
+%=============================================================================
+% 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 = head(varargin)
+    narginchk(1, 2);
+    nargoutchk(0, 1);
+    if nargin < 2
+        k = 8;
+    else
+        k = varargin{2};
+    end
+    A = varargin{1};
+    k = min(k, size(A, 1));
+    mustBeInteger(k, 2);
+    mustBeGreaterThanOrEqual(k, 0, 2);
+    out = A(1:k, :);
+
+    if nargout > 0
+        varargout{1} = out;
+    else
+        disp(out);
+    end    
+end
+%=============================================================================
+

modules/table/functions/tail.m

@@ -0,0 +1,32 @@
+%=============================================================================
+% 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 = tail(varargin)
+    narginchk(1, 2);
+    nargoutchk(0, 1);
+    if nargin < 2
+        k = 8;
+    else
+        k = varargin{2};
+    end
+    A = varargin{1};
+    k = min(k, size(A, 1));
+    mustBeInteger(k, 2);
+    mustBeGreaterThanOrEqual(k, 0, 2);
+
+    out = A(size(A, 1) - k + 1:size(A, 1), :);
+
+    if nargout > 0
+        varargout{1} = out;
+    else
+        disp(out);
+    end    
+end
+%=============================================================================
+

modules/table/help/en_US/xml/head.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xmldoc>
+  <copyright>SAME AS NELSON SOFTWARE</copyright>
+
+  <language>en_US</language>
+  <keyword>head</keyword>
+  <short_description>Get top rows of table or array.</short_description>
+
+  <syntax>
+    <syntax_item>head(A)</syntax_item>
+    <syntax_item>head(A, k)</syntax_item>
+    <syntax_item>B = head(...)</syntax_item>
+  </syntax>
+
+  <param_input>
+
+    <param_input_item>
+      <param_name>A</param_name>
+      <param_description>Input array (table or other).</param_description>
+    </param_input_item>
+
+  </param_input>
+
+  <param_output>
+    <param_output_item>
+      <param_name>k</param_name>
+      <param_description
+      >a integer value: Number of rows to extract (k = 8 by default).</param_description>
+    </param_output_item>
+  </param_output>
+
+  <description>
+    <p><b>head(A)</b> displays the first eight rows of an array, or table <b
+      >A</b> in the Command Window without assigning it to a variable.</p>
+    <p><b>head(A, k)</b> displays the first k rows of A.</p>
+    <p><b>B = head(...)</b> returns the specified rows of <b
+      >A</b> for any of the previous syntaxes, with <b
+      >B</b> having the same data type as <b>A</b>.</p>
+  </description>
+  <used_function />
+  <bibliography />
+
+<examples>
+
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data
+      ><![CDATA[LastName = {'Sanchez';'Johnson';'Li';'Diaz';'Brown'};
+Age = [38;43;38;40;49];
+Smoker = logical([1;0;1;0;1]);
+Height = [71;69;64;67;64];
+Weight = [176;163;131;133;119];
+BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];
+T = table(LastName, Age, Smoker, Height, Weight, BloodPressure)
+head(T, 2)]]>
+    </example_item_data>
+  </example_item>
+
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data><![CDATA[A = repmat((1:50)',1, 3);
+head(A)]]>
+    </example_item_data>
+  </example_item>
+
+</examples>
+
+  <see_also>
+    <see_also_item>
+      <link linkend="${table}tail">tail</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${table}table">table</link>
+    </see_also_item>
+
+  </see_also>
+
+  <history>
+    <history_item>
+      <history_version>1.9.0</history_version>
+      <history_description>initial version</history_description>
+    </history_item>
+  </history>
+
+  <authors>
+    <author_item>Allan CORNET</author_item>
+  </authors>
+</xmldoc>

modules/table/help/en_US/xml/tail.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xmldoc>
+  <copyright>SAME AS NELSON SOFTWARE</copyright>
+
+  <language>en_US</language>
+  <keyword>tail</keyword>
+  <short_description>Get bottom rows of table or array.</short_description>
+
+  <syntax>
+    <syntax_item>tail(A)</syntax_item>
+    <syntax_item>tail(A, k)</syntax_item>
+    <syntax_item>B = tail(...)</syntax_item>
+  </syntax>
+
+  <param_input>
+
+    <param_input_item>
+      <param_name>A</param_name>
+      <param_description>Input array (table or other).</param_description>
+    </param_input_item>
+
+  </param_input>
+
+  <param_output>
+    <param_output_item>
+      <param_name>k</param_name>
+      <param_description
+      >a integer value: Number of rows to extract (k = 8 by default).</param_description>
+    </param_output_item>
+  </param_output>
+
+  <description>
+    <p><b>tail(A)</b> displays the last eight rows of an array, or table <b
+      >A</b> in the Command Window without assigning it to a variable.</p>
+    <p><b>tail(A, k)</b> displays the last k rows of A.</p>
+    <p><b>B = tail(...)</b> returns the specified rows of <b
+      >A</b> for any of the previous syntaxes, with <b
+      >B</b> having the same data type as <b>A</b>.</p>
+  </description>
+  <used_function />
+  <bibliography />
+
+<examples>
+
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data
+      ><![CDATA[LastName = {'Sanchez';'Johnson';'Li';'Diaz';'Brown'};
+Age = [38;43;38;40;49];
+Smoker = logical([1;0;1;0;1]);
+Height = [71;69;64;67;64];
+Weight = [176;163;131;133;119];
+BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];
+T = table(LastName, Age, Smoker, Height, Weight, BloodPressure)
+tail(T, 2)]]>
+    </example_item_data>
+  </example_item>
+
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data><![CDATA[A = repmat((1:50)',1, 3);
+tail(A)]]>
+    </example_item_data>
+  </example_item>
+
+</examples>
+
+  <see_also>
+    <see_also_item>
+      <link linkend="${table}head">head</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${table}table">table</link>
+    </see_also_item>
+
+  </see_also>
+
+  <history>
+    <history_item>
+      <history_version>1.9.0</history_version>
+      <history_description>initial version</history_description>
+    </history_item>
+  </history>
+
+  <authors>
+    <author_item>Allan CORNET</author_item>
+  </authors>
+</xmldoc>

modules/table/tests/test_head.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
+%=============================================================================
+LastName = {'Sanchez';'Johnson';'Li';'Diaz';'Brown'};
+Age = [38;43;38;40;49];
+Smoker = logical([1;0;1;0;1]);
+Height = [71;69;64;67;64];
+Weight = [176;163;131;133;119];
+BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];
+T = table(LastName, Age, Smoker, Height, Weight, BloodPressure);
+R = evalc('head(T, 2)');
+REF =    '    LastName       Age    Smoker    Height    Weight    BloodPressure    
+    ___________    ___    ______    ______    ______    _____________    
+
+    {''Sanchez''}    38     true      71        176       124    93        
+    {''Johnson''}    43     false     69        163       109    77        
+
+';
+assert_isequal(R, REF);
+%=============================================================================
+A = repmat((1:100)',1,4);
+R = evalc('head(A)');
+REF =  '     1     1     1     1
+     2     2     2     2
+     3     3     3     3
+     4     4     4     4
+     5     5     5     5
+     6     6     6     6
+     7     7     7     7
+     8     8     8     8
+
+';
+assert_isequal(R, REF);
+%=============================================================================
+R = evalc('head(A, 2)');
+REF =   '     1     1     1     1
+     2     2     2     2
+
+';
+assert_isequal(R, REF); 
+%=============================================================================
+R = head(A, 8);
+REF = repmat((1:8)', 1, 4);
+assert_isequal(R, REF);
+%=============================================================================
+msg = sprintf(_('Invalid input argument at position %d.\nValue must be greater than or equal to %d.'), 2, 0);
+assert_checkerror('head(A, -1)', msg, 'Nelson:validators:mustBeGreaterThanOrEqual');
+%=============================================================================
+msg = sprintf(_('Invalid input argument at position %d.\nValue must be integer.'), 2);
+assert_checkerror('head(A, 1.2)', msg);
+%=============================================================================

modules/table/tests/test_tail.m

@@ -0,0 +1,34 @@
+%=============================================================================
+% 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
+%=============================================================================
+LastName = {'Sanchez';'Johnson';'Li';'Diaz';'Brown'};
+Age = [38;43;38;40;49];
+Smoker = logical([1;0;1;0;1]);
+Height = [71;69;64;67;64];
+Weight = [176;163;131;133;119];
+BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];
+T = table(LastName, Age, Smoker, Height, Weight, BloodPressure);
+R = evalc('tail(T, 2)');
+REF =  '    LastName     Age    Smoker    Height    Weight    BloodPressure    
+    _________    ___    ______    ______    ______    _____________    
+
+    {''Diaz''}     40     false     67        133       117    75        
+    {''Brown''}    49     true      64        119       122    80        
+
+';
+assert_isequal(R, REF);
+%=============================================================================
+A = repmat((1:100)', 1, 4);
+R = evalc('tail(A, 2)');
+REF = '    99    99    99    99
+   100   100   100   100
+
+';
+assert_isequal(R, REF);
+%=============================================================================

modules/validators/builtin/cpp/mustBeGreaterThanBuiltin.cpp

@@ -20,7 +20,7 @@ Nelson::ValidatorsGateway::mustBeGreaterThanBuiltin(int nLhs, const ArrayOfVecto
 {
     ArrayOfVector retval;
     nargoutcheck(nLhs, 0, 0);
-    nargincheck(argIn, 1, 3);
+    nargincheck(argIn, 2, 3);
     int argPos = -1;
     if (argIn.size() == 3) {
         ArrayOf param3 = argIn[2];

modules/validators/builtin/cpp/mustBeGreaterThanOrEqualBuiltin.cpp

@@ -20,7 +20,7 @@ Nelson::ValidatorsGateway::mustBeGreaterThanOrEqualBuiltin(int nLhs, const Array
 {
     ArrayOfVector retval;
     nargoutcheck(nLhs, 0, 0);
-    nargincheck(argIn, 1, 3);
+    nargincheck(argIn, 2, 3);
     int argPos = -1;
     if (argIn.size() == 3) {
         ArrayOf param3 = argIn[2];

modules/validators/builtin/cpp/mustBeLessThanBuiltin.cpp

@@ -20,7 +20,7 @@ Nelson::ValidatorsGateway::mustBeLessThanBuiltin(int nLhs, const ArrayOfVector&
 {
     ArrayOfVector retval;
     nargoutcheck(nLhs, 0, 0);
-    nargincheck(argIn, 1, 3);
+    nargincheck(argIn, 2, 3);
     int argPos = -1;
     if (argIn.size() == 3) {
         ArrayOf param3 = argIn[2];

modules/validators/builtin/cpp/mustBeLessThanOrEqualBuiltin.cpp

@@ -20,7 +20,7 @@ Nelson::ValidatorsGateway::mustBeLessThanOrEqualBuiltin(int nLhs, const ArrayOfV
 {
     ArrayOfVector retval;
     nargoutcheck(nLhs, 0, 0);
-    nargincheck(argIn, 1, 3);
+    nargincheck(argIn, 2, 3);
     int argPos = -1;
     if (argIn.size() == 3) {
         ArrayOf param3 = argIn[2];