Toolbox.Utilities 1.0.0

Toolbox.Utilities

A .NET library providing essential utility functions and extension methods for common programming tasks including collections, dates, and enumerations.

Overview

Toolbox.Utilities is a lightweight, high-performance utility library designed for personal and professional use. It provides a collection of extension methods and helper functions that enhance productivity when working with common .NET types and operations.

Features

• Collection Extensions: Enhanced collection manipulation with fluent extension methods
• Date Utilities: Helper functions for date calculations and manipulations
• Enum Utilities: Easy access to enum descriptions and metadata
• .NET 9.0 Compatible: Built with modern C# 13 features and nullable reference types
• Zero Dependencies: Lightweight with no external dependencies
• High Performance: Optimized implementations following .NET best practices
• Memory Efficient: Designed with performance and memory usage in mind

Installation

Install the Toolbox.Utilities NuGet package:

dotnet add package Toolbox.Utilities

Or via Package Manager Console:

Install-Package Toolbox.Utilities

Quick Start

Collection Extensions

using Toolbox.Utilities;

// Add multiple items to any ICollection<T>
var list = new List<string> { "item1" };
var newItems = new[] { "item2", "item3", "item4" };
list.AddRange(newItems); // Returns the original list for chaining

// Works with any ICollection<T> implementation
var hashSet = new HashSet<int> { 1 };
hashSet.AddRange(new[] { 2, 3, 4 });

Date Utilities

using Toolbox.Utilities;

// Get the Monday of any week
var someDate = new DateOnly(2024, 3, 15); // Friday
var monday = someDate.GetMonday(); // Returns Monday of that week

// Useful for week-based calculations
var today = DateOnly.FromDateTime(DateTime.Today);
var startOfWeek = today.GetMonday();

Enum Utilities

using System.ComponentModel;
using Toolbox.Utilities;

public enum Status
{
    [Description("Task is pending")]
    Pending,
    
    [Description("Task is in progress")]
    InProgress,
    
    [Description("Task completed successfully")]
    Completed
}

// Get human-readable descriptions
var status = Status.InProgress;
var description = status.GetEnumDescription(); // "Task is in progress"

API Reference

Collections Class

AddRange<TCol, TItem> Extension Method

Adds multiple items to any collection that implements ICollection<T>.

public static TCol AddRange<TCol, TItem>(this TCol destination, IEnumerable<TItem> source)
    where TCol : ICollection<TItem>

Parameters:

• destination: The target collection to add items to
• source: The items to add to the collection

Returns: The original collection for method chaining

Throws:

• ArgumentNullException: When destination or source is null

Performance Notes:

• Optimized for List<T> using the built-in AddRange method
• Falls back to individual Add calls for other collection types

Dates Class

GetMonday Extension Method

Gets the Monday of the week for the specified date.

public static DateOnly GetMonday(this DateOnly date)

Parameters:

• date: The date to find the Monday for

Returns: The DateOnly representing the Monday of the same week

Example:

var friday = new DateOnly(2024, 3, 15);
var monday = friday.GetMonday(); // Returns 2024-03-11

Enums Class

GetEnumDescription Extension Method

Retrieves the description attribute value for an enum value, or the enum name if no description is found.

public static string GetEnumDescription(this Enum value)

Parameters:

• value: The enum value to get the description for

Returns: The description from the DescriptionAttribute, or the enum's string representation if no attribute is found

Example:

public enum Priority
{
    [Description("Low priority item")]
    Low,
    High // No description attribute
}

Priority.Low.GetEnumDescription();  // "Low priority item"
Priority.High.GetEnumDescription(); // "High"

Usage Examples

Fluent Collection Operations

using Toolbox.Utilities;

var result = new List<string>()
    .AddRange(new[] { "first", "second" })
    .AddRange(GetMoreItems())
    .AddRange(new[] { "last" });

Week-Based Date Calculations

using Toolbox.Utilities;

// Get all dates in the current week
var today = DateOnly.FromDateTime(DateTime.Today);
var monday = today.GetMonday();
var weekDates = Enumerable.Range(0, 7)
    .Select(i => monday.AddDays(i))
    .ToList();

Enum-Driven UI Components

using System.ComponentModel;
using Toolbox.Utilities;

public enum UserRole
{
    [Description("Regular User")]
    User,
    
    [Description("System Administrator")]
    Admin,
    
    [Description("Content Moderator")]
    Moderator
}

// Generate dropdown options
var roleOptions = Enum.GetValues<UserRole>()
    .Select(role => new { Value = role, Text = role.GetEnumDescription() })
    .ToList();

Performance Considerations

• Collections.AddRange: Uses the optimized List<T>.AddRange when available, otherwise iterates efficiently
• Dates.GetMonday: Performs simple arithmetic operations without creating intermediate objects
• Enums.GetEnumDescription: Uses reflection but caches are handled by the .NET runtime

Best Practices

1. Null Safety

All methods include appropriate null checks and follow nullable reference type conventions:

// Safe usage with null checks
ICollection<string>? maybeNull = GetCollection();
if (maybeNull != null)
{
    maybeNull.AddRange(items);
}

2. Method Chaining

Take advantage of the fluent interface design:

var result = new List<int>()
    .AddRange(firstBatch)
    .AddRange(secondBatch)
    .AddRange(thirdBatch);

3. Enum Documentation

Always use DescriptionAttribute for user-facing enum values:

public enum Status
{
    [Description("Order is being processed")]
    Processing,
    
    [Description("Order has been shipped")]
    Shipped
}

Limitations

• GetMonday assumes Monday as the first day of the week (ISO 8601 standard)
• GetEnumDescription uses reflection, which may have performance implications in tight loops
• AddRange creates individual add operations for non-List collections

Troubleshooting

Common Issues

ArgumentNullException in AddRange

• Ensure both the target collection and source enumerable are not null
• Check that the source enumerable is properly initialized

Unexpected Monday Calculation

• Verify that you're using DateOnly and not DateTime
• Remember that the calculation assumes Monday as the first day of the week

Missing Enum Descriptions

• Ensure you've added the using System.ComponentModel; directive
• Verify that DescriptionAttribute is properly applied to enum values

Contributing

This project is designed for personal usage. For issues or suggestions, please refer to the project repository.

License

This project is licensed under the MIT License. See the project repository for details.

Version History

See the CHANGELOG.md for version history and release notes.

Related Projects

• ToolBox.File - CSV file reading utilities
• Toolbox.ADO - Database connection utilities
• Toolbox.VariousTools - Additional utility functions