Skip to content

Latest commit

 

History

History
93 lines (77 loc) · 3.1 KB

README.md

File metadata and controls

93 lines (77 loc) · 3.1 KB

Maven Central javadoc

matrix-csv

Comprehensive support for creating a Matrix from structured text files (CSV files) and writing a Matrix to a CSV file in the format of choice.

To use it in your project, add the following dependencies to your code

implementation 'se.alipsa.groovy:matrix-core:2.1.1'
implementation 'se.alipsa.groovy:matrix-csv:1.1.0'

Import a CSV file into a Matrix

Matrix-csv uses apache-commons csv to parse the csv file. Here is a simple example:

import org.apache.commons.csv.CSVFormat
import se.alipsa.matrix.core.Matrix
import se.alipsa.matrix.matrixcsv.CsvImporter

URL url = getClass().getResource("/basic.csv")
CSVFormat format = CSVFormat.Builder.create().setTrim(true).build()
Matrix basic = CsvImporter.importCsv(url, format)

For more advanced cases see the apache commons csv user guide

A slightly more complicated example: Given the following text file:

1;"Per";"2023-Apr-30";234,12
2;"Karin";"2023-May-10";345,22

3;"Tage";"2023-Jun-20";3489,01
4;"Arne";"2023-Jul-01";222,99

...we can parse as follows:

import org.apache.commons.csv.CSVFormat
import se.alipsa.matrix.core.Matrix
import se.alipsa.matrix.matrixcsv.CsvImporter

URL url = getClass().getResource("/colonQuotesEmptyLine.csv")
CSVFormat format = CSVFormat.Builder.create()
    .setTrim(true)
    .setDelimiter(';')
    .setIgnoreEmptyLines(true)
    .setQuote('"' as Character)
    .setHeader('id', 'name', 'date', 'amount')
    .build()
Matrix matrix = CsvImporter.importCsv(url, format)

The resulting Matrix will be all strings. To convert the content to the appropriate type, use the convert method e.g.

Matrix table = matrix.convert(
  [
      "id": Integer, 
      "name": String, 
      "date": LocalDate, 
      "amount": BigDecimal
  ],
  DateTimeFormatter.ofPattern("yyyy-MMM-dd"),
  NumberFormat.getInstance(Locale.GERMANY)
)
//the following assertions then applies
assert 4 == table.rowCount() // Number of rows
assert ['id', 'name', 'date', 'amount'] == table.columnNames() // Column names
assert [4, 'Arne', LocalDate.parse('2023-07-01'), 222.99] == table.row(3) // last row

Exporting a Matrix to a CSV file

import se.alipsa.matrix.datasets.Dataset
import se.alipsa.matrix.matrixcsv.CsvExporter
import org.apache.commons.csv.CSVFormat

File file = File.createTempFile('mtcars', '.csv')
CsvExporter.exportToCsv(Dataset.mtcars(), CSVFormat.DEFAULT, file)

exportToCsv() takes a File or a Writer as output parameter.

Release version compatibility matrix

The following table illustrates the version compatibility of the matrix-csv and matrix core

Matrix csv Matrix core
1.0.0 1.2.3 -> 1.2.4
1.0.1 2.0.0 -> 2.1.1
1.1.0 2.2.0