👁 Image
DoenaSoft.PillRefresh 1.0.5

PillRefreshLib

A .NET library for calculating medication supply duration and generating calendar reminders with automatic weekend and holiday avoidance.

Description

PillRefreshLib provides core functionality for managing medication schedules by calculating when prescriptions need to be refilled. The library automatically adjusts reminder dates to avoid weekends and regional holidays, ensuring reminders occur on business days when prescriptions can actually be filled.

Features

• Calculate remaining medication supply duration based on current pills and daily dosage
• Generate iCalendar (.ics) files compatible with Outlook, Google Calendar, and other applications
• Automatic reminder date adjustment to avoid:
  • Weekends (Saturday/Sunday)
  • Public holidays (country and region-specific)
  • Mondays (optional, to account for medical provider schedules)
• Flexible user interaction interface for easy integration
• Support for decimal pill counts and dosages
• Multi-language support via resource files

Installation

Install via NuGet Package Manager:

Install-Package DoenaSoft.PillRefresh

Or via .NET CLI:

dotnet add package DoenaSoft.PillRefresh

Target Frameworks

This library supports:

• .NET 10.0
• .NET Framework 4.7.2
• .NET Standard 2.0

Dependencies

• Ical.Net (>= 5.2.1): iCalendar file format support
• mitoSoft.Holidays (>= 2.0.6): Holiday calendar data for multiple countries and regions

Usage

Basic Example

using DoenaSoft.PillRefresh;

// Implement the IInteraction interface for your application
public class ConsoleInteraction : IInteraction
{
 public void WriteLine(string message = null)
 {
 Console.WriteLine(message);
 }

 public string ReadLine()
 {
 return Console.ReadLine();
 }
}

// Use the PillCalculator
var interaction = new ConsoleInteraction();
var calculator = new PillCalculator(interaction);

// Get user input
double pillCount = calculator.GetPillCount();
double dailyDosage = calculator.GetDosageCount();

// Calculate final day
DateTime finalDay = DateTime.Now.Date.AddDays(Math.Floor(pillCount / dailyDosage) - 1);

// Get reminder day (adjusted for holidays and weekends)
DateTime reminderDay = calculator.GetReminderDay(finalDay, "us", "California");

// Get event name
string eventName = calculator.GetEventName();

// Create calendar event
string icsFilePath = calculator.CreateEvent(finalDay, reminderDay, eventName);

// The .ics file is now ready to be imported into any calendar application

Advanced Integration

For GUI or web applications, implement the IInteraction interface to match your UI framework:

public class WpfInteraction : IInteraction
{
 private readonly TextBox outputTextBox;
 private readonly Func<string> inputProvider;

 public WpfInteraction(TextBox output, Func<string> inputFunc)
 {
 outputTextBox = output;
 inputProvider = inputFunc;
 }

 public void WriteLine(string message = null)
 {
 outputTextBox.AppendText(message + Environment.NewLine);
 }

 public string ReadLine()
 {
 return inputProvider();
 }
}

Automated Scenarios

For testing or automated workflows, create a mock interaction:

public class MockInteraction : IInteraction
{
 private readonly Queue<string> responses;
 private readonly List<string> output;

 public MockInteraction(params string[] inputResponses)
 {
 responses = new Queue<string>(inputResponses);
 output = new List<string>();
 }

 public void WriteLine(string message = null)
 {
 output.Add(message);
 }

 public string ReadLine()
 {
 return responses.Dequeue();
 }

 public IReadOnlyList<string> Output => output;
}

// Usage in tests
var mock = new MockInteraction("30", "2", "7", "Refill Medication");
var calculator = new PillCalculator(mock);
// ... perform calculations

API Reference

IInteraction Interface

public interface IInteraction
{
 void WriteLine(string message = null);
 string ReadLine();
}

Implement this interface to integrate the library with your application's UI framework.

PillCalculator Class

Constructor

public PillCalculator(IInteraction interaction)

Creates a new instance of the PillCalculator with the specified interaction interface.

Parameters:

• interaction: Implementation of IInteraction for user communication

Methods

Calculate()

public string Calculate(string countryCode, string administrativeDivision)

Performs a complete pill supply calculation workflow: prompts for pill count and dosage, calculates the final day, determines the optimal reminder day (avoiding weekends and holidays), gets the event name, and creates the calendar file.

Parameters:

• countryCode: ISO 3166-1 alpha-2 country code for holiday lookup (e.g., "us", "de", "gb", "ch", "ca"). Used to identify regional holidays
• administrativeDivision: The administrative division within the country (state, province, canton, region). Examples:
  • United States: "California", "Texas", "NewYork"
  • Germany: "Bayern" (Bavaria), "RheinlandPfalz", "Berlin"
  • Switzerland: "Zurich", "Geneva", "Bern"
  • Canada: "Ontario", "Quebec", "BritishColumbia"

Returns: The file path to the generated iCalendar (.ics) file

GetPillCount()

public double GetPillCount()

Prompts the user for the number of pills remaining.

Returns: The number of pills left (decimal value allowed)

GetDosageCount()

public double GetDosageCount()

Prompts the user for the daily dosage.

Returns: The number of pills taken per day (decimal value allowed)

