Handle range inclusivity, escaping and short forms

Author: ejsmith

AGENTS.md

@@ -1,10 +1,8 @@
-# Agent Guidelines for Exceptionless.DateTimeExtensions
+# AGENTS.md
 
-You are an expert .NET engineer working on Exceptionless.DateTimeExtensions, a focused utility library providing DateTimeRange, Business Day/Week calculations, Elasticsearch-compatible date math parsing, and extension methods for DateTime, DateTimeOffset, and TimeSpan. Your changes must maintain backward compatibility, correctness across edge cases (especially timezone handling), and parsing reliability. Approach each task methodically: research existing patterns, make surgical changes, and validate thoroughly.
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
 
-**Craftsmanship Mindset**: Every line of code should be intentional, readable, and maintainable. Write code you'd be proud to have reviewed by senior engineers. Prefer simplicity over cleverness. When in doubt, favor explicitness and clarity.
-
-## Repository Overview
+## Overview
 
 Exceptionless.DateTimeExtensions provides date/time utilities for .NET applications:
 
@@ -18,19 +16,24 @@ Exceptionless.DateTimeExtensions provides date/time utilities for .NET applicati
 
 Design principles: **parse flexibility**, **timezone correctness**, **comprehensive edge case handling**, **netstandard2.0 compatibility**.
 
-## Quick Start
+## Build Commands
 
 ```bash
 # Build
 dotnet build Exceptionless.DateTimeExtensions.slnx
 
-# Test
+# Test all
 dotnet test Exceptionless.DateTimeExtensions.slnx
 
+# Test specific file/method
+dotnet test --filter "FullyQualifiedName~DateMathTests"
+
 # Format code
 dotnet format Exceptionless.DateTimeExtensions.slnx
 ```
 
+Warnings are treated as errors (`<WarningsAsErrors>true</WarningsAsErrors>`).
+
 ## Project Structure
 
 ```text
@@ -100,21 +103,11 @@ The library uses a **priority-ordered parser chain** for `DateTimeRange.Parse()`
 
 ## Coding Standards
 
-### Style & Formatting
-
-- Follow `.editorconfig` rules (file-scoped namespaces enforced, IDE0005 as error)
-- Follow [Microsoft C# conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
-- Run `dotnet format` to auto-format code
-- Match existing file style; minimize diffs
-- No code comments unless necessary—code should be self-explanatory
-
-### Code Quality
-
-- Write complete, runnable code—no placeholders, TODOs, or `// existing code...` comments
-- Use modern C# features compatible with **netstandard2.0**: be mindful of API availability
-- Follow SOLID, DRY principles; remove unused code and parameters
-- Clear, descriptive naming; prefer explicit over clever
+- File-scoped namespaces enforced (`csharp_style_namespace_declarations = file_scoped:error`)
+- Unnecessary usings are errors (`IDE0005`)
+- Target **netstandard2.0**: be mindful of API availability
 - Use `ConfigureAwait(false)` in library code (not in tests)
+- Private/internal fields use `_camelCase` prefix
 
 ### Parsing & Date Math Patterns
 
@@ -128,192 +121,24 @@ The library uses a **priority-ordered parser chain** for `DateTimeRange.Parse()`
 ### Common Patterns
 
 - **Extension methods**: Group by target type (`DateTimeExtensions.cs`, `DateTimeOffsetExtensions.cs`, `TimeSpanExtensions.cs`)
-- **Safe arithmetic**: Use overflow-protected add/subtract methods (`SafeAdd`, `SafeSubtract`) to avoid `ArgumentOutOfRangeException`
-- **Start/End helpers**: Provide `StartOf*` and `EndOf*` for all time periods (minute, hour, day, week, month, year)
-- **Exceptions**: Use `ArgumentException` for invalid input. Use `FormatException` for parsing failures. Return `false` from `TryParse` methods instead of throwing.
-
-### Single Responsibility
-
-- Each class has one reason to change
-- Methods do one thing well; extract when doing multiple things
-- Keep files focused: one primary type per file
-- Each parser handles one specific format pattern
-- If a method needs a comment explaining what it does, it should probably be extracted
-
-### Performance Considerations
-
-- **Avoid allocations in hot paths**: Parsing methods are called frequently; minimize string allocations
+- **Safe arithmetic**: Use `SafeAdd`, `SafeSubtract` to avoid `ArgumentOutOfRangeException`
+- **Exceptions**: Use `ArgumentException` for invalid input, `FormatException` for parsing failures. Return `false` from `TryParse` methods.
 - **Compiled regex**: Use `RegexOptions.Compiled` for frequently-used patterns
