BitDT 🗜️⏰

A highly efficient, compact date-time encoding library for Java that provides 60-80% space savings through advanced bit packing and character encoding techniques. Perfect for applications requiring high-density timestamp storage or transmission.

🌟 Key Features

• 🗜️ Ultra-Compact Storage - 60-80% smaller than traditional date-time representations
• 📅 Massive Date Range - Support for dates from 50,000 BCE to 176,980 CE
• 🌍 Timezone Aware - Full timezone support with 15-minute granularity
• ⚡ High Performance - Optimized for bulk operations and sorting
• 🛡️ Immutable & Thread-Safe - Predictable behavior in concurrent environments
• 🔧 Multiple Date Types - Full, date-only, time-only, and empty variants
• 🎯 Millisecond Precision - Complete temporal accuracy
• 📦 Zero Dependencies - Pure Java implementation

📚 Documentation

• README - Main documentation (you are here)
• Changelog - Version history and releases
• Contributing - How to contribute to this project
• License - MIT License details

📊 Performance Comparison

Use Case	Traditional Size	BitDateTime Size	Reduction
Full date-time	~20-30 bytes	~6-10 bytes	~70%
Date-only	~10-15 bytes	~2-4 bytes	~80%
Time-only	~8-12 bytes	~3-5 bytes	~60%
Bulk storage (1000 items)	~20-30 KB	~6-10 KB	~70%

🚀 Quick Start

Installation

Since BitDT is currently available as source code, you have several options:

Option 1: Download Source Files

Download the Java files and add them to your project’s source directory:

src/
└──main/
└── java/
└── danexcodr/
└── time/
├── BitDT.java    # Main date-time class
├── BitDTArray.java     # Bulk operations
├── ThousandCounter.java # Millisecond encoding
├── BitDTExample.java   # Usage examples
└── BitDTTest.java      # Test suite

Option 2: Clone and Copy

git clone https://github.com/Danexcodr/BitDT.git
cd BitDT
# Copy src/danexcodr/time/ directory to your project

Option 3: Manual Download

1. Download individual .java files from the src/danexcodr/time/ directory
2. Place them in your project maintaining the package structure
3. Compile with your Java compiler

🔜 Package Manager Support (Coming Soon)

Maven Central and Gradle plugin support planned for future release

<!-- Future Maven Support -->
<dependency>
<groupId>com.danexcodr</groupId>
<artifactId>bitdatetime</artifactId>
<version>1.0.0</version>
</dependency>

// Future Gradle Support
implementation 'com.danexcodr:bitdatetime:1.0.0'

Basic Usage

import danexcodr.time.BitDT;
import danexcodr.time.BitDTArray;
import java.util.*;

// Create a compact date-time
BitDT dateTime = BitDT.fromPrimitives(2024, 5, 15, 14, 30, 45, 123, "+08:00");
String encoded = dateTime.encode(); // Returns compact string like "ABC123Xyz+08"

System.out.println("Encoded: " + encoded); // ~6-10 characters instead of 20+

// Decode back to full date-time
BitDT decoded = BitDT.decode(encoded);

// Verify round-trip
System.out.println("Round-trip successful: " + dateTime.equals(decoded));

Efficient Bulk Operations

// Create array of dates for efficient processing
List<BitDT> dates = Arrays.asList(
BitDT.fromPrimitives(2024, 5, 15, 14, 30, 0, 0, null),
BitDT.fromPrimitives(2024, 3, 10, 9, 0, 0, 0, null),
BitDT.fromPrimitives(2024, 1, 1, 0, 0, 0, 0, "+05:30")
);

BitDTArray dateArray = BitDTArray.fromList(dates);

// Sort efficiently
BitDTArray sortedArray = dateArray.sorted();

// Filter by date type
BitDTArray dateOnly = dateArray.getDateOnly();

// Slice and concatenate
BitDTArray slice = dateArray.slice(0, 2);
BitDTArray combined = slice.concat(dateOnly);

📖 Comprehensive Examples

Different Date Types

// Full date-time with timezone
BitDT full = BitDT.fromPrimitives(2024, 5, 15, 14, 30, 45, 123, "+08:00");
System.out.println("Full: " + full.encode());

// Date-only (no time component)
BitDT dateOnly = BitDT.fromPrimitives(2024, 5, 15, 0, 0, 0, 0, null);
System.out.println("Date only: " + dateOnly.encode());

// Time-only (no date component)
BitDT timeOnly = BitDT.fromPrimitives(0, 0, 0, 14, 30, 45, 123, null);
System.out.println("Time only: " + timeOnly.encode());

// Empty timestamp
BitDT empty = BitDT.createEmpty();
System.out.println("Empty: " + empty.encode());

Timezone Handling

// Different timezone formats
BitDT utc = BitDT.fromPrimitives(2024, 5, 15, 14, 30, 0, 0, "+00");
BitDT est = BitDT.fromPrimitives(2024, 5, 15, 14, 30, 0, 0, "-05");
BitDT ist = BitDT.fromPrimitives(2024, 5, 15, 14, 30, 0, 0, "+05:30");

