CalendarVersioning

A robust Calendar Versioning implementation for .NET with full support for parsing, comparison, and format customization.

📦 Installation

Install via NuGet Package Manager:

dotnet add package tetri.net.CalendarVersioning

Or add directly to your .csproj:

<PackageReference Include="tetri.net.CalendarVersioning" Version="0.0.4" />

🚀 Quick Start

Creating versions

// From string
var version = CalendarVersion.Parse("2025.04.29");

// With custom format (YY.MM.Minor)
var format = new CalendarVersionFormat("YY.MM.Minor");
var custom = CalendarVersion.Parse("25.04.1", format);

// Using constructor
var version = new CalendarVersion(year: 2025, month: 4, day: 29, minor: 1);

Comparing versions

var v1 = CalendarVersion.Parse("2025.04");
var v2 = CalendarVersion.Parse("2025.05");

if (v1 < v2) 
{
    Console.WriteLine($"{v1} is earlier than {v2}");
}

Safe parsing (TryParse)

if (CalendarVersion.TryParse("2025.04.29", out var version))
{
    Console.WriteLine($"Parsed: {version}");
}

// With custom format
var format = new CalendarVersionFormat("YY.MM.DD");
if (CalendarVersion.TryParse("25.04.29", format, out var custom))
{
    Console.WriteLine($"Parsed: {custom}");
}

Supported operations

// Equality
bool equal = v1 == v2; 

// Comparison
bool greater = v1 > v2;

// Comparison methods
int result = v1.CompareTo(v2);

✨ Features

✅ Strict Calendar Version parsing with format validation
✅ Safe parsing via TryParse (no exceptions on invalid input)
✅ DoS protection: max 256 characters, limited number of components
✅ Full version comparison support
✅ Custom formats (YYYY.MM, YY.MM.DD.Minor, etc)
✅ Overloaded operators (==, !=, <, >, <=, >=)
✅ Immutable and thread-safe
✅ System.Text.Json serialization ready (via CalendarVersionConverter)
✅ Implements IParsable<CalendarVersion> (.NET 7+)

📚 Advanced Examples

Custom format parsing

var format = new CalendarVersionFormat("YYYY.MM.Minor");
var version = CalendarVersion.Parse("2025.04.2", format);

Console.WriteLine(version.Year);  // 2025
Console.WriteLine(version.Month); // 4
Console.WriteLine(version.Minor); // 2

Comparing detailed versions

var stable = CalendarVersion.Parse("2025.04.15");
var hotfix = CalendarVersion.Parse("2025.04.15.1");

Console.WriteLine(hotfix > stable); // True

JSON serialization

// Serialization works out of the box via the built-in JsonConverter
var version = CalendarVersion.Parse("2025.04.29");
string json = JsonSerializer.Serialize(version);
// "2025.04.29"

// Deserialization
var deserialized = JsonSerializer.Deserialize<CalendarVersion>("\"2025.04.29\"");

Security limits

CalendarVersion.Parse enforces a maximum input length of 256 characters and limits the number of dot-separated components to prevent denial-of-service attacks via excessive memory allocation.

// Throws ArgumentException: input exceeds 256 characters
CalendarVersion.Parse(new string('a', 257));

// Throws FormatException: too many components
CalendarVersion.Parse("2025.04.01.1.extra.dots");

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

---

Crafted with 🧠 by Tetri Mesquita