CalculateFinalDay()

public DateTime CalculateFinalDay(double pills, double dosage)

Calculates the final day when the pill supply will run out based on current count and daily dosage.

Parameters:

• pills: The current number of pills available
• dosage: The number of pills taken per day

Returns: The date when the pills will run out

GetReminderDay()

public DateTime GetReminderDay(DateTime finalDay, string countryCode, string administrativeDivision)

Calculates the reminder day, automatically avoiding weekends and holidays.

Parameters:

• finalDay: The date when pills will run out
• countryCode: ISO 3166-1 alpha-2 country code for holiday lookup (e.g., "us", "de", "gb", "ch", "ca")
• administrativeDivision: The administrative division within the country (state, province, canton, region). Examples:
  • United States: "California", "Texas", "NewYork"
  • Germany: "Bayern" (Bavaria), "RheinlandPfalz", "Berlin"
  • Switzerland: "Zurich", "Geneva", "Bern"
  • Canada: "Ontario", "Quebec", "BritishColumbia"

Returns: The calculated reminder date, adjusted for weekends and regional holidays

GetEventName()

public string GetEventName()

Prompts the user for the reminder event name.

Returns: The name for the calendar event

CreateEvent()

public string CreateEvent(DateTime finalDay, DateTime reminderDay, string eventName)

Creates an iCalendar (.ics) file with an event and reminder.

Parameters:

• finalDay: The date when the pills will run out
• reminderDay: The date for the reminder alarm
• eventName: The name/summary of the calendar event

Returns: The file path to the generated .ics file (created in system temp directory)

GetDoAnotherCalculation()

public bool GetDoAnotherCalculation()

Prompts the user whether they want to perform another calculation.

Returns: true if the user wants another calculation; otherwise, false

Holiday Support

The library uses the mitoSoft.Holidays package to support holidays for numerous countries and regions.

Understanding Country Codes and Administrative Divisions

Country Codes use ISO 3166-1 alpha-2 standard. Common country codes include:

• de - Germany
• us - United States
• gb - United Kingdom
• fr - France
• ch - Switzerland
• at - Austria
• ca - Canada
• it - Italy
• es - Spain

What is an Administrative Division?

An administrative division is a geographical subdivision within a country that has its own regional holidays in addition to national holidays. Different countries use different terms for these divisions:

Administrative Division Examples by Country:

Why Administrative Divisions Matter

Different regions within the same country often observe different public holidays. For example:

• Germany: Epiphany (January 6) is a public holiday in Bavaria, Baden-Württemberg, and Saxony-Anhalt, but not in other German states
• United States: Many states have their own unique holidays (e.g., Patriots' Day in Massachusetts)
• Switzerland: Each canton determines its own public holidays, leading to significant variation
• Canada: Family Day is observed on different dates depending on the province

The library uses this information to ensure reminder dates don't fall on regional holidays when medical offices might be closed.

Usage in Code

// Example for California, United States
DateTime reminderDay = calculator.GetReminderDay(finalDay, "us", "California");

// Example for Bavaria, Germany
DateTime reminderDay = calculator.GetReminderDay(finalDay, "de", "Bayern");

// Example for Zurich, Switzerland
DateTime reminderDay = calculator.GetReminderDay(finalDay, "ch", "Zurich");

Holiday Calendar Availability

If no holiday calendar is found for the specified country or administrative division, the library will:

• Continue without holiday adjustment
• Notify via the IInteraction interface
• Still adjust for weekends (Saturday/Sunday)

This ensures the application remains functional even for regions without comprehensive holiday data.

Calendar Compatibility

Generated .ics files are compatible with:

• Microsoft Outlook
• Google Calendar
• Apple Calendar
• Mozilla Thunderbird
• Any application supporting the iCalendar (RFC 5545) standard

The events are created with:

• All-day event on the final medication day
• Reminder alarm on the calculated reminder date
• "Free" busy status for Outlook compatibility
• Unique UID for proper event tracking

Localization

The library includes built-in support for multiple languages through resource files:

• English (default)
• German (de)

Add additional languages by including culture-specific resource files in your application.

Examples

Calculate Days Until Refill

var calculator = new PillCalculator(interaction);
double pills = 60;
double dosage = 2.5;
int daysLeft = (int)Math.Floor(pills / dosage) - 1;
DateTime refillDate = DateTime.Now.Date.AddDays(daysLeft);

Create Event Without User Interaction

// Use a preset interaction or mock
var finalDay = DateTime.Now.AddDays(20);
var reminderDay = calculator.GetReminderDay(finalDay, "de", "Bayern");
string icsFile = calculator.CreateEvent(finalDay, reminderDay, "Medication Refill");

Thread Safety

The PillCalculator class is not thread-safe. Create separate instances for concurrent operations.

License

This library is licensed under the MIT License. See LICENSE file for details.

Author

Copyright (c) 2022 DJ Doena

Support

For issues, questions, or feature requests, please visit: https://github.com/DJDoena/PillRefresh

Version History

1.0.0

• Initial release
• Core calculation functionality
• iCalendar event generation
• Holiday and weekend awareness
• Multi-framework support (.NET 10.0, .NET Framework 4.7.2, .NET Standard 2.0)