MatchBrackets

Simple, fast bracket matching utilities for .NET 6 and .NET 8. Finds matching pairs, validates balance, computes nesting depth, and supports multiple bracket types.

• Namespace: MatchBrackets
• Primary type: Brackets
• Target frameworks: .NET 6 and .NET 8
• Thread-safe: Yes (pure static, no shared mutable state)
• Time complexity: O(n)
• Memory complexity: O(n)

Install

• Add a project reference, or install the NuGet package if published.
• Requires .NET 6 or .NET 8.

Quick start

Notes:

• Only the specified bracket characters are considered; all other characters are ignored.
• Many APIs return null when brackets are not balanced. GetPairsMultiple returns null on mismatch, but returns an empty dictionary for null/empty input.

Here are practical scenarios where MatchBrackets fits well.

Editor/IDE features

• Brace colorization and highlighting: GetPairs, GetPairsMultiple, GetPairsWithDepth, GetDepthMap
• Go to matching brace / caret navigation: FindMatchingIndex
• Code folding/outlining regions from bracketed ranges: GetPairs, GetPairsWithDepth
• Smart selection expansion to the enclosing pair: FindMatchingIndex, GetPairsWithDepth
• Auto-indentation/formatting based on nesting: GetDepthMap, GetPairsWithDepth

Validation and diagnostics

• CI/lint checks for templates, expressions, and configs using (), {}, [], <>: IsBalanced, GetFirstMismatch, GetPairsMultiple
• Pre-parse sanity checks in calculators, DSLs, query builders, SQL/Expression evaluators: IsBalanced, GetFirstMismatch
• User input feedback (highlight first error position/reason): GetFirstMismatch

Parsing and transformations

• Bracket-aware tokenization/splitting (e.g., split commas only at depth 0): GetDepthMap, GetPairsWithDepth

API reference

Single bracket type (defaults to ( and )):

• Dictionary<int,int>? GetPairs(string text, char openingnBracket = '(', char closingBracket = ')')
  • Returns opening→closing index pairs; null if unbalanced.
• bool IsBalanced(string input, char openingnBracket = '(', char closingBracket = ')')
  • true for balanced, false otherwise.

New in 1.1.0:

• int[]? GetDepthMap(string text, char openingBracket = '(', char closingBracket = ')')
  • Per-character depth map; -1 for non-bracket chars; null if unbalanced.
• int FindMatchingIndex(string text, int position, char openingBracket = '(', char closingBracket = ')')
  • Returns partner index for the bracket at position, or -1 if invalid/unbalanced.
• List<(int openIndex, int closeIndex, int depth)>? GetPairsWithDepth(string text, char openingBracket = '(', char closingBracket = ')')
  • All pairs with their nesting depth (outermost = 0); null if unbalanced.
• (int index, char character, string reason)? GetFirstMismatch(string text, char openingBracket = '(', char closingBracket = ')')
  • First mismatch diagnostic; null if balanced.
• Dictionary<int,int>? GetPairsMultiple(string text, params (char open, char close)[] bracketTypes)
  • Matches multiple types simultaneously (defaults to () { } [ ] < >). Returns null on mismatch/imbalance; empty dictionary for null/empty input.

Behavior details

• Unbalanced input:
  • GetPairs, GetDepthMap, GetPairsWithDepth → null
  • FindMatchingIndex → -1
  • GetPairsMultiple → null (unless the input is null/empty → returns empty dictionary)
• Empty or null strings:
  • IsBalanced → true
  • GetPairsMultiple → empty dictionary