readmatrix function

CHANGELOG.md

@@ -10,10 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `detectImportOptions`: Generate import options from the file's content.
-- `readcell`: Read cell array from file.
 - `readtable`: Read table from file.
 - `writetable`: Write table to file.
+- `readcell`: Read cell array from file.
 - `writecell`: write cell array to file.
+- `readmatrix`: read matrix from file.
 - `writematrix`: write matrix to file.
 - `csvread`: Read comma-separated value (CSV) file.
 - `csvwrite`: Write comma-separated value (CSV) file.

modules/spreadsheet/builtin/c/nlsSpreadsheet_builtin.vcxproj

@@ -218,6 +218,7 @@
     <ClCompile Include="..\cpp\Gateway.cpp" />
     <ClCompile Include="..\cpp\dllMain.cpp" />
     <ClCompile Include="..\cpp\readcellBuiltin.cpp" />
+    <ClCompile Include="..\cpp\readmatrixBuiltin.cpp" />
     <ClCompile Include="..\cpp\readtableBuiltin.cpp" />
     <ClCompile Include="..\cpp\writetableBuiltin.cpp" />
   </ItemGroup>
@@ -227,6 +228,7 @@
     <ClInclude Include="..\include\dlmwriteBuiltin.hpp" />
     <ClInclude Include="..\include\nlsSpreadsheet_builtin_exports.h" />
     <ClInclude Include="..\include\readcellBuiltin.hpp" />
+    <ClInclude Include="..\include\readmatrixBuiltin.hpp" />
     <ClInclude Include="..\include\readtableBuiltin.hpp" />
     <ClInclude Include="..\include\writetableBuiltin.hpp" />
   </ItemGroup>

modules/spreadsheet/builtin/c/nlsSpreadsheet_builtin.vcxproj.filters

@@ -53,6 +53,9 @@
     <ClCompile Include="..\cpp\readtableBuiltin.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\cpp\readmatrixBuiltin.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="..\include\nlsSpreadsheet_builtin_exports.h">
@@ -76,5 +79,8 @@
     <ClInclude Include="..\include\readtableBuiltin.hpp">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="..\include\readmatrixBuiltin.hpp">
+      <Filter>Header Files</Filter>
+    </ClInclude>
   </ItemGroup>
 </Project>

modules/spreadsheet/builtin/cpp/Gateway.cpp

@@ -9,6 +9,7 @@
 //=============================================================================
 #include "NelsonGateway.hpp"
 #include "readcellBuiltin.hpp"
+#include "readmatrixBuiltin.hpp"
 #include "readtableBuiltin.hpp"
 #include "dlmreadBuiltin.hpp"
 #include "dlmwriteBuiltin.hpp"
@@ -21,14 +22,14 @@ const std::wstring gatewayName = L"spreadsheet";
 //=============================================================================
 static const nlsGateway gateway[] = {
     { "readcell", (ptrBuiltin)Nelson::SpreadsheetGateway::readcellBuiltin, 1, 1 },
+    { "readmatrix", (ptrBuiltin)Nelson::SpreadsheetGateway::readmatrixBuiltin, 1, 1 },
     { "readtable", (ptrBuiltin)Nelson::SpreadsheetGateway::readtableBuiltin, 1, 1 },
     { "dlmread", (ptrBuiltin)Nelson::SpreadsheetGateway::dlmreadBuiltin, 1, 4 },
     { "dlmwrite", (ptrBuiltin)Nelson::SpreadsheetGateway::dlmwriteBuiltin, 0, -3,
         CPP_BUILTIN_WITH_EVALUATOR },
     { "writetable", (ptrBuiltin)Nelson::SpreadsheetGateway::writetableBuiltin, 0, 4 },
     { "detectImportOptions", (ptrBuiltin)Nelson::SpreadsheetGateway::detectImportOptionsBuiltin, 1,
         -1 },
-
 };
 //=============================================================================
 NLSGATEWAYFUNC(gateway)

modules/spreadsheet/builtin/cpp/readmatrixBuiltin.cpp

