Documentation
¶
Overview ¶
Package idcodec provides consolidated ID encoding/decoding operations. This package delegates to internal/encoding for the core base-63 algorithm and provides type-safe wrappers for LCI-specific ID types.
Base-63 Alphabet: A-Z (0-25), a-z (26-51), 0-9 (52-61), _ (62) This provides ~6 character IDs for typical projects (vs ~16 for hex).
Index ¶
- Constants
- Variables
- func Decode(encoded string) (uint64, error)
- func DecodeComposite(encoded string) (types.FileID, uint32, error)
- func DecodeFileID(encoded string) (types.FileID, error)
- func DecodeSymbolID(encoded string) (types.SymbolID, error)
- func Encode(value uint64) string
- func EncodeComposite(fileID types.FileID, localSymbolID uint32) string
- func EncodeFileID(id types.FileID) string
- func EncodeNoZero(value uint64) string
- func EncodeSymbolID(id types.SymbolID) string
- func IsValid(encoded string) bool
- func IsValidSymbolID(encoded string) bool
- func MustDecodeSymbolID(encoded string) types.SymbolID
- func PackComposite(fileID types.FileID, localSymbolID uint32) uint64
- func UnpackComposite(packed uint64) (types.FileID, uint32)
- type DeletedFileChecker
- type LookupError
- type LookupErrorReason
- type LookupResult
- type SymbolGetter
- type SymbolLookup
- func (l *SymbolLookup) DecodeAndGet(encoded string) (*types.EnhancedSymbol, error)
- func (l *SymbolLookup) Get(id types.SymbolID) (*types.EnhancedSymbol, error)
- func (l *SymbolLookup) GetMultiple(ids []types.SymbolID) []LookupResult
- func (l *SymbolLookup) GetMultipleValid(ids []types.SymbolID) []*types.EnhancedSymbol
- func (l *SymbolLookup) GetOrNil(id types.SymbolID) *types.EnhancedSymbol
- func (l *SymbolLookup) MustGet(id types.SymbolID) *types.EnhancedSymbol
Constants ¶
const ( Base = encoding.Base63 Alphabet = encoding.Alphabet63 )
Re-export constants from encoding package for convenience
Variables ¶
var ( ErrEmptyString = encoding.ErrEmptyString ErrInvalidChar = encoding.ErrInvalidChar ErrOverflow = encoding.ErrOverflow )
Re-export errors from encoding package for use with errors.Is
var ( ErrSymbolNotFound = &LookupError{Reason: ReasonNotFound} ErrSymbolFileDeleted = &LookupError{Reason: ReasonDeletedFile} ErrSymbolInvalidID = &LookupError{Reason: ReasonInvalidID} )
Sentinel errors for use with errors.Is
Functions ¶
func Decode ¶
Decode decodes a base-63 string to a uint64 value. Returns error for empty strings or invalid characters. Delegates to encoding.Base63Decode.
func DecodeComposite ¶
DecodeComposite decodes a base-63 string to FileID and LocalSymbolID. Returns error for invalid input.
func DecodeFileID ¶
DecodeFileID decodes a base-63 string to a FileID.
func DecodeSymbolID ¶
DecodeSymbolID decodes a base-63 string to a SymbolID. Returns error for invalid input.
func Encode ¶
Encode encodes a uint64 value to a base-63 string. Returns "A" for zero (minimum non-empty encoding). Delegates to encoding.Base63Encode.
func EncodeComposite ¶
EncodeComposite encodes a FileID and LocalSymbolID into a single base-63 string. The values are packed as: uint64(fileID) | (uint64(localSymbolID) << 32)
func EncodeFileID ¶
EncodeFileID encodes a FileID to a base-63 string.
func EncodeNoZero ¶
EncodeNoZero encodes a uint64 value to a base-63 string. Returns empty string for zero value (used for composite IDs where 0 means "none"). Delegates to encoding.Base63EncodeNoZero.
func EncodeSymbolID ¶
EncodeSymbolID encodes a SymbolID to a base-63 string. This is the canonical function for encoding symbol IDs throughout LCI.
SymbolID in LCI is a raw uint64 index into the symbol store. It is NOT a packed FileID+LocalSymbolID (that's CompositeSymbolID).
func IsValid ¶
IsValid checks if a string is a valid base-63 encoded value. Delegates to encoding.Base63IsValid.
func IsValidSymbolID ¶
IsValidSymbolID checks if a string is a valid base-63 encoded SymbolID.
func MustDecodeSymbolID ¶
MustDecodeSymbolID decodes a base-63 string to a SymbolID. Panics on error - use only when the input is known to be valid.
func PackComposite ¶
PackComposite packs FileID and LocalSymbolID into a uint64. Use this when you need the raw packed value.
Types ¶
type DeletedFileChecker ¶
DeletedFileChecker is the interface for checking if a file is deleted.
type LookupError ¶
type LookupError struct {
SymbolID types.SymbolID
Reason LookupErrorReason
Detail string // Optional additional detail
}
LookupError provides context about why a symbol lookup failed.
func NewDeletedFileError ¶
func NewDeletedFileError(id types.SymbolID, filePath string) *LookupError
NewDeletedFileError creates a deleted-file error for a specific symbol ID.
func NewInvalidIDError ¶
func NewInvalidIDError(id types.SymbolID, detail string) *LookupError
NewInvalidIDError creates an invalid-ID error.
func NewNotFoundError ¶
func NewNotFoundError(id types.SymbolID) *LookupError
NewNotFoundError creates a not-found error for a specific symbol ID.
func (*LookupError) Error ¶
func (e *LookupError) Error() string
func (*LookupError) Is ¶
func (e *LookupError) Is(target error) bool
Is implements errors.Is for LookupError.
type LookupErrorReason ¶
type LookupErrorReason int
LookupErrorReason indicates why a symbol lookup failed.
const ( // ReasonNotFound indicates the symbol ID does not exist in the index. ReasonNotFound LookupErrorReason = iota // ReasonDeletedFile indicates the symbol's file has been deleted. ReasonDeletedFile // ReasonInvalidID indicates the provided ID was malformed. ReasonInvalidID )
func (LookupErrorReason) String ¶
func (r LookupErrorReason) String() string
type LookupResult ¶
type LookupResult struct {
ID types.SymbolID
Symbol *types.EnhancedSymbol
Error error
}
LookupResult holds a symbol lookup result with possible error.
type SymbolGetter ¶
type SymbolGetter interface {
GetEnhancedSymbol(symbolID types.SymbolID) *types.EnhancedSymbol
}
SymbolGetter is the interface for symbol lookup. Implemented by ReferenceTracker.
type SymbolLookup ¶
type SymbolLookup struct {
// contains filtered or unexported fields
}
SymbolLookup provides safe symbol lookup with proper error handling. It wraps a SymbolGetter to provide typed errors.
func NewSymbolLookup ¶
func NewSymbolLookup(getter SymbolGetter, deletedChecker DeletedFileChecker) *SymbolLookup
NewSymbolLookup creates a new SymbolLookup.
func (*SymbolLookup) DecodeAndGet ¶
func (l *SymbolLookup) DecodeAndGet(encoded string) (*types.EnhancedSymbol, error)
DecodeAndGet decodes a base-63 string and looks up the symbol. Combines DecodeSymbolID and Get into a single operation.
func (*SymbolLookup) Get ¶
func (l *SymbolLookup) Get(id types.SymbolID) (*types.EnhancedSymbol, error)
Get looks up a symbol by ID with proper error handling. Returns (*EnhancedSymbol, nil) on success. Returns (nil, *LookupError) with specific reason on failure.
func (*SymbolLookup) GetMultiple ¶
func (l *SymbolLookup) GetMultiple(ids []types.SymbolID) []LookupResult
GetMultiple looks up multiple symbols, returning results for all. Continues on errors, returning partial results.
func (*SymbolLookup) GetMultipleValid ¶
func (l *SymbolLookup) GetMultipleValid(ids []types.SymbolID) []*types.EnhancedSymbol
GetMultipleValid looks up multiple symbols, returning only valid results. Silently skips errors.
func (*SymbolLookup) GetOrNil ¶
func (l *SymbolLookup) GetOrNil(id types.SymbolID) *types.EnhancedSymbol
GetOrNil looks up a symbol by ID, returning nil without error if not found. Use this when you expect some lookups to fail (e.g., in batch operations).
func (*SymbolLookup) MustGet ¶
func (l *SymbolLookup) MustGet(id types.SymbolID) *types.EnhancedSymbol
MustGet looks up a symbol by ID, panicking if not found. Use this only when you're certain the symbol exists.
Source Files