System.out.println("UTC: " + utc.encode() + " -> " + utc.getTimezone());
System.out.println("EST: " + est.encode() + " -> " + est.getTimezone());
System.out.println("IST: " + ist.encode() + " -> " + ist.getTimezone());

Sorting and Comparison

List<BitDT> events = new ArrayList<>();
events.add(BitDT.fromPrimitives(2024, 5, 15, 14, 30, 0, 0, null));
events.add(BitDT.fromPrimitives(2024, 3, 10, 9, 0, 0, 0, null));
events.add(BitDT.fromPrimitives(2024, 1, 1, 0, 0, 0, 0, null));

// Sort by numerical value
List<BitDT> sorted = BitDT.sortByNumericalValue(events);

// Compare dates
BitDT first = sorted.get(0);
BitDT last = sorted.get(sorted.size() - 1);
System.out.println("First before last: " + first.before(last));

🏗️ Architecture

Bit Packing Strategy

BitDT (BitDateTime) uses sophisticated bit packing to store all date-time components in a single 64-bit long:

[4 bits: Type][20 bits: Year][4 bits: Month][5 bits: Day]
[5 bits: Hour][6 bits: Minute][6 bits: Second][10 bits: Millis][4 bits: Reserved]

Character Encoding

The library employs multiple optimized character sets:

· Years: Base-61 encoding (3 characters for 0-226,980 range) · Months: 12-character set (A-L) · Days: 31-character set (A-Z,1-5) · Time components: Optimized character ranges avoiding ambiguous characters · Zero compression: Special characters for repeated zeros

🔧 Advanced Usage

Custom Date Ranges

// Convert between relative and absolute years
int absoluteYear = 2024;
int relativeYear = BitDT.fromAbsoluteYear(absoluteYear);

BitDT date = BitDT.fromPrimitives(relativeYear, 5, 15, 14, 30, 0, 0, null);
int recoveredYear = BitDT.toAbsoluteYear(date.getYear());

Efficient Storage for Databases

// Store as numerical values for maximum efficiency
long[] numericalValues = BitDT.toNumericalArray(dates);

// Restore from numerical values
List<BitDT> restoredDates = BitDT.fromNumericalArray(numericalValues);

Error Handling

try {
BitDT date = BitDT.fromPrimitives(300000, 0, 1, 0, 0, 0, 0, null);
} catch (IllegalArgumentException e) {
System.out.println("Invalid year: " + e.getMessage());
}

// Invalid encodings return empty instances
BitDT invalid = BitDT.decode("INVALID_STRING");
System.out.println("Is empty: " + invalid.isEmpty());

🎯 Use Cases

Ideal For:

· Database timestamp storage - Reduce storage requirements by 60-80%

· High-frequency logging - Compact timestamps for log files

· Network protocols - Efficient date-time transmission

· Embedded systems - Low memory footprint applications

· Time-series databases - High-density temporal data storage

· Mobile applications - Reduce data transmission costs

· Caching systems - Efficient timestamp metadata

Performance-Sensitive Applications:

· Financial trading systems

· IoT device data collection

· Real-time analytics platforms

· High-volume transaction processing

· Distributed systems with frequent clock synchronization

📊 Benchmarks

Memory Efficiency

Traditional Java Date: ~24 bytes
BitDateTime encoded: ~8 bytes (66% reduction)
BitDateTime packed: 8 bytes + 1 byte timezone (62% reduction)

Encoding/Decoding Speed

Encoding: ~0.5-2 microseconds per operation
Decoding: ~1-3 microseconds per operation
Bulk operations: 3-5x faster than individual objects

🔍 API Reference

Core Classes

BitDT

Main date-time class with methods for:

· fromPrimitives() - Create from components · encode()/decode() - Compact string representation

· getNumericalValue() - Raw numerical form

· Comparison methods (before(), after(), compareTo())

BitDTArray

Efficient bulk operations:

· fromList()/toList() - Conversion

· sorted() - Efficient sorting

· filterByType() - Date type filtering

· slice()/concat() - Array operations

ThousandCounter

Millisecond encoding:

· encodeMilliseconds() - 0-999 to 2 characters

· decodeMilliseconds() - Reverse encoding

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository 1.

Create a feature branch (git checkout -b feature/amazing-feature) 1.

Commit your changes (git commit -m ‘Add amazing feature’) 1.

Push to the branch (git push origin feature/amazing-feature) 1.

Open a Pull Request

🐛 Reporting Issues

Found a bug? Please create an issue with:

· Detailed description

· Reproduction steps

· Expected vs actual behavior

· Environment details

📝 License

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

🙏 Acknowledgments

· Inspired by the need for efficient temporal data storage in high-performance systems

· Thanks to the Java community for best practices and patterns

· Special thanks to contributors and testers

---

Ready to optimize your date-time storage? Give BitDT a ⭐ and start saving space today!