🎉 MATLAB File Reader/Writer v0.3.0 Released - Production Quality Achieved!

[kolkov]

We're excited to announce the release of v0.3.0 - a major milestone bringing the library to production quality (Grade A-)!

🌟 Highlights

This release focuses on security, developer experience, and production readiness with 60 new tests, 3 critical security fixes, and modern Go API design patterns.

🎯 New Features

Functional Options Pattern

Clean, extensible API with backward compatibility:

// Before (still works!)
writer, _ := matlab.Create("output.mat", matlab.Version5)

// Now (with options!)
writer, _ := matlab.Create("output.mat", matlab.Version5,
    matlab.WithEndianness(binary.BigEndian),
    matlab.WithDescription("My awesome dataset"),
)

Available options:

• WithEndianness(binary.ByteOrder) - Control byte order for v5 files
• WithDescription(string) - Set custom file description
• WithCompression(int) - Set compression level (0-9) for v7.3 files

API Convenience Methods (70% Less Boilerplate!)

Before v0.3.0:

mat, _ := matlab.Open(file)
var myVar *types.Variable
for _, v := range mat.Variables {
    if v.Name == "data" {
        myVar = v
        break
    }
}
if myVar == nil {
    log.Fatal("variable not found")
}
data, ok := myVar.Data.([]float64)
if !ok {
    log.Fatal("wrong type")
}

With v0.3.0:

mat, _ := matlab.Open(file)
v := mat.GetVariable("data")
data, _ := v.GetFloat64Array()

New methods:

• MatFile.GetVariable(name) - Direct variable access
• MatFile.GetVariableNames() - List all variables
• MatFile.HasVariable(name) - Check existence
• Variable.GetFloat64Array() - Type-safe extraction with auto-conversion
• Variable.GetInt32Array() - Int32 extraction
• Variable.GetComplex128Array() - Complex number extraction
• Variable.GetScalar() - Single value extraction

Testable Examples

17 new godoc examples that are:

• ✅ Executable (go test verified)
• ✅ Always current (part of test suite)
• ✅ Copy-paste ready

View them at: https://pkg.go.dev/github.com/scigolib/matlab#pkg-examples

🔒 Critical Security Fixes

Security Fix #1: Tag Size Validation (High Priority)

• Problem: Malicious MAT files could trigger memory exhaustion by specifying 4GB+ tag sizes
• Solution: Added 2GB safety limit with proper validation
• Location: internal/v5/data_tag.go:53

Security Fix #2: Dimension Overflow Protection (High Priority)

• Problem: Integer overflow when calculating array sizes from dimensions
• Solution: Added math.MaxInt checks before multiplication
• Location: internal/v5/writer.go:124, internal/v73/writer.go:98

Security Fix #3: v73 Complex Reading (Functionality)

• Problem: Round-trip failures for complex numbers in v7.3 format
• Solution: Proper MATLAB_complex attribute detection
• Location: internal/v73/adapter.go:50

📊 Quality Metrics

Metric	v0.2.0	v0.3.0	Change
Grade	B+	A-	⬆️ Production Quality
Tests	238	298	+60 tests (+25%)
Coverage	78.5%	85.4%	+6.9%
Linter Issues	0	0	✅ Maintained
Platforms	3/3 GREEN	3/3 GREEN	✅ All passing

🚀 What's Supported

Reader (Complete ✅)

• ✅ All numeric types (double, single, int8-64, uint8-64)
• ✅ Complex numbers (both v5 and v7.3 formats)
• ✅ Multi-dimensional arrays
• ✅ Character arrays
• ✅ Structures
• ✅ Cell arrays
• ✅ Sparse matrices
• ✅ Compressed data

Writer (v5 + v7.3 ✅)

• ✅ All numeric types
• ✅ Complex numbers (proper MATLAB format)
• ✅ Multi-dimensional arrays
• ✅ Character arrays
• ✅ Both endianness (MI/IM for v5)
• 📅 Structures (planned v0.5.0+)
• 📅 Cell arrays (planned v0.5.0+)
• 📅 Compression (planned v0.5.0+)

📦 Installation

go get github.com/scigolib/matlab

🔄 Upgrading from v0.2.0

100% backward compatible - no breaking changes!

go get -u github.com/scigolib/matlab

Your existing code will work without modifications. New features are opt-in via functional options.

📚 Resources

• Release Notes: https://github.com/scigolib/matlab/releases/tag/v0.3.0
• Changelog: https://github.com/scigolib/matlab/blob/main/CHANGELOG.md#030---2025-11-21
• API Reference: https://pkg.go.dev/github.com/scigolib/matlab
• Examples: https://pkg.go.dev/github.com/scigolib/matlab#pkg-examples
• Quick Start: https://github.com/scigolib/matlab#quick-start

🎯 What's Next?

v0.4.0 (planned 2-3 weeks):

• Context support for cancellable operations
• OpenWithContext() and WriteVariableWithContext() APIs
• Timeout support
• Progress callbacks

v0.5.0+ (1-2 months):

• Compression support (v5 GZIP, v7.3 filters)
• Structures and cell arrays writing
• Performance optimizations
• 90%+ test coverage

See the ROADMAP for full details.

💬 Feedback

We'd love to hear from you! Please:

• ⭐ Star the repo if you find it useful
• 🐛 Report bugs in Issues
• 💡 Suggest features in Discussions
• 🧪 Test with your real MATLAB files and share compatibility reports

🙏 Acknowledgments

Special thanks to:

• The scigolib/hdf5 team for v0.13.1 stable
• All contributors and early adopters
• The MATLAB/Octave community for reference implementations

---

Ready for production! 🚀

Try it out and let us know what you think!