@@ -0,0 +1,123 @@
+//=============================================================================
+// 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
+//=============================================================================
+#include <map>
+#include "readmatrixBuiltin.hpp"
+#include "Error.hpp"
+#include "InputOutputArgumentsCheckers.hpp"
+#include "ReadMatrix.hpp"
+#include "DetectImportOptions.hpp"
+//=============================================================================
+using namespace Nelson;
+//=============================================================================
+static NelsonType
+convertToNelsonType(const std::wstring& typeStr);
+static void
+populateImportOptions(const ArrayOf& importOptionsObj, detectImportOptions& options);
+//=============================================================================
+ArrayOfVector
+Nelson::SpreadsheetGateway::readmatrixBuiltin(int nLhs, const ArrayOfVector& argIn)
+{
+    ArrayOfVector retval;
+    nargoutcheck(nLhs, 0, 1);
+    nargincheck(argIn, 1, 4);
+    std::wstring filename = argIn[0].getContentAsWideString();
+    std::string errorMessage;
+    detectImportOptions options;
+    NelsonType OutputType = NLS_DOUBLE;
+    initializeDetectImportOptions(options);
+
+    switch (argIn.size()) {
+    case 1: {
+        // readmatrix(filename)
+        analyzeFileFormatImportOptions(filename, 4096, options, errorMessage);
+        options.CommentStyle.clear();
+        if (!errorMessage.empty()) {
+            Error(errorMessage);
+        }
+    } break;
+    case 2: {
+        // readmatrix(filename, options)
+        if (argIn[1].isClassType() && argIn[1].getClassType() == "DelimitedTextImportOptions") {
+            populateImportOptions(argIn[1], options);
+        } else {
+            Error(_W("Import options object expected."));
+        }
+    } break;
+    case 3: {
+        // readmatrix(filename, 'fieldname', fieldvalue)
+        std::wstring fieldname = argIn[1].getContentAsWideString();
+        if (fieldname != L"OutputType") {
+            Error(_W("OutputType name expected."));
+        }
+        OutputType = convertToNelsonType(argIn[2].getContentAsWideString());
+        analyzeFileFormatImportOptions(filename, 4096, options, errorMessage);
+        options.CommentStyle.clear();
+        if (!errorMessage.empty()) {
+            Error(errorMessage);
+        }
+    } break;
+    case 4: {
+        // readmatrix(filename, options, 'fieldname', fieldvalue)
+        if (argIn[1].isClassType() && argIn[1].getClassType() == "DelimitedTextImportOptions") {
+            populateImportOptions(argIn[1], options);
+        } else {
+            Error(_W("Import options object expected."));
+        }
+        std::wstring fieldname = argIn[2].getContentAsWideString();
+        if (fieldname != L"OutputType") {
+            Error(_W("OutputType name expected."));
+        }
+        OutputType = convertToNelsonType(argIn[3].getContentAsWideString());
+    } break;
+    default: {
+    } break;
+    }
+
+    retval << ReadMatrix(filename, options, OutputType, errorMessage);
+    if (!errorMessage.empty()) {
+        Error(errorMessage);
+    }
+    return retval;
+}
+//=============================================================================
+NelsonType
+convertToNelsonType(const std::wstring& typeStr)
+{
+    static const std::map<std::wstring, NelsonType> typeMap
+        = { { L"double", NLS_DOUBLE }, { L"single", NLS_SINGLE }, { L"string", NLS_STRING_ARRAY },
+              { L"char", NLS_CELL_ARRAY }, { L"int8", NLS_INT8 }, { L"int16", NLS_INT16 },
+              { L"int32", NLS_INT32 }, { L"int64", NLS_INT64 }, { L"uint8", NLS_UINT8 },
+              { L"uint16", NLS_UINT16 }, { L"uint32", NLS_UINT32 }, { L"uint64", NLS_UINT64 } };
+
+    auto it = typeMap.find(typeStr);
+    if (it != typeMap.end()) {
+        return it->second;
+    }
+
+    Error(_W("Unsupported type."));
+    return NLS_DOUBLE;
+}
+//=============================================================================
+void
+populateImportOptions(const ArrayOf& importOptionsObj, detectImportOptions& options)
+{
+    options.Delimiter = importOptionsObj.getField("Delimiter").getContentAsCStringRowVector();
+    options.LineEnding = importOptionsObj.getField("LineEnding").getContentAsCStringRowVector();
+    options.CommentStyle = importOptionsObj.getField("CommentStyle").getContentAsCStringRowVector();
+    options.EmptyLineRule = importOptionsObj.getField("EmptyLineRule").getContentAsCString();
+    options.VariableNamesLine
+        = (int)importOptionsObj.getField("VariableNamesLine").getContentAsDoubleScalar();
+    options.VariableNames
+        = importOptionsObj.getField("VariableNames").getContentAsCStringRowVector();
+    options.RowNamesColumn
+        = (int)importOptionsObj.getField("RowNamesColumn").getContentAsDoubleScalar();
+    options.DataLines = importOptionsObj.getField("DataLines").getContentAsDoubleVector();
+}
+//=============================================================================

