Hebrew.EBCDIC2Unicode.Converter 2.0.0-alpha

Hebrew.EBCDIC2Unicode.Converter

A production-ready .NET library for converting between EBCDIC (Extended Binary Coded Decimal Interchange Code) and UTF-8 encodings, with specialized support for Hebrew text processing.

🚀 Features

• 🔄 Unified API: Single public method with clean interface
• 🌍 Multi-Codepage Support: Hebrew Custom, IBM500, IBM037, IBM424
• 📈 Production Ready: Comprehensive error handling and validation
• ⚡ High Performance: Optimized for large-scale text processing
• 🔧 .NET 8: Built on the latest LTS framework
• 📚 Well Documented: Complete XML documentation included

📦 Installation

Package Manager Console

Install-Package Hebrew.EBCDIC2Unicode.Converter -Version 2.0.0-alpha

.NET CLI

dotnet add package Hebrew.EBCDIC2Unicode.Converter --version 2.0.0-alpha

PackageReference

<PackageReference Include="Hebrew.EBCDIC2Unicode.Converter" Version="2.0.0-alpha" />

🔧 Quick Start

using HebrewEBCDIC3Unicode.Converter;

// Create converter instance
var converter = new HebrewEbcdicConverter();

// Method 1: Convert EBCDIC byte array to UTF-8 (recommended)
byte[] ebcdicBytes = { 0x41, 0x42, 0x40, 0xC8, 0x85, 0x93, 0x93, 0x96 }; // אב Hello
string result = converter.ConvertEbcdicToUtf8(ebcdicBytes);
// Output: "אב Hello"

// Method 2: Convert EBCDIC string (containing raw bytes) to UTF-8
string ebcdicString = HebrewEbcdicConverter.CreateEbcdicStringFromBytes(ebcdicBytes);
string result2 = converter.ConvertEbcdicToUtf8(ebcdicString);
// Output: "אב Hello"

// Method 3: Convert hex string to UTF-8 (utility method)
string hexResult = converter.ConvertHexStringToUtf8("4142 40C8 8593 9396");
// Output: "אב Hello"

// Convert with specific codepage
string ibmResult = converter.ConvertEbcdicToUtf8(ebcdicBytes, EbcdicCodepage.IBM500);
// Output: " â Hello"

📖 Supported Codepages

🌟 Advanced Usage

Working with Different Input Formats

// Working with byte arrays (most efficient)
byte[] ebcdicData = GetEbcdicDataFromMainframe();
string utf8Result = converter.ConvertEbcdicToUtf8(ebcdicData);

// Working with .NET strings containing raw EBCDIC bytes
string ebcdicAsString = GetEbcdicStringFromLegacySystem();
string utf8Result2 = converter.ConvertEbcdicToUtf8(ebcdicAsString);

// Working with hex strings (for testing/debugging)
string hexString = "4142 40C8 8593 9396";
string utf8Result3 = converter.ConvertHexStringToUtf8(hexString);

Error Handling

try 
{
    byte[]? nullBytes = null;
    var result = converter.ConvertEbcdicToUtf8(nullBytes!);
}
catch (ArgumentNullException ex)
{
    // Handle null input
    Console.WriteLine($"Null input: {ex.Message}");
}

try 
{
    var result = converter.ConvertHexStringToUtf8("invalid hex");
}
catch (ArgumentException ex)
{
    // Handle invalid hex string
    Console.WriteLine($"Invalid hex: {ex.Message}");
}

Batch Processing

var ebcdicDataList = new List<byte[]> { /* your EBCDIC byte arrays */ };
var results = ebcdicDataList
    .Select(bytes => converter.ConvertEbcdicToUtf8(bytes))
    .ToList();

Round-trip Conversion

string originalText = "אב Hello 123";
byte[] ebcdicBytes = converter.ConvertFromUtf8(originalText);
string convertedBack = converter.ConvertEbcdicToUtf8(ebcdicBytes);
bool isIdentical = originalText == convertedBack; // Should be true

IBM-424 Handling

// IBM-424 has .NET limitations - graceful handling
var result = converter.ConvertEbcdicToUtf8(ebcdicBytes, EbcdicCodepage.IBM424);
// Returns: "[Codepage 424 not supported by Microsoft .NET - consider using HebrewCustom mapping]"

🔍 Character Mapping Details

Hebrew Characters (HebrewCustom)

• Hebrew Letters (א-ת): Optimized mapping for modern Hebrew text
• Final Forms: Support for final letter forms (ך, ם, ן, ף, ץ)
• Special Characters: Hebrew-specific punctuation and symbols

English & Numbers

• English Letters: Standard EBCDIC uppercase/lowercase mapping
• Numbers (0-9): Standard EBCDIC numeric mapping (0xF0-0xF9)
• Special Characters: Spaces, periods, apostrophes, and common symbols

🏗️ Technical Implementation

Why Not System.Text.Encoding?

This library provides custom Hebrew EBCDIC mapping because:

1. Microsoft .NET Limitations: Limited EBCDIC codepage support
2. Hebrew Optimization: Custom mapping optimized for Hebrew text
3. Legacy System Support: Compatibility with mainframe Hebrew data
4. Production Reliability: Handles edge cases and invalid input gracefully
5. Raw Byte Processing: Works directly with EBCDIC byte data, not hex representations

Performance Characteristics

• Memory Efficient: Minimal allocations during conversion
• Thread Safe: Converter instances can be used concurrently
• Validation: Input validation prevents runtime errors

🧪 Testing & Quality

This library includes comprehensive testing:

• ✅ Round-trip Testing: Ensures conversion accuracy
• ✅ Error Handling: Invalid input validation
• ✅ Performance Testing: Large-scale processing verification
• ✅ Multi-codepage Testing: All supported codepages verified

🌐 Real-World Applications

• Mainframe Data Migration: Converting legacy Hebrew EBCDIC data
• Banking Systems: Processing Hebrew transaction data from IBM systems
• Government Systems: Converting Hebrew administrative data
• Database Integration: ETL processes with Hebrew EBCDIC sources

📋 Requirements

• .NET 8.0 or later
• System.Text.Encoding.CodePages (automatically included)

🤝 Contributing

This project welcomes contributions! Areas of interest:

• Additional EBCDIC codepage support
• Performance optimizations
• Enhanced Hebrew text processing
• Documentation improvements

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• HebrewEBCDIC3Unicode: Complete solution with DB2 integration
• Unified API Example: Comprehensive usage guide

📞 Support

• Issues: GitHub Issues
• Documentation: Project README
• Examples: API Documentation

Made with ❤️ for the Hebrew text processing community