dabomase-italian-datetime-utils

Introduction

Hello everybody!

My name is Dabomase.ItalianDateTimeUtils and I'm a class library originally written by Davide Borghi. He wrote me because he was bored to copy and paste a static class in every project he was working on.

Another stubborn developer, Massimo Serra, also decided to support Davide with my code.

As a humble, simple and pluggable .NET Standard 2.0 utility library, my role is to help Italian developers or any developer who need support when dealing with Italian holidays (both national and customizable local ones) and work days calculations, which sometimes can be really boring!

Even if I have a good set of unit tests, my developers are committed to extend my features and documentation too, so be patient with me, I promise, they're working hard on these things in their spare time!

For this reason, please, feel free to file comments, open issues and, if you want, even fork my code and open pull requests: only bear in mind to check my open source license to be nice with me.

You can find me on NuGet!

And by the way, if you want to know me better, here's my changelog.

Developers' guide

Installation and prerequisites

The library uses .NET Standard 2.0 to support both .NET Framework and .NET (Core).

You should install the latest version via NuGet:

Install-Package Dabomase.ItalianDateTimeUtils

or via the .NET Core command line interface:

dotnet add package Dabomase.ItalianDateTimeUtils

A general overview

These are the main utility static classes:

• DateUtils.cs provides DateTime general purpose utility methods;
• ItalianHolidaysUtils.cs has methods to work with Italian holidays checks;
• ItalianWorkDaysUtils.cs gives you methods to deal with Italian work days calculations.

While the following classes offers custom extensions to the DateTime type:

• DateTimeExtensions.cs supports equality check, week and weekends, days of months, quarters and four-month periods;
• DateTimeHolidaysExtensions.cs adds to the DateTime simple boolean methods to check if given date is an Italian holiday or not.

A quick start

Let's say you want me to check if a given date is an Italian holiday:

bool isHoliday = ItalianHolidaysUtils.IsHoliday(new DateTime(2024, 1, 1));

or you want me to list all yearly Italian holidays or from a selected DateTime range:

var startDate = new DateTime(2024, 3, 15);
var endDate = new DateTime(2025, 12, 15);

var italianHolidaysFor2024 = ItalianHolidaysUtils.GetYearlyHolidays(2024);
var italianHolidaysInRange = ItalianHolidaysUtils.GetHolidaysInRange(startDate, endDate);

When it comes to work days calculations, I can either calculate the number of office days given two dates:

var startDate = new DateTime(2024, 7, 16);
var endDate = new DateTime(2024, 12, 15);

var italianOfficeDaysInRangeCount = 
    ItalianWorkDaysUtils.HowManyOfficeDaysBetweenDates(startDate, endDate);

or even use Func to specify what kind of work days condition you want, either built-in or your own; let me show you:

var startDate = new DateTime(2024, 7, 16);
var endDate = new DateTime(2024, 12, 15);

var italianOfficeDaysInRangeCount = 
    ItalianWorkDaysUtils.HowManyOfficeDaysBetweenDates(startDate, endDate);

var workDaysInRangeExcludingSundaysCount = 
    ItalianWorkDaysUtils.HowManyWorkDaysBetweenDates(
        startDate, endDate, 
        workDaysCondition: ItalianWorkDaysUtils.ExcludeSundaysCondition);

var evenWorkDaysInRangeCount = 
    ItalianWorkDaysUtils.HowManyWorkDaysBetweenDates(
        startDate, endDate, 
        workDaysCondition: ItalianWorkDaysUtils.IncludeOnlyEvenDaysCondition);

var allDaysAsWorkingDaysInRangeCount = 
    ItalianWorkDaysUtils.HowManyWorkDaysBetweenDates(
        startDate, endDate, 
        workDaysCondition: _ => true);

Full user documentation

You can find generated markdown files documenting the available APIs here to foresee more advanced use cases and utilities.

Keep also in mind to regularly check my GitHub repo to see if my developers either packed a new release version or added new use case samples.

Feel free to take a look at the tests project to further explore what I can do for you with real world data sets.

Maintainers' guide

In short

Maintainers can find under the docs directory the following files:

1. NuGet checklist to help them pack and release a new version of the NuGet package;
2. Docs generation checklist to guide them generate documents from code using an open source CLI tool;
3. Generated docs' parent folder.

Code of conduct

Currently used code of conduct can be found here.