README
¶
nameutil
Package nameutil provides utilities for resolving name collisions by assigning sequential numeric suffixes.
Purpose
This package helps manage situations where multiple items share the same base name and need unique identifiers. It provides two strategies:
- Batch processing: When all items are known upfront (
ResolveCollisions) - Incremental processing: When items are processed one-by-one with filesystem checks (
NameReserver)
Configuration
Collision resolution behavior is controlled by CollisionConfig:
type CollisionConfig struct {
PaddingDigits int // Number of zeros to pad (default: 2)
FirstWithSuffix bool // Whether first item gets a suffix (default: false)
}
Examples:
PaddingDigits: 2, FirstWithSuffix: false→file,file-02,file-03PaddingDigits: 2, FirstWithSuffix: true→file-01,file-02,file-03PaddingDigits: 3, FirstWithSuffix: false→file,file-002,file-003
Functions
ResolveCollisions
func ResolveCollisions[T Item](items []T, cfg CollisionConfig)
Resolves collisions for a batch of items in memory. Items sharing the same base name get sequential suffixes assigned according to the configuration.
Use when: All items are known upfront and you want to process them in a single pass.
Example:
type MyItem struct {
name string
}
func (m *MyItem) GetBaseName() string { return m.name }
func (m *MyItem) SetBaseName(name string) { m.name = name }
items := []*MyItem{
{name: "file"},
{name: "file"},
{name: "file"},
}
nameutil.ResolveCollisions(items, nameutil.DefaultCollisionConfig())
// Result: items[0].name = "file"
// items[1].name = "file-02"
// items[2].name = "file-03"
NameReserver
type NameReserver struct {
OutDir string
Config CollisionConfig
// ... internal fields
}
func NewNameReserver(outDir string, cfg CollisionConfig) *NameReserver
func (r *NameReserver) ReserveName(base, ext string) (string, error)
Incrementally reserves unique names, checking both in-memory state and filesystem.
Use when: Processing items one-by-one and need to avoid conflicts with existing files.
Example:
reserver := nameutil.NewNameReserver("/output", nameutil.DefaultCollisionConfig())
name1, _ := reserver.ReserveName("file", ".txt") // "file.txt"
name2, _ := reserver.ReserveName("file", ".txt") // "file-02.txt"
name3, _ := reserver.ReserveName("file", ".txt") // "file-03.txt"
Item Interface
To use ResolveCollisions, types must implement the Item interface:
type Item interface {
GetBaseName() string
SetBaseName(name string)
}
Used By
- cmd-dev/sync-test-cases - Batch collision resolution for test fixtures
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ResolveCollisions ¶
func ResolveCollisions[T Item](items []T, cfg CollisionConfig)
ResolveCollisions assigns unique names to items with the same base name. Items are grouped by their current base name, and suffixes are assigned according to the collision config.
This is useful for batch processing where all items are known upfront.
Types ¶
type CollisionConfig ¶
type CollisionConfig struct {
// PaddingDigits specifies how many digits to use for suffix numbers (default: 2)
// Examples: 2 -> "-02", 3 -> "-003"
PaddingDigits int
// FirstWithSuffix determines whether the first item gets a suffix
// false (default): first="base", second="base-02", third="base-03"
// true: first="base-01", second="base-02", third="base-03"
FirstWithSuffix bool
}
CollisionConfig controls how name collisions are resolved.
func DefaultCollisionConfig ¶
func DefaultCollisionConfig() CollisionConfig
DefaultCollisionConfig returns the default configuration. - PaddingDigits: 2 (produces -02, -03, etc.) - FirstWithSuffix: false (first item has no suffix)
type NameReserver ¶
type NameReserver struct {
OutDir string
Config CollisionConfig
// contains filtered or unexported fields
}
NameReserver helps reserve unique names incrementally, checking both in-memory state and filesystem.
This is useful for processing items one-by-one where you need to check if files already exist on disk.
func NewNameReserver ¶
func NewNameReserver(outDir string, cfg CollisionConfig) *NameReserver
NewNameReserver creates a new name reserver for the given output directory.
func (*NameReserver) ReserveName ¶
func (r *NameReserver) ReserveName(base, ext string) (string, error)
ReserveName attempts to reserve a unique name for the given base and extension. It first tries the base name, then adds numeric suffixes until an available name is found. Returns the reserved name (including extension) or an error if no name could be found.
Source Files