README
¶
BDataMatrix - Structured Tabular Data Management in Go
BDataMatrix is a lightweight Go library for managing structured tabular data efficiently. It provides functions to add, update, delete, sort, and query data, along with various export options such as CSV, TSV, JSON, and YAML.
Installation
To install BDataMatrix, run:
go get github.com/bearaujus/bdatamatrix
Import
import "github.com/bearaujus/bdatamatrix"
Features
- Create structured tabular data with defined headers.
- Add, update, delete, and search rows efficiently.
- Export data to CSV, TSV, JSON, YAML, or custom formats.
- Track header indices for optimized querying.
- Support for case-insensitive searching.
Usage
1. Creating a Matrix
Create a new matrix with headers:
matrix, err := bdatamatrix.New("ID", "Name", "Age")
if err != nil {
log.Fatal(err)
}
Create a matrix with predefined data:
rows := [][]string{
{"1", "Alice", "30"},
{"2", "Bob", "25"},
}
matrix, err := bdatamatrix.NewWithData(rows, "ID", "Name", "Age")
if err != nil {
log.Fatal(err)
}
2. Adding and Querying Rows
_ = matrix.AddRow("3", "Charlie", "35")
query := bdatamatrix.FindRowsQuery{
Column: "Name",
Operator: bdatamatrix.OperatorEquals,
CaseInsensitive: true,
Values: []string{"Alice"},
}
result, err := matrix.FindRows(query)
if err != nil {
log.Fatal(err)
}
fmt.Println("Matched rows:", result)
3. Exporting Data
Export as CSV:
csvOutput := matrix.ToCSV(true)
_ = csvOutput.Write("output.csv", 0644)
Export as JSON:
jsonOutput := matrix.ToJSON(true, false)
_ = jsonOutput.Write("output.json", 0644)
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Index ¶
Constants ¶
View Source
const ( FindRowsQueryStatus_Entries = "entries" FindRowsQueryStatus_MeetCondition = "meet_condition" )
Variables ¶
View Source
var ( // ErrEmptyHeader is returned when no header is provided. ErrEmptyHeader = errors.New("empty header") // ErrDuplicateHeader is returned when a duplicate header is encountered. ErrDuplicateHeader = errors.New("duplicate header") // ErrRowIndexOutOfRange is returned when the specified row index is invalid. ErrRowIndexOutOfRange = errors.New("row index out of range") // ErrColumnNotFound is returned when a specified column does not exist. ErrColumnNotFound = errors.New("column not found") // ErrNoRowsFound is returned when no rows match the query criteria. ErrNoRowsFound = errors.New("no rows found matching criteria") // ErrDeleteLastColumn is returned when try to delete the last column. ErrDeleteLastColumn = errors.New("unable to delete last column") )
Functions ¶
This section is empty.
Types ¶
type BDataMatrix ¶
type BDataMatrix interface {
// AddRow appends a single row to the matrix.
//
// Parameters:
// - values: A variadic list of strings representing a row.
//
// Returns:
// - An error if the number of values does not match the header length.
AddRow(values ...string) error
// AddRows appends multiple rows to the matrix.
//
// Parameters:
// - rows: A variadic list of rows, where each row is a slice of strings.
//
// Returns:
// - An error if any row's length does not match the header length.
AddRows(rows ...[]string) error
// GetRow retrieves the row at the specified index.
//
// Parameters:
// - index: The zero-based index of the row.
//
// Returns:
// - The row as a slice of strings.
// - An error if the index is out of range.
GetRow(index int) ([]string, error)
// GetRows retrieves multiple rows specified by their indexes.
//
// Parameters:
// - indexes: A variadic list of row indexes.
//
// Returns:
// - A new BDataMatrix containing only the specified rows.
// - An error if any index is out of range.
GetRows(indexes ...int) (BDataMatrix, error)
// GetColumn retrieves a column by header name.
//
// Parameters:
// - key: The header name of the column.
//
// Returns:
// - A slice of strings containing the values of the column.
// - An error if the column does not exist.
GetColumn(key string) ([]string, error)
// GetColumns returns a new BDataMatrix containing only the specified columns.
//
// Parameters:
// - keys: A variadic list of header names.
//
// Returns:
// - A new BDataMatrix whose rows contain only the values from the specified columns.
// - An error if any of the specified columns do not exist.
GetColumns(keys ...string) (BDataMatrix, error)
// UpdateRow updates the row at the specified index with new values.
//
// Parameters:
// - index: The zero-based index of the row to update.
// - values: A variadic list of new values for the row.
//
// Returns:
// - An error if the index is out of range or if the number of values does not match the header length.
UpdateRow(index int, values ...string) error
// DeleteRow removes the row at the specified index.
//
// Parameters:
// - index: The zero-based index of the row to delete.
//
// Returns:
// - An error if the index is out of range.
DeleteRow(index int) error
// FindRows returns a new BDataMatrix containing only the rows that match the given query.
// It searches in the column specified by query.Column and compares each row's value using
// query.Operator and query.CaseInsensitive. A row is included if any of the query.Values match.
//
// Parameters:
// - query: A FindRowsQuery struct with fields:
// - Column: Column to search in.
// - Operator: Comparison operator (e.g., OperatorEquals, OperatorContains).
// - CaseInsensitive: If true, comparison ignores letter case.
// - Value: Value to compare against.
// - Values: Values to compare against. (If both Value & Values are present, it will add Value as one of the Values)
//
// Returns:
// - A new BDataMatrix with matching rows.
// - A new BDataMatrix for not found value(s).
// - An error if the specified column does not exist or no rows match.
FindRows(query FindRowsQuery) (BDataMatrix, BDataMatrix, error)
// SortBy sorts the rows based on the specified header keys.
//
// Parameters:
// - keys: A variadic list of header names to sort by.
// If no keys are provided, the matrix is sorted by all header columns in order.
//
// Returns:
// - An error if any of the specified columns do not exist.
SortBy(keys ...string) error
// Header returns the header row as a slice of strings.
//
// Returns:
// - A []string representing the header.
Header() []string
// Rows returns all rows (excluding the header) as a two-dimensional slice of strings.
//
// Returns:
// - A [][]string containing all rows.
Rows() [][]string
// Data returns the full dataset as a two-dimensional slice of strings.
//
// Parameters:
// - withHeader: If true, includes the header as the first row; otherwise, returns only the data rows.
//
// Returns:
// - A [][]string where the first element is the header if withHeader is true, followed by data rows.
// - If withHeader is false, only the data rows are returned.
//
// Example usage:
//
// // Get the full dataset with the header included.
// dataWithHeader := matrix.Data(true)
//
// // Get only the data rows, excluding the header.
// dataWithoutHeader := matrix.Data(false)
Data(withHeader bool) [][]string
// Clear removes all rows from the matrix while preserving the header.
//
// Example:
// matrix.Clear()
Clear()
// Preview prints the matrix as a formatted table.
//
// Parameters:
// - n: Total number of entry for previewing the current matrix.
//
// Returns:
// +----+-------+-----+
// | ID | Name | Age |
// +----+-------+-----+
// | 1 | Alice | 30 |
// | 2 | Bob | 25 |
// | 3 | alice | 28 |
// +----+-------+-----+
Preview(n int)
// ToCSV exports the matrix in CSV format.
//
// Parameters:
// - withHeader: If true, includes the header row in the output.
//
// Returns:
// - An Output interface representing the CSV data.
ToCSV(withHeader bool) Output
// ToTSV exports the matrix in TSV (tab-separated) format.
//
// Parameters:
// - withHeader: If true, includes the header row in the output.
//
// Returns:
// - An Output interface representing the TSV data.
ToTSV(withHeader bool) Output
// ToYAML exports the matrix in YAML format.
//
// Returns:
// - An Output interface representing the YAML data.
ToYAML() Output
// ToJSON exports the matrix in JSON format.
//
// Parameters:
// - compact: If false, the JSON output is pretty-printed; otherwise, it is compact.
//
// Returns:
// - An Output interface representing the JSON data.
ToJSON(compact bool) Output
// ToCustom exports the matrix using a custom separator.
//
// Parameters:
// - withHeader: If true, includes the header row in the output.
// - separator: The string to use as a separator between columns.
//
// Returns:
// - An Output interface representing the custom-formatted data.
ToCustom(withHeader bool, separator string) Output
AddColumn(key string) error
AddColumns(keys ...string) error
AddColumnWithDefaultValue(defaultValue, key string) error
AddColumnsWithDefaultValue(defaultValue string, keys ...string) error
GetRowData(index int, key string) (string, error)
UpdateRowColumn(index int, key string, value string) error
DeleteColumn(key string) error
DeleteEmptyColumns() error
LenColumns() int
LenRows() int
DataMap() []map[string]string
Copy() BDataMatrix
Peek()
}
BDataMatrix defines the behavior for a data matrix.
func New ¶
func New(keys ...string) (BDataMatrix, error)
New create a new BDataMatrix with the provided headers.
Example usage:
// Create a new matrix with headers "ID", "Name", "Age".
matrix, err := New("ID", "Name", "Age")
if err != nil {
// handle error
}
// Add rows.
_ = matrix.AddRow("1", "Alice", "30")
_ = matrix.AddRow("2", "Bob", "25")
// Find rows where "Name" equals "Alice" (case-insensitive).
query := FindRowsQuery{
Column: "Name",
Operator: OperatorEquals,
CaseInsensitive: true,
Values: []string{"Alice"},
}
result, err := matrix.FindRows(query)
if err != nil {
// handle error
}
// Preview the matrix.
matrix.Preview()
// Export as CSV (with header) and write to file.
csvOut := matrix.ToCSV(true)
_ = csvOut.Write("output.csv", 0644)
func NewWithData ¶
func NewWithData(rows [][]string, keys ...string) (BDataMatrix, error)
NewWithData creates a new BDataMatrix with the provided headers and initial data.
Example usage:
// Define initial data rows.
rows := [][]string{
{"1", "Alice", "30"},
{"2", "Bob", "25"},
}
// Create a new matrix with headers and data.
matrix, err := NewWithData(rows, "ID", "Name", "Age")
if err != nil {
// handle error
}
// Preview the matrix.
matrix.Preview()
// Export as JSON (compact format).
jsonOut := matrix.ToJSON(true, true)
_ = jsonOut.Write("output.json", 0644)
type FindRowsQuery ¶
type FindRowsQuery struct {
// Column is the header name of the column to search.
Column string
// Operator is the comparison operator to apply.
Operator Operator
// CaseInsensitive indicates whether the comparison should ignore letter case.
CaseInsensitive bool
// Value is a value to compare against.
Value string
// Values is a slice of values to compare against.
Values []string
}
FindRowsQuery specifies the criteria for searching rows.
If both FindRowsQuery.Value and FindRowsQuery.Values present, FindRowsQuery.Value will be added to be one of FindRowsQuery.Values entry.
type Output ¶
type Output interface {
// Write writes the output data to a file with the given name and file mode.
//
// Parameters:
// - name: The filename to write to.
// - mode: The file mode (permissions) to use when writing.
//
// Returns:
// - An error if writing fails.
Write(name string, mode os.FileMode) error
// Bytes returns the output data as a byte slice.
//
// Returns:
// - A []byte containing the output data.
Bytes() []byte
// String returns the output data as a string.
//
// Returns:
// - A string representation of the output data.
String() string
}
Output defines methods for exporting matrix data.
Example usage:
// Get CSV output and write to file.
csvOut := matrix.ToCSV(true)
err := csvOut.Write("output.csv", 0644)
if err != nil {
// handle error
}
// Retrieve JSON output as a string.
jsonOut := matrix.ToJSON(true, false)
fmt.Println(jsonOut.String())
Source Files
Click to show internal directories.
Click to hide internal directories.