CSV Library

🚀 Features

📋 Table of Contents

🔧 Installation

Prerequisites

Build from Source

git clone https://github.com/csvtoolkit/FastCSV-C.git
cd FastCSV-C
# Build shared and static libraries
make
# Run tests to verify installation
make test
# Optional: Run memory safety checks
make valgrind
# Performance benchmarks
make benchmark

Build Targets

🚀 Quick Start

Reading CSV Files

#include "csv_reader.h"
#include "arena.h"
int main() {
 // Initialize arena allocator
 Arena arena;
 arena_create(&arena, 4096);
 
 // Create configuration with encoding support
 CSVConfig *config = csv_config_create(&arena);
 csv_config_set_path(config, "data.csv");
 csv_config_set_has_header(config, true);
 csv_config_set_encoding(config, CSV_ENCODING_UTF8);
 
 // Initialize reader
 CSVReader *reader = csv_reader_init_with_config(&arena, config);
 
 // Get headers
 int header_count;
 char **headers = csv_reader_get_headers(reader, &header_count);
 printf("Headers: ");
 for (int i = 0; i < header_count; i++) {
 printf("%s ", headers[i]);
 }
 printf("\n");
 
 // Read records with navigation support
 while (csv_reader_has_next(reader)) {
 CSVRecord *record = csv_reader_next_record(reader);
 if (record) {
 printf("Record at position %ld:\n", csv_reader_get_position(reader));
 for (int i = 0; i < record->field_count; i++) {
 printf(" %s: %s\n", headers[i], record->fields[i]);
 }
 }
 }
 
 // Cleanup
 csv_reader_free(reader);
 arena_destroy(&arena);
 return 0;
}

Writing CSV Files with Encoding

#include "csv_writer.h"
#include "arena.h"
int main() {
 Arena arena;
 arena_create(&arena, 4096);
 
 // Configure with UTF-8 and BOM
 CSVConfig *config = csv_config_create(&arena);
 csv_config_set_path(config, "output.csv");
 csv_config_set_encoding(config, CSV_ENCODING_UTF8);
 csv_config_set_write_bom(config, true);
 csv_config_set_strict_mode(config, true);
 
 // Initialize writer
 CSVWriter *writer;
 char *headers[] = {"Name", "Age", "City"};
 csv_writer_init(&writer, config, headers, 3, &arena);
 
 // Write data with automatic quoting
 char *row1[] = {"John Doe", "30", "New York"};
 csv_writer_write_record(writer, row1, 3);
 
 char *row2[] = {"Jane Smith", "25", "Los Angeles"};
 csv_writer_write_record(writer, row2, 3);
 
 csv_writer_free(writer);
 arena_destroy(&arena);
 return 0;
}

📖 API Reference

Core Components

Arena Management

// Initialize arena with specified size
Arena arena;
ArenaResult result = arena_create(&arena, size_t size);
// Allocate memory from arena
void* ptr;
ArenaResult result = arena_alloc(&arena, size_t size, &ptr);
// Duplicate string in arena
ArenaResult result = arena_strdup(&arena, const char* str, char** result);
// Reset arena for reuse
arena_reset(&arena);
// Clean up arena
arena_destroy(&arena);

Enhanced CSV Reading

// Initialize reader with configuration
CSVReader *reader = csv_reader_init_with_config(&arena, config);
// Navigation and positioning
int has_more = csv_reader_has_next(reader);
long position = csv_reader_get_position(reader);
int seek_result = csv_reader_seek(reader, long position);
csv_reader_rewind(reader);
// Header management
int header_count;
char **headers = csv_reader_get_headers(reader, &header_count);
// Configuration updates
csv_reader_set_config(reader, &arena, new_config);
// Read records
CSVRecord *record = csv_reader_next_record(reader);

Advanced CSV Writing

// Initialize with encoding and BOM support
CSVWriter *writer;
CSVWriterResult result = csv_writer_init(&writer, config, headers, count, &arena);
// Write records with automatic formatting
csv_writer_write_record(writer, fields, field_count);
// Write with field mapping
csv_writer_write_record_map(writer, field_names, field_values, count);
// Utility functions
bool needs_quoting = field_needs_quoting(field, delimiter, enclosure, strict_mode);
bool is_numeric = is_numeric_field(field);

⚙️ Configuration

Basic Configuration

CSVConfig *config = csv_config_create(&arena);
// Customize delimiters and quotes
csv_config_set_delimiter(config, ';'); // Default: ','
csv_config_set_enclosure(config, '\''); // Default: '"'
csv_config_set_escape(config, '\\'); // Default: '"'
// Configure parsing behavior
csv_config_set_trim_fields(config, true); // Default: false
csv_config_set_skip_empty_lines(config, true); // Default: false
csv_config_set_strict_mode(config, true); // Default: false
csv_config_set_preserve_quotes(config, false); // Default: false

Advanced Configuration

// Encoding and BOM support
csv_config_set_encoding(config, CSV_ENCODING_UTF8);
csv_config_set_write_bom(config, true);
// File handling
csv_config_set_path(config, "data.csv");
csv_config_set_has_header(config, true);
csv_config_set_offset(config, 100); // Skip first 100 lines
csv_config_set_limit(config, 1000); // Process only 1000 records