-- **Span-based parsing**: Where compatible with netstandard2.0, prefer span-based approaches
-- **Profile before optimizing**: Don't guess—measure
-- **Cache parser instances**: Parsers are discovered once via reflection and reused
-
-## Making Changes
-
-### Before Starting
-
-1. **Gather context**: Read related files, search for similar implementations, understand the full scope
-2. **Research patterns**: Find existing usages of the code you're modifying using grep/semantic search
-3. **Understand completely**: Know the problem, side effects, and edge cases before coding
-4. **Plan the approach**: Choose the simplest solution that satisfies all requirements
-5. **Check dependencies**: Verify you understand how changes affect dependent code
-
-### Pre-Implementation Analysis
-
-Before writing any implementation code, think critically:
-
-1. **What could go wrong?** Consider timezone edge cases, overflow/underflow, leap years, DST transitions
-2. **What are the parsing edge cases?** Ambiguous input, whitespace, case sensitivity, partial matches
-3. **What assumptions am I making?** Validate each assumption against existing tests
-4. **Is this the root cause?** Don't fix symptoms—trace to the core problem
-5. **Is there existing code that does this?** Search before creating new utilities
-
-### Test-First Development
-
-**Always write or extend tests before implementing changes:**
-
-1. **Find existing tests first**: Search for tests covering the code you're modifying
-2. **Extend existing tests**: Add test cases to existing test classes/methods when possible for maintainability
-3. **Write failing tests**: Create tests that demonstrate the bug or missing feature
-4. **Implement the fix**: Write minimal code to make tests pass
-5. **Refactor**: Clean up while keeping tests green
-6. **Verify edge cases**: Add tests for boundary conditions, timezone handling, and error paths
-
-**Why extend existing tests?** Consolidates related test logic, reduces duplication, improves discoverability, maintains consistent test patterns.
-
-### While Coding
-
-- **Minimize diffs**: Change only what's necessary, preserve formatting and structure
-- **Preserve behavior**: Don't break existing functionality or change semantics unintentionally
-- **Build incrementally**: Run `dotnet build` after each logical change to catch errors early
-- **Test continuously**: Run `dotnet test` frequently to verify correctness
-- **Match style**: Follow the patterns in surrounding code exactly
-
-### Validation
-
-Before marking work complete, verify:
-
-1. **Builds successfully**: `dotnet build Exceptionless.DateTimeExtensions.slnx` exits with code 0
-2. **All tests pass**: `dotnet test Exceptionless.DateTimeExtensions.slnx` shows no failures
-3. **No new warnings**: Check build output for new compiler warnings (warnings are treated as errors)
-4. **API compatibility**: Public API changes are intentional and backward-compatible when possible
-5. **Timezone correctness**: Verify explicit timezones are preserved and rounding respects offset
-6. **Breaking changes flagged**: Clearly identify any breaking changes for review
-
-### Error Handling
-
-- **Validate inputs**: Check for null, empty strings, invalid ranges at method entry
-- **Fail fast**: Throw exceptions immediately for invalid arguments (don't propagate bad data)
-- **Meaningful messages**: Include parameter names and expected values in exception messages
-- **TryParse pattern**: Always provide a `TryParse` alternative that returns `bool` instead of throwing
-- **Use guard clauses**: Early returns for invalid conditions, keep happy path unindented
 
 ## Testing
 
-### Philosophy: Battle-Tested Code
-
-Tests are not just validation—they're **executable documentation** and **design tools**. Well-tested code is:
-
-- **Trustworthy**: Confidence to refactor and extend
-- **Documented**: Tests show how the API should be used
-- **Resilient**: Edge cases are covered before they become production bugs
-
-### Framework
-
-- **xUnit** as the primary testing framework
-- **Foundatio.Xunit** provides `TestWithLoggingBase` for test output logging
-- Follow [Microsoft unit testing best practices](https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices)
-
-### Test-First Workflow
-
-1. **Search for existing tests**: `dotnet test --filter "FullyQualifiedName~MethodYouAreChanging"`
-2. **Extend existing test classes**: Add new `[Fact]` or `[Theory]` cases to existing files
-3. **Write the failing test first**: Verify it fails for the right reason
-4. **Implement minimal code**: Just enough to pass the test
-5. **Add edge case tests**: Null inputs, timezone boundaries, leap years, DST transitions, overflow
-6. **Run full test suite**: Ensure no regressions
-
-### Test Principles (FIRST)
-
-- **Fast**: Tests execute quickly
-- **Isolated**: No dependencies on external services or execution order
-- **Repeatable**: Consistent results every run
-- **Self-checking**: Tests validate their own outcomes
-- **Timely**: Write tests alongside code
-
-### Naming Convention
-
-Use the pattern: `MethodName_StateUnderTest_ExpectedBehavior`
-
-Examples:
-
-- `Parse_WithNowPlusOneHour_ReturnsOffsetDateTime`
-- `TryParse_WithInvalidExpression_ReturnsFalse`
-- `StartOfDay_WithDateTimeOffset_PreservesTimezone`
-
-### Test Structure
-
-Follow the AAA (Arrange-Act-Assert) pattern:
-
-```csharp
-[Fact]
-public void Parse_WithExplicitUtcDate_PreservesTimezone()
-{
-    // Arrange
-    var expression = "2025-01-01T01:25:35Z||+3d/d";
-    var baseTime = DateTimeOffset.UtcNow;
-
-    // Act
-    var result = DateMath.Parse(expression, baseTime);
-
-    // Assert
-    Assert.Equal(TimeSpan.Zero, result.Offset);
-    Assert.Equal(new DateTimeOffset(2025, 1, 4, 0, 0, 0, TimeSpan.Zero), result);
-}
-```
-
-### Parameterized Tests
-
-Use `[Theory]` with `[InlineData]` for multiple scenarios:
-
-```csharp
-[Theory]
-[InlineData("1s", 1000)]
-[InlineData("1m", 60000)]
-[InlineData("1h", 3600000)]
-[InlineData("1d", 86400000)]
-public void Parse_WithValidTimeUnit_ReturnsExpectedMilliseconds(string input, double expectedMs)
-{
-    var result = TimeUnit.Parse(input);
-    Assert.Equal(expectedMs, result.TotalMilliseconds);
-}
-```
-
-### Test Organization
-
-- Mirror the main code structure (e.g., `FormatParsers/` tests for `src/.../FormatParsers/`)
+- **xUnit** with **Foundatio.Xunit** (`TestWithLoggingBase` for test output logging)
+- Naming: `MethodName_StateUnderTest_ExpectedBehavior`
+- Use `[Theory]` with `[InlineData]` for parameterized tests
 - Use `FormatParserTestsBase` and `PartParserTestsBase` for parser tests
-- Inject `ITestOutputHelper` for test logging via `TestWithLoggingBase`
-
-### Running Tests
-
-```bash
-# All tests
-dotnet test Exceptionless.DateTimeExtensions.slnx
-
-# Specific test file
-dotnet test --filter "FullyQualifiedName~DateMathTests"
-
-# With logging
-dotnet test --logger "console;verbosity=detailed"
-```
+- Test structure mirrors main code (e.g., `tests/.../FormatParsers/` for `src/.../FormatParsers/`)
 
-## Debugging
+### Critical Edge Cases
 
-1. **Reproduce** with minimal steps—write a failing test
-2. **Understand** the root cause before fixing (especially for timezone and parsing issues)
-3. **Test** the fix thoroughly with multiple timezone scenarios
-4. **Document** non-obvious fixes in code if needed
+- Timezone boundaries (`Z`, `+05:00`, `-08:00`) - explicit timezones must be preserved
+- Leap years, DST transitions
+- Overflow/underflow in date arithmetic
+- Ambiguous parsing input, whitespace, case sensitivity
 
 ## Resources
 

README.md

@@ -56,12 +56,52 @@ var wildcardRange = DateTimeRange.Parse("[2023-01-01 TO *]", DateTime.Now); // F
 
 #### Date Math Features
 
-Supports full Elasticsearch date math syntax following [official specifications](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math):
+Supports full [Elasticsearch date math syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math):
 
 - **Anchors**: `now`, explicit dates with `||` separator
-- **Operations**: `+1d` (add), `-1h` (subtract), `/d` (round down)
+- **Operations**: `+1d` (add), `-1h` (subtract), `/d` (round)
 - **Units**: `y` (years), `M` (months), `w` (weeks), `d` (days), `h`/`H` (hours), `m` (minutes), `s` (seconds)
 - **Timezone Support**: Preserves explicit timezones (`Z`, `+05:00`, `-08:00`) or uses system timezone as fallback
+- **Escaped slashes**: `\/d` is treated identically to `/d` for contexts where `/` must be escaped
+
+##### Real-World Patterns
+
+```csharp
+// Common date range queries
+var thisMonth     = DateTimeRange.Parse("[now/M TO now/M]", now);    // Start of month through end of month
+var lastMonth     = DateTimeRange.Parse("[now-1M/M TO now/M}", now); // Start of last month through start of this month
+var yearToDate    = DateTimeRange.Parse("[now/y TO now]", now);      // Start of year through now
+var last7Days     = DateTimeRange.Parse("[now-7d/d TO now]", now);   // Start of 7 days ago through now
+var last15Minutes = DateTimeRange.Parse("[now-15m TO now]", now);    // 15 minutes ago through now
+var last24Hours   = DateTimeRange.Parse("[now-24h TO now]", now);    // 24 hours ago through now
+var tomorrow      = DateTimeRange.Parse("[now+1d/d TO now+1d/d]", now); // Start through end of tomorrow
+
+// Short-form comparison operators
+var recentItems   = DateTimeRange.Parse(">=now-1h", now);    // From 1 hour ago to max
+var futureOnly    = DateTimeRange.Parse(">now", now);         // After now to max
+var beforeToday   = DateTimeRange.Parse("<now/d", now);       // Min to start of today
+var throughToday  = DateTimeRange.Parse("<=now/d", now);      // Min to end of today
+```
+
+##### Rounding Behavior with Boundaries
+
+Rounding direction (`/d`, `/M`, etc.) is controlled by boundary inclusivity, following [Elasticsearch range query rounding rules](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html#date-math-rounding):
+
+| Boundary | Bracket | Operator | Rounding direction | `now/d` resolves to |
+| ---------- | --------- | ---------- | -------------------- | --------------------- |
+| Inclusive lower | `[` | `>=` | Floor (start of period) | `2025-02-16T00:00:00` |
+| Exclusive lower | `{` | `>` | Ceiling (end of period) | `2025-02-16T23:59:59.999` |
+| Inclusive upper | `]` | `<=` | Ceiling (end of period) | `2025-02-16T23:59:59.999` |
+| Exclusive upper | `}` | `<` | Floor (start of period) | `2025-02-16T00:00:00` |
+
+All four bracket combinations are supported: `[]`, `[}`, `{]`, `{}`.
+
+```csharp
+// [now/d TO now/d]  → start of today through end of today (full day, inclusive both ends)
+// [now/d TO now/d}  → start of today through start of today (exclusive upper)
+// {now/d TO now/d]  → end of today through end of today (exclusive lower)
+// {now/d TO now/d}  → collapsed to start of today (exclusive both ends inverts the range, which is then normalized)
+```
 
 Examples:
 

src/Exceptionless.DateTimeExtensions/DateMath.cs

@@ -29,11 +29,12 @@ public static class DateMath
     // https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options
     internal static readonly Regex Parser = new(
         @"\G(?<anchor>now|(?<date>\d{4}-?\d{2}-?\d{2}(?:[T\s](?:\d{1,2}(?::?\d{2}(?::?\d{2})?)?(?:\.\d{1,3})?)?(?:[+-]\d{2}:?\d{2}|Z)?)?)\|\|)" +
-        @"(?<operations>(?:[+\-/]\d*[yMwdhHms])*)(?=\s|$|[\]\}])",
+        @"(?<operations>(?:(?:[+\-]|\\?/)\d*[yMwdhHms])*)(?=\s|$|[\]\}])",
         RegexOptions.Compiled);
 
     // Pre-compiled regex for operation parsing to avoid repeated compilation
-    private static readonly Regex _operationRegex = new(@"([+\-/])(\d*)([yMwdhHms])", RegexOptions.Compiled);
+    // Supports both / and \/ (escaped forward slash) for rounding operations
+    private static readonly Regex _operationRegex = new(@"([+\-]|\\?/)(\d*)([yMwdhHms])", RegexOptions.Compiled);
 
     // Pre-compiled regex for offset parsing to avoid repeated compilation
     private static readonly Regex _offsetRegex = new(@"(Z|[+-]\d{2}:\d{2})$", RegexOptions.Compiled);
@@ -461,12 +462,12 @@ public static DateTimeOffset ApplyOperations(DateTimeOffset baseTime, string ope
             throw new ArgumentException("Invalid operations");
         }
 
-        // Validate that rounding operations (/) are only at the end
+        // Validate that rounding operations (/ or \/) are only at the end
         // According to Elasticsearch spec, rounding must be the final operation
         bool foundRounding = false;
         for (int i = 0; i < matches.Count; i++)
         {
-            string operation = matches[i].Groups[1].Value;
+            string operation = matches[i].Groups[1].Value.TrimStart('\\');
             if (String.Equals(operation, "/"))
             {
                 if (foundRounding)
@@ -485,7 +486,8 @@ public static DateTimeOffset ApplyOperations(DateTimeOffset baseTime, string ope
 
         foreach (Match opMatch in matches)
         {
-            string operation = opMatch.Groups[1].Value;
+            // Normalize escaped forward slash (\/) to unescaped (/) for rounding operations
+            string operation = opMatch.Groups[1].Value.TrimStart('\\');
             string amountStr = opMatch.Groups[2].Value;
             string unit = opMatch.Groups[3].Value;