How do I add custom holidays using the Ruby holidays gem?

Use Holidays.load_custom to load YAML files that match the gem's definition syntax. This allows defining holidays like company events, which can then be queried immediately, as shown in the custom definitions section.

Ruby holidays gem vs handling holidays manually in code?

The gem saves time by providing pre-built, tested holiday logic for multiple regions, reducing maintenance. Manual handling might be simpler for single-region apps but lacks the gem's flexibility for updates and custom definitions.

Does the Ruby holidays gem support time zones?

No, the README clearly states that time zones are ignored, and all dates are assumed to be in the same zone. For applications with time zone-sensitive data, you'll need to handle conversions externally.

How to cache holidays for better performance in Ruby?

Call Holidays.cache_before with a date range and regions to pre-calculate and store holidays in memory. This speeds up future lookups, but note it's only in-memory and not suitable for distributed setups.

What are informal holidays in the Ruby holidays gem?

Informal holidays are non-statutory celebrations like Valentine's Day, included using the :informal flag in queries. By default, they're excluded, but adding the flag returns them, as demonstrated with US examples.

How to extend the Date class with the holidays gem?

Require 'holidays/core_extensions/date' and include Holidays::CoreExtensions::Date in the Date class. This adds methods like holidays and holiday? for easier holiday checks, as shown in the core extensions section.

List of region codes for Ruby holidays gem?

Call Holidays.available_regions to get all supported region symbols, such as [:ar, :at, ..., :sg]. This helps identify valid codes for queries, as mentioned in the usage examples.

holidays — Ruby Holiday Date Handler

What is holidays?

Holidays is a Ruby gem that provides functionality to deal with statutory and custom holidays. It extends Ruby's built-in Date and Time classes, allowing developers to check for holidays on specific dates, within ranges, and across multiple regions. The gem solves the problem of managing holiday logic in applications that require date-aware scheduling, calendar features, or region-specific business rules.

Target Audience

Ruby developers building applications that need to handle holidays, such as scheduling tools, payroll systems, calendar apps, or international services requiring region-specific date logic. It's particularly useful for teams working with multiple countries or custom holiday sets.

Value Proposition

Developers choose this gem for its comprehensive region support, flexibility with custom holiday definitions, and seamless integration with Ruby's core date classes. It stands out by offering both formal and informal holiday handling, observed date logic, and performance optimizations like caching, all maintained as a reliable open-source project.

A collection of Ruby methods to deal with statutory and other holidays. You deserve a holiday!

Use Cases

Best For

Adding holiday-aware logic to scheduling or calendar applications
Building payroll systems that need to account for statutory holidays
Creating international services with region-specific date handling
Developing custom holiday calendars for companies or organizations
Integrating holiday checks into existing Ruby date/time workflows
Optimizing performance in applications that frequently query holiday data

Not Ideal For

Applications needing real-time holiday data from external APIs or dynamic sources
Projects built in languages other than Ruby, such as Python or JavaScript
Systems requiring distributed or persistent caching beyond in-memory storage
Teams looking for out-of-the-box calendar UI components or visualizations

Pros & Cons

Pros

Comprehensive Region Support

Supports holidays for multiple countries and sub-regions, allowing queries like Holidays.on(Date.new(2008, 1, 1), :us, :fr) to check across regions simultaneously, as shown in the README examples.

Flexible Holiday Handling

Includes options for informal and observed holidays with flags like :informal and :observed, enabling precise control over holiday inclusion, such as fetching Valentine's Day or shifted Canada Day.

Custom Definition Loading

Allows loading custom holiday definition files on the fly via Holidays.load_custom, letting teams define company-specific or regional holidays without modifying core gem files.

Seamless Ruby Integration

Extends Ruby's Date and Time classes with holiday methods, making checks intuitive with examples like d.holidays(:is) or d.holiday?(:ca) for Iceland or Canada.

Performance Caching

Offers in-memory caching with Holidays.cache_between to pre-calculate holidays for date ranges, improving lookup speed in high-frequency applications as detailed in the caching section.

Cons

Time Zone Ignorance

The library explicitly states it ignores time zones and assumes all dates are in the same zone, which can lead to inaccuracies in global or distributed applications.

Static Definition Reliance

Holiday definitions are based on static files, and the README notes that definition changes are considered 'minor' bumps, meaning holiday results can change without code modifications, potentially breaking assumptions.

In-Memory Caching Limitation

Caching is only in-memory, making it unsuitable for distributed systems or applications that restart frequently, as highlighted in the caching section without options for persistent storage.

Invasive Setup for Extensions

To use core extensions, developers must modify Ruby's Date and Time classes by including modules, which could conflict with other libraries or be undesirable in certain codebases.

Frequently Asked Questions

What is holidays?

Target Audience

Value Proposition

Use Cases

Best For

Adding holiday-aware logic to scheduling or calendar applications
Building payroll systems that need to account for statutory holidays
Creating international services with region-specific date handling
Developing custom holiday calendars for companies or organizations
Integrating holiday checks into existing Ruby date/time workflows
Optimizing performance in applications that frequently query holiday data

Not Ideal For

Applications needing real-time holiday data from external APIs or dynamic sources
Projects built in languages other than Ruby, such as Python or JavaScript
Systems requiring distributed or persistent caching beyond in-memory storage
Teams looking for out-of-the-box calendar UI components or visualizations

Pros & Cons

Pros

Comprehensive Region Support

Supports holidays for multiple countries and sub-regions, allowing queries like Holidays.on(Date.new(2008, 1, 1), :us, :fr) to check across regions simultaneously, as shown in the README examples.

Flexible Holiday Handling

Includes options for informal and observed holidays with flags like :informal and :observed, enabling precise control over holiday inclusion, such as fetching Valentine's Day or shifted Canada Day.

Custom Definition Loading

Allows loading custom holiday definition files on the fly via Holidays.load_custom, letting teams define company-specific or regional holidays without modifying core gem files.

Seamless Ruby Integration

Extends Ruby's Date and Time classes with holiday methods, making checks intuitive with examples like d.holidays(:is) or d.holiday?(:ca) for Iceland or Canada.

Performance Caching

Offers in-memory caching with Holidays.cache_between to pre-calculate holidays for date ranges, improving lookup speed in high-frequency applications as detailed in the caching section.

Cons

Time Zone Ignorance

The library explicitly states it ignores time zones and assumes all dates are in the same zone, which can lead to inaccuracies in global or distributed applications.

Static Definition Reliance

In-Memory Caching Limitation

Caching is only in-memory, making it unsuitable for distributed systems or applications that restart frequently, as highlighted in the caching section without options for persistent storage.

Invasive Setup for Extensions

To use core extensions, developers must modify Ruby's Date and Time classes by including modules, which could conflict with other libraries or be undesirable in certain codebases.

Frequently Asked Questions

holidays

What is holidays?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

holidays

What is holidays?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?