modules/spreadsheet/builtin/include/readmatrixBuiltin.hpp

@@ -0,0 +1,20 @@
+//=============================================================================
+// 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
+//=============================================================================
+#pragma once
+//=============================================================================
+#include "ArrayOf.hpp"
+//=============================================================================
+namespace Nelson::SpreadsheetGateway {
+//=============================================================================
+ArrayOfVector
+readmatrixBuiltin(int nLhs, const ArrayOfVector& argIn);
+//=============================================================================
+} // namespace Nelson
+//=============================================================================

modules/spreadsheet/help/en_US/xml/detectImportOptions.xml

@@ -35,6 +35,22 @@
       >readmatrix</b> to control how Nelson imports data as a table, cell array, or matrix.</p>
   <p
     >The type of the returned options object depends on the file's extension.</p>
+
+    <p />
+  <p>Properties:</p>
+  <p><b>Delimiter</b>: Field delimiter characters. example: {','} </p>
+  <p><b>LineEnding</b>: End-of-line characters. example: {'\r\n'}</p>
+  <p><b>CommentStyle</b>: Style of comments. example: {'#'}</p>
+  <p><b>EmptyLineRule</b>: Procedure to handle empty lines. example: 'skip'</p>
+  <p><b>VariableNamesLine</b>: Variable names location. example: 1</p>
+  <p><b
+      >VariableNames</b>: Variable names. example: {'Names'  'Age'  'Height'  'Weight'}</p>
+  <p><b>RowNamesColumn</b>:  Row names location. example: 0</p>
+  <p><b>DataLines</b>: Data location, <b
+      >[l1 l2]</b> Indicate the range of lines containing the data. <b
+      >l1</b> refers to the first line with data, while <b
+      >l2</b> refers to the last line. example: [2  Inf]</p>
+
 </description>
 
   <used_function />

modules/spreadsheet/help/en_US/xml/readmatrix.xml

