IntelliDataSort 1.0.0

IntelliDataSort – HumanSort Engine

Secure, culture-aware sorting and parsing engine for real-world string data

IntelliDataSort (powered by HumanSort) is a high-precision sorting library for .NET designed to safely handle untrusted, mixed-format, and international string data.

It combines:

• Explicit type declaration (no ambiguous auto-detection)
• Strict validation
• Secure parsing
• Stable, human-friendly sorting
• Parsed output for filtering & auditing

Ideal for data grids, reports, logs, CSV/Excel imports, admin panels, and console tooling where correctness and security matter.

🔍 What Problems Does It Solve?

Common issues with traditional sorting:

• "file10" sorted before "file2"
• "₹1,00,000" treated as invalid
• "04/07/2023" misinterpreted across cultures
• Injection payloads silently accepted
• Mixed formats producing unstable results

HumanSort solves these with explicit type declaration and strict validation.

✨ Core Capabilities

Sorting Types

• Human-friendly natural string sorting
• Numeric sorting (int, decimal, scientific, hex, binary)
• Culture-aware date & time sorting
• Currency sorting with regional rules
• Percentage sorting with strict validation
• File size sorting (B → YB, decimal & binary)
• IP address sorting (IPv4)
• Semantic version sorting (SemVer)

Filtering Support

• Parsed output exposed via out parameter for post-sort filtering
• Invalid values explicitly identified (parsed = null)
• No silent coercion or guessing

📦 Installation (NuGet)

dotnet add package IntelliDataSort

🚀 Quick Start

using IntelliDataSort;

var sorter = new HumanSort();

var data = new List<string>
{
    "file10",
    "file2",
    "file1"
};

// REQUIRED: Explicitly specify column type
var result = sorter.Sort(
    data,
    HumanSort.ColumnType.NaturalString,  // ← MANDATORY parameter
    ascending: true,
    nullHandling: HumanSort.NullHandling.NullsFirst
);

// Result: ["file1", "file2", "file10"]

⚠️ Critical API Change: Explicit Type Declaration Required

forceType is now a REQUIRED non-nullable parameter.
Auto-detection has been removed to prevent silent failures and ambiguous behavior.

✅ Correct usage:

sorter.Sort(data, HumanSort.ColumnType.Number, true);

❌ Will not compile:

// Missing required forceType parameter
sorter.Sort(data, true); 

Why this change? Ambiguous inputs like "1.234" could mean 1.234 (decimal) or 1234 (thousands separator) depending on culture. HumanSort requires explicit intent to guarantee deterministic results.

🧩 Supported Column Types

💱 Currency Sorting

var data = new List<string>
{
    "(₹1,00,000)",
    "₹10",
    "₹1,00,00,000"
};

var result = sorter.Sort(
    data,
    HumanSort.ColumnType.Currency,
    ascending: true,
    nullHandling: HumanSort.NullHandling.NullsFirst
);

✔ Parentheses negatives: (₹100) → -100
✔ Indian numbering system (lakh/crore)
✔ Strict validation (rejects ambiguous inputs)
✔ No mixed-currency coercion

📅 Date Sorting (Culture-Aware)

var culture = new CultureInfo("en-GB"); // Day-first culture

var data = new List<string>
{
    "04/07/2023",  // 4 July 2023 (not April!)
    "01/12/2024",
    "07/08/2022"
};

var result = sorter.Sort(
    data,
    HumanSort.ColumnType.DateTime,
    ascending: true,
    nullHandling: null,
    dateTimeCulture: culture,  // ← Only valid for DateTime
    out var parsedValues
);

⚠️ dateTimeCulture parameter is only accepted when forceType = ColumnType.DateTime. Using it with other types throws ArgumentException.

📊 Percentage Sorting

var data = new List<string>
{
    "10%",
    "(15%)",   // → -15
    "25 pct",
    "50 percent"
};

var result = sorter.Sort(
    data,
    HumanSort.ColumnType.Percentage,
    ascending: true
);

Accepted: 10%, (15%), 25 pct, 50 percent, -30%
Rejected: 100 (no % indicator), $50, 10% KB, percent 50

🧪 Parsed Values Output

All sort operations support an out parameter for parsed values:

var result = sorter.Sort(
    data,
    HumanSort.ColumnType.Number,
    ascending: true,
    nullHandling: null,
    out List<(string original, object parsed)> parsedValues
);

// Inspect parsed values for filtering/auditing
foreach (var (original, parsed) in parsedValues)
{
    Console.WriteLine($"{original} → {parsed ?? "INVALID"}");
}

🔐 Security Model

Zero-trust input philosophy: Ambiguous or potentially malicious inputs are rejected, not guessed.

Actively Rejected Inputs

• SQL injection attempts (' OR 1=1 --)
• XSS/script payloads (<script>)
• HTML/XML fragments
• Unicode control/invisible characters
• Mixed units (100$€)
• Extreme numeric values (DoS prevention)
• Scientific notation in currencies ($1e5)
• Roman numerals with currency symbols ($X)

Security Note: This parser implements strict allow-list validation per OWASP guidelines. It reduces injection risk at the input boundary but does not replace downstream security controls (parameterized queries, output encoding, access control).

⚙️ Public API Surface

Visible Types (Users Can Access)

namespace IntelliDataSort
{
    public sealed class HumanSort
    {
        public enum ColumnType { ... }
        public enum NullHandling { ... }
        public enum NaturalSortCaseSensitivity { ... }
        
        public HumanSort();
        
        public IReadOnlyList<string> Sort(
            IEnumerable<string> data,
            ColumnType forceType,          // ← REQUIRED (non-nullable)
            bool ascending = true,
            NullHandling? nullHandling = null
        );
        
        public IReadOnlyList<string> Sort(
            IEnumerable<string> data,
            ColumnType forceType,
            bool ascending,
            NullHandling? nullHandling,
            out List<(string original, object parsed)> parsedValues
        );
        
        public IReadOnlyList<string> Sort(
            IEnumerable<string> data,
            ColumnType forceType,
            bool ascending,
            NullHandling? nullHandling,
            CultureInfo dateTimeCulture,   // ← DateTime only
            out List<(string original, object parsed)> parsedValues
        );
        
        // ===== VALIDATION METHODS =====
        public bool IsValidCurrencyLiteral(string input);
        public bool IsValidCurrencyLiteral(string input, string expectedCurrencyCode);
        public static bool IsValidIpAddressExact(string input);


        public IReadOnlyCollection<string> GetCurrencySymbols();
        public IReadOnlyCollection<string> GetCurrencyCodes();
    }
}

Hidden Implementation Details

• All validators (NumberValidator, CurrencyValidator, etc.) → internal
• All helpers (VersionParser, TokenListComparer, etc.) → private/internal
• Configuration classes → private sealed
• Regex patterns & dictionaries → private static readonly

🧾 License

Proprietary License

© 2026 Mohd Nasrullah Kazmi (IntelliDataSort).
All rights reserved.

Unauthorized copying, modification, distribution, or commercial use is prohibited unless explicitly permitted by the author.