6.6 KiB
API Reference
Complete API documentation for the Poindexter library.
Core Functions
Version
func Version() string
Returns the current version of the library.
Returns:
string: The version string (e.g., "0.2.0")
Example:
version := poindexter.Version()
fmt.Println(version) // Output: 0.2.0
Hello
func Hello(name string) string
Returns a greeting message.
Parameters:
name(string): The name to greet. If empty, defaults to "World"
Returns:
string: A greeting message
Examples:
// Greet the world
message := poindexter.Hello("")
fmt.Println(message) // Output: Hello, World!
// Greet a specific person
message = poindexter.Hello("Alice")
fmt.Println(message) // Output: Hello, Alice!
Sorting Functions
Basic Sorting
SortInts
func SortInts(data []int)
Sorts a slice of integers in ascending order in place.
Example:
numbers := []int{3, 1, 4, 1, 5, 9}
poindexter.SortInts(numbers)
fmt.Println(numbers) // Output: [1 1 3 4 5 9]
SortIntsDescending
func SortIntsDescending(data []int)
Sorts a slice of integers in descending order in place.
Example:
numbers := []int{3, 1, 4, 1, 5, 9}
poindexter.SortIntsDescending(numbers)
fmt.Println(numbers) // Output: [9 5 4 3 1 1]
SortStrings
func SortStrings(data []string)
Sorts a slice of strings in ascending order in place.
Example:
words := []string{"banana", "apple", "cherry"}
poindexter.SortStrings(words)
fmt.Println(words) // Output: [apple banana cherry]
SortStringsDescending
func SortStringsDescending(data []string)
Sorts a slice of strings in descending order in place.
SortFloat64s
func SortFloat64s(data []float64)
Sorts a slice of float64 values in ascending order in place.
SortFloat64sDescending
func SortFloat64sDescending(data []float64)
Sorts a slice of float64 values in descending order in place.
Advanced Sorting
SortBy
func SortBy[T any](data []T, less func(i, j int) bool)
Sorts a slice using a custom comparison function.
Parameters:
data: The slice to sortless: A function that returns true if data[i] should come before data[j]
Example:
type Person struct {
Name string
Age int
}
people := []Person{
{"Alice", 30},
{"Bob", 25},
{"Charlie", 35},
}
// Sort by age
poindexter.SortBy(people, func(i, j int) bool {
return people[i].Age < people[j].Age
})
// Result: [Bob(25) Alice(30) Charlie(35)]
SortByKey
func SortByKey[T any, K int | float64 | string](data []T, key func(T) K)
Sorts a slice by extracting a comparable key from each element in ascending order.
Parameters:
data: The slice to sortkey: A function that extracts a sortable key from each element
Example:
type Product struct {
Name string
Price float64
}
products := []Product{
{"Apple", 1.50},
{"Banana", 0.75},
{"Cherry", 3.00},
}
// Sort by price
poindexter.SortByKey(products, func(p Product) float64 {
return p.Price
})
// Result: [Banana(0.75) Apple(1.50) Cherry(3.00)]
SortByKeyDescending
func SortByKeyDescending[T any, K int | float64 | string](data []T, key func(T) K)
Sorts a slice by extracting a comparable key from each element in descending order.
Example:
type Student struct {
Name string
Score int
}
students := []Student{
{"Alice", 85},
{"Bob", 92},
{"Charlie", 78},
}
// Sort by score descending
poindexter.SortByKeyDescending(students, func(s Student) int {
return s.Score
})
// Result: [Bob(92) Alice(85) Charlie(78)]
Checking if Sorted
IsSorted
func IsSorted(data []int) bool
Checks if a slice of integers is sorted in ascending order.
IsSortedStrings
func IsSortedStrings(data []string) bool
Checks if a slice of strings is sorted in ascending order.
IsSortedFloat64s
func IsSortedFloat64s(data []float64) bool
Checks if a slice of float64 values is sorted in ascending order.
Binary Search
BinarySearch
func BinarySearch(data []int, target int) int
Performs a binary search on a sorted slice of integers.
Parameters:
data: A sorted slice of integerstarget: The value to search for
Returns:
int: The index where target is found, or -1 if not found
Example:
numbers := []int{1, 3, 5, 7, 9, 11}
index := poindexter.BinarySearch(numbers, 7)
fmt.Println(index) // Output: 3
BinarySearchStrings
func BinarySearchStrings(data []string, target string) int
Performs a binary search on a sorted slice of strings.
Parameters:
data: A sorted slice of stringstarget: The value to search for
Returns:
int: The index where target is found, or -1 if not found
KDTree Helpers
Poindexter provides helpers to build normalized, weighted KD points from your own records. These functions min–max normalize each axis over your dataset, optionally invert axes where higher is better (to turn them into “lower cost”), and apply per‑axis weights.
func Build2D[T any](
items []T,
id func(T) string,
f1, f2 func(T) float64,
weights [2]float64,
invert [2]bool,
) ([]KDPoint[T], error)
func Build3D[T any](
items []T,
id func(T) string,
f1, f2, f3 func(T) float64,
weights [3]float64,
invert [3]bool,
) ([]KDPoint[T], error)
func Build4D[T any](
items []T,
id func(T) string,
f1, f2, f3, f4 func(T) float64,
weights [4]float64,
invert [4]bool,
) ([]KDPoint[T], error)
Example (4D over ping, hops, geo, score):
// weights and inversion: flip score so higher is better → lower cost
weights := [4]float64{1.0, 0.7, 0.2, 1.2}
invert := [4]bool{false, false, false, true}
pts, err := poindexter.Build4D(
peers,
func(p Peer) string { return p.ID },
func(p Peer) float64 { return p.PingMS },
func(p Peer) float64 { return p.Hops },
func(p Peer) float64 { return p.GeoKM },
func(p Peer) float64 { return p.Score },
weights, invert,
)
if err != nil { panic(err) }
kdt, _ := poindexter.NewKDTree(pts, poindexter.WithMetric(poindexter.EuclideanDistance{}))
best, dist, _ := kdt.Nearest([]float64{0, 0, 0, 0})
Notes:
- Keep and reuse your normalization parameters (min/max) if you need consistency across updates; otherwise rebuild points when the candidate set changes.
- Use
invertto turn “higher is better” features (like scores) into lower costs for distance calculations.