match

func DerivePrefix ¶

func DerivePrefix(pattern string) string

DerivePrefix extracts the longest static prefix from a glob pattern.

The prefix is the portion of the pattern before any unescaped glob metacharacter. Escaped metacharacters (\*, \?, \[, \{) are treated as literals and included in the prefix. This prefix can be used to efficiently filter cloud storage listings.

Examples:

"data/2024/**/*.parquet" → "data/2024/"
"*.json"                 → ""
"logs/app-{a,b}/*.log"   → "logs/"
"exact/path/file.txt"    → "exact/path/file.txt"
"data/[0-9]*/*.csv"      → "data/"
"prefix/"                → "prefix/"
"data/file\*.txt"        → "data/file*.txt" (escaped * is literal)
"data/\[backup\]/*.log"  → "data/[backup]/" (escaped brackets are literal)

func DerivePrefixes ¶

func DerivePrefixes(patterns []string) []string

DerivePrefixes extracts prefixes from multiple patterns and deduplicates them.

The returned prefixes are:

• Derived from each include pattern
• Deduplicated (parent prefixes subsume children)
• Sorted for deterministic ordering

Examples:

["data/2024/**", "data/2025/**"] → ["data/2024/", "data/2025/"]
["data/**", "data/2024/**"]      → ["data/"]  (parent subsumes child)
["**/*.json"]                    → [""]       (empty = full listing)

func EnsureTrailingSlash ¶

func EnsureTrailingSlash(key string) string

EnsureTrailingSlash adds a trailing slash if not present. Returns empty string unchanged.

func FormatSize ¶

func FormatSize(bytes int64) string

FormatSize formats bytes as human-readable string using base-2 units.

func HasEmptyPrefix ¶

func HasEmptyPrefix(patterns []string) bool

HasEmptyPrefix returns true if any derived prefix is empty. An empty prefix means a full bucket listing is required. This is a scale concern and callers may want to warn users.

func HasTrailingSlash ¶

func HasTrailingSlash(key string) bool

HasTrailingSlash returns true if the key ends with a slash. This typically indicates a prefix/directory rather than a file.

func IsGlobPattern ¶

func IsGlobPattern(pattern string) bool

IsGlobPattern returns true if the pattern contains unescaped glob metacharacters.

This is escape-aware: literal metacharacters escaped with backslash (\*, \?, \[, \{) are not considered glob characters. This allows matching filenames that contain literal asterisks, question marks, or brackets.

Examples:

"data/**/*.parquet"  → true  (unescaped glob)
"data/file\*.txt"    → false (escaped asterisk is literal)
"data/file?.csv"     → true  (unescaped question mark)
"path/to/file.txt"   → false (no metacharacters)

func IsHidden ¶

func IsHidden(key string) bool

IsHidden returns true if any path segment starts with a dot.

Hidden segments follow Unix convention where files/directories starting with '.' are considered hidden.

The key is matched as-is without normalization, using '/' as separator.

Examples:

"path/to/file.txt"      → false
".hidden/file.txt"      → true
"path/.hidden/file.txt" → true
"path/to/.gitignore"    → true
"path/to/file.txt."     → false (dot at end is not hidden)

func JoinKeySegments ¶

func JoinKeySegments(segments []string) string

JoinKeySegments joins path segments into a key using / as separator.

func Normalize ¶

func Normalize(s string) string

Normalize is deprecated. Use NormalizeKey for keys or NormalizePattern for patterns.

This function exists for backward compatibility and calls NormalizePattern. New code should use the specific functions.

func NormalizeKey ¶

func NormalizeKey(key string) string

NormalizeKey returns a cloud object key unchanged.

Cloud storage keys (S3, GCS) are opaque strings where any character is valid, including /, //, leading /, *, ?, etc. We preserve key identity exactly as returned by the provider.

This function exists for documentation and potential future options. Currently it returns the key unchanged.

func NormalizePattern ¶

func NormalizePattern(pattern string) string

NormalizePattern converts a user-provided glob pattern to canonical form.

Normalization rules:

• Unescaped backslashes converted to forward slashes (Windows compat)
• Escaped backslashes and glob metacharacters preserved (\*, \?, \[, etc.)
• Leading slash, trailing slash, and // sequences preserved

This allows Windows users to write patterns like "data\2024\**\*.parquet" while preserving escape semantics for literal matching.

Examples:

"data/2024/**"        → "data/2024/**"       (unchanged)
"data\2024\**"        → "data/2024/**"       (backslash → slash)
"data/file\*.txt"     → "data/file\*.txt"    (escape preserved)
"data\\backup\\*"     → "data/backup/*"      (unescaped \ → /)
"/data/2024/**"       → "/data/2024/**"      (leading slash preserved)
"data//2024/**"       → "data//2024/**"      (// preserved)

func ParseDate ¶

func ParseDate(s string) (time.Time, error)

ParseDate parses an ISO 8601 date or datetime string.

Supported formats:

• Date only: "2024-01-15" (interpreted as start of day UTC)
• Datetime: "2024-01-15T10:30:00Z"
• Datetime with offset: "2024-01-15T10:30:00+05:00"

All times are normalized to UTC for comparison.

func ParseSize ¶

func ParseSize(s string) (int64, error)

ParseSize parses a human-readable size string.

Supported formats:

• Raw bytes: "1024", "104857600"
• Base-10 (SI): "1KB", "100MB", "1GB" (1KB = 1000 bytes)
• Base-2 (IEC): "1KiB", "100MiB", "1GiB" (1KiB = 1024 bytes)
• Case insensitive: "1kb", "1KB", "1Kb" all work

Note: KB/MB/GB use base-10 (SI standard), KiB/MiB/GiB use base-2 (IEC).

func SplitKeySegments ¶

func SplitKeySegments(key string) []string

SplitKeySegments splits a key into path segments using / as separator. Empty segments are preserved (for keys with // sequences).