@@ -0,0 +1,123 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<xmldoc>
+  <copyright>SAME AS NELSON SOFTWARE</copyright>
+
+  <language>en_US</language>
+  <keyword>readmatrix</keyword>
+  <short_description>Create matrix array from file.</short_description>
+
+  <syntax>
+    <syntax_item>M = readmatrix(filename)</syntax_item>
+    <syntax_item>M = readmatrix(filename, opts)</syntax_item>
+    <syntax_item
+    >M = readmatrix(filename, opts, 'OutputType', type)</syntax_item>
+
+  </syntax>
+
+  <param_input>
+    <param_input_item>
+      <param_name>filename</param_name>
+      <param_description
+      >a string: an existing filename source.</param_description>
+    </param_input_item>
+
+    <param_input_item>
+      <param_name>opts</param_name>
+      <param_description>DelimitedTextImportOptions object</param_description>
+    </param_input_item>
+
+    <param_input_item>
+      <param_name>type</param_name>
+      <param_description
+      >a string: 'double', 'single', 'char', 'string', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64'.</param_description>
+    </param_input_item>
+
+  </param_input>
+
+  <param_output>
+    <param_output_item>
+      <param_name>M</param_name>
+      <param_description>a matrix.</param_description>
+    </param_output_item>
+  </param_output>
+
+
+<description>
+  <p><b
+      >M = readmatrix(filename)</b> creates a matrix array by importing column-oriented data from a text or spreadsheet file.</p>
+  <p><b
+      >M = readmatrix(filename, opts)</b> creates a matrix array using the settings defined in the <b
+      >opts</b> import options object. The import <b
+      >options</b> object allows you to customize how <b
+      >readmatrix</b> interprets the file, offering greater control, improved performance, and the ability to reuse the configuration compared to the default syntax.</p>
+</description>
+
+  <used_function />
+  <bibliography />
+
+<examples>
+
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data>
+filename = [tempdir,'readmatrix_1.csv'];
+Names = {'John'; 'Alice'; 'Bob'; 'Diana'};
+Age = [28; 34; 22; 30];
+Height = [175; 160; 180; 165];
+Weight = [70; 55; 80; 60];
+T = table(Names, Age, Height, Weight);
+writetable(T, filename)
+M = readmatrix(filename)
+</example_item_data>
+
+  </example_item>
+
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data>
+filename = [tempdir,'readmatrix_2.csv'];
+M = magic(6);
+writematrix(M, filename)
+options = detectImportOptions(filename)
+options.DataLines = [2 4];
+M2 = readmatrix(filename, options, 'OutputType', 'int64')
+M3 = readmatrix(filename, options, 'OutputType', 'char')
+
+</example_item_data>
+
+  </example_item>
+
+</examples>
+  <see_also>
+    <see_also_item>
+      <link linkend="${spreadsheet}writematrix">writematrix</link>
+    </see_also_item>
+    <see_also_item>
+      <link
+        linkend="${spreadsheet}detectImportOptions"
+      >detectImportOptions</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${spreadsheet}writetable">writetable</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${spreadsheet}readtable">readtable</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${stream_manager}fileread">fileread</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>

modules/spreadsheet/src/c/nlsSpreadsheet.vcxproj

@@ -208,11 +208,14 @@
     <ClCompile Include="..\cpp\CSVRangeConverter.cpp" />
     <ClCompile Include="..\cpp\CSVSeparatorDetector.cpp" />
     <ClCompile Include="..\cpp\CSVTableWriter.cpp" />
+    <ClCompile Include="..\cpp\CSVTypeConverters.cpp" />
     <ClCompile Include="..\cpp\DelimitedFileWriter.cpp" />
     <ClCompile Include="..\cpp\DelimitedFileReader.cpp" />
     <ClCompile Include="..\cpp\DetectImportOptions.cpp" />
     <ClCompile Include="..\cpp\dllMain.cpp" />
     <ClCompile Include="..\cpp\ReadCell.cpp" />
+    <ClCompile Include="..\cpp\ReadLinesFromFile.cpp" />
+    <ClCompile Include="..\cpp\ReadMatrix.cpp" />
     <ClCompile Include="..\cpp\ReadTable.cpp" />
     <ClCompile Include="..\cpp\TableWriter.cpp" />
     <ClCompile Include="..\cpp\WriteTable.cpp" />
@@ -221,8 +224,10 @@
   <ItemGroup>
     <ClInclude Include="..\cpp\CSVSeparatorDetector.hpp" />
     <ClInclude Include="..\cpp\CSVTableWriter.hpp" />
+    <ClInclude Include="..\cpp\CSVTypeConverters.hpp" />
     <ClInclude Include="..\cpp\ITableWriter.hpp" />
     <ClInclude Include="..\cpp\rapidcsv.h" />
+    <ClInclude Include="..\cpp\ReadLinesFromFile.hpp" />
     <ClInclude Include="..\cpp\TableWriter.hpp" />
     <ClInclude Include="..\cpp\XmlTableWriter.hpp" />
     <ClInclude Include="..\include\CSVRangeConverter.hpp" />
@@ -231,6 +236,7 @@
     <ClInclude Include="..\include\DetectImportOptions.hpp" />
     <ClInclude Include="..\include\nlsSpreadsheet_exports.h" />
     <ClInclude Include="..\include\ReadCell.hpp" />
+    <ClInclude Include="..\include\ReadMatrix.hpp" />
     <ClInclude Include="..\include\ReadTable.hpp" />
     <ClInclude Include="..\include\WriteTable.hpp" />
   </ItemGroup>