🌐 Encoding Support

Supported Encodings

BOM (Byte Order Mark) Writing

// Enable BOM for UTF encodings
csv_config_set_encoding(config, CSV_ENCODING_UTF8);
csv_config_set_write_bom(config, true);
// BOM bytes are automatically written:
// UTF-8: EF BB BF
// UTF-16LE: FF FE
// UTF-16BE: FE FF
// UTF-32LE: FF FE 00 00
// UTF-32BE: 00 00 FE FF

🔧 Advanced Features

Multi-line Field Support

// Automatic handling of quoted multi-line fields
char *content = "name,description\n"
 "\"Product A\",\"A great product\nwith multiple lines\"\n"
 "\"Product B\",\"Another product\"";
// Parser automatically handles multi-line quoted fields
CSVParseResult result = csv_parse_line_inplace(content, &arena, config, 1);

RFC 4180 Quote Escaping

// Proper quote escaping: "" becomes "
char *input = "\"Say \"\"Hello\"\" World\",normal";
// Results in: Say "Hello" World, normal
// Enhanced quote handling in parser
CSVParseResult result = csv_parse_line_inplace(input, &arena, config, 1);

Strict Mode Processing

// Enable strict mode for enhanced validation
csv_config_set_strict_mode(config, true);
// Strict mode features:
// - Fields with spaces are automatically quoted
// - Enhanced validation of field content
// - Stricter RFC 4180 compliance

🧪 Testing

Running Tests

# Run all tests
make test
# Run specific test suite
make test-arena
make test-config
make test-utils
make test-parser
make test-writer
make test-reader
# Memory leak detection
make valgrind
make valgrind-all
# Performance testing
make benchmark
make stress-test

Test Results Summary

✅ Arena Tests: 13/13 passed
✅ Config Tests: 7/7 passed 
✅ Utils Tests: 11/11 passed
✅ Parser Tests: 7/7 passed
✅ Writer Tests: 15/15 passed
✅ Reader Tests: 8/8 passed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Total: 60+ tests passed

⚡ Performance

Benchmarks

Performance Features

Stress Test Results

# 50,000 iteration stress test
✅ All iterations completed successfully
✅ Zero memory leaks detected
✅ Consistent performance maintained

🛡️ Memory Safety

✅ Zero memory leaks
✅ Zero memory errors 
✅ Proper allocation/deallocation balance
✅ No buffer overflows or underflows
✅ No uninitialized memory access

🔧 Error Handling

// Arena errors
typedef enum {
 ARENA_OK = 0,
 ARENA_ERROR_NULL_POINTER,
 ARENA_ERROR_INVALID_SIZE,
 ARENA_ERROR_OUT_OF_MEMORY,
 ARENA_ERROR_ALIGNMENT
} ArenaResult;
// Writer errors
typedef enum {
 CSV_WRITER_OK = 0,
 CSV_WRITER_ERROR_NULL_POINTER,
 CSV_WRITER_ERROR_MEMORY_ALLOCATION,
 CSV_WRITER_ERROR_FILE_OPEN,
 CSV_WRITER_ERROR_FILE_WRITE,
 CSV_WRITER_ERROR_INVALID_FIELD_COUNT,
 CSV_WRITER_ERROR_FIELD_NOT_FOUND,
 CSV_WRITER_ERROR_BUFFER_OVERFLOW,
 CSV_WRITER_ERROR_ENCODING
} CSVWriterResult;
// Parser errors with detailed information
typedef struct {
 bool success;
 const char *error;
 int error_line;
 int error_column;
 FieldArray fields;
} CSVParseResult;

📚 Examples

Custom Delimiter Processing

CSVConfig *config = csv_config_create(&arena);
csv_config_set_delimiter(config, ';'); // Use semicolon
csv_config_set_enclosure(config, '\''); // Use single quotes
csv_config_set_strict_mode(config, true); // Enable strict validation

Large File Processing with Navigation

// Efficient streaming for large files
CSVReader *reader = csv_reader_init_with_config(&arena, config);
// Skip to specific position
csv_reader_seek(reader, 1000);
// Process with position tracking
while (csv_reader_has_next(reader)) {
 long position = csv_reader_get_position(reader);
 CSVRecord *record = csv_reader_next_record(reader);
 
 printf("Processing record at position %ld\n", position);
 process_record(record);
 
 // Arena automatically manages memory
}

Multi-Encoding File Processing

// Process files with different encodings, including ASCII and Latin1
CSVEncoding encodings[] = {
 CSV_ENCODING_UTF8,
 CSV_ENCODING_UTF16LE,
 CSV_ENCODING_LATIN1, // Now fully supported
 CSV_ENCODING_ASCII // Now fully supported
};
for (int i = 0; i < 4; i++) {
 csv_config_set_encoding(config, encodings[i]);
 csv_config_set_write_bom(config, true); // No BOM for ASCII/Latin1
 process_csv_file(config);
}

Integration with Other Languages

🤝 Contributing

Development Setup

git clone https://github.com/csvtoolkit/FastCSV-C.git
cd FastCSV-C
make test
make valgrind

Code Style

📄 License

📦 Releases

Latest Release Features

🙏 Acknowledgments