README
¶
names
*names.Names implements a set of strings which can be searched by substrings.
The set is case-sensitive. To get case-insensitive behavior, apply strings.ToLower() or strings.ToUpper() on any strings passed and translate them back to their original form using a lookup map[string]string if needed.
Example Usage
const maxLookupSubstringRuneCount = 3
const supportRemove = true
people := names.New(maxLookupSubstringRuneCount, supportRemove)
people.Add("amelia", "james", "maxim", "luke", "sam")
result := people.Find("am", nil) // []string{"amelia", "james", "sam"}
people.Contains("james") // true
people.Remove("james") // this panics IFF supportRemove is false
result = people.Find("am", result) // []string{"amelia", "sam"}; result reused and returned as result[:2]
people.Contains("james") // false
Sorting
Often after querying for matches, one may want to sort the result alphabetically. To do this, see functions SortCIFunc, NewSortUXFunc and NewSortUXCIFunc for use with slices.Sortfunc() on string slices returned from Find().
Technical details
This implementation provides fast lookup speeds by maintainig a map[string][]string which maps all unique substrings up to a specified maximum length of every added string to a list of potential matches. You specify said maximum substring length as the first parameter in a call to names.New(). Higher values mean faster lookup speed at the cost of higher memory usage and lower insertion speed. As such, this implementation performs great for short strings, but poorly for long strings (i.e. over 100 runes per string).
It is possible to remove strings from the set, but only if you pass true as the second parameter in a call to names.New(). This is because an extra lookup map needs to maintained to allow for fast removal, which however increases memory usage and insertion speed further.
Documentation
¶
Index ¶
- func NewSortUXCIFunc(query string) func(a, b string) bool
- func NewSortUXFunc(query string) func(a, b string) bool
- func SortCIFunc(a, b string) bool
- type Names
- func (names *Names) Add(name string) bool
- func (names *Names) Contains(name string) bool
- func (names *Names) Find(query string, buffer []string) []string
- func (names *Names) IsRemoveSupported() bool
- func (names *Names) MaxLookupSubstringRuneCount() int
- func (names *Names) NumSearchNames(query string) int
- func (names *Names) Remove(name string) bool
- func (names *Names) Size() int
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewSortUXCIFunc ¶
Returns a sort function which sorts s case-insensitively, using case-sensitive sorting only where two strings are the same in their lower case forms, for user experience: strings case-insensitively starting with query come first.
func NewSortUXFunc ¶
Returns a sort function which sorts s for user experience: strings starting with query come first.
func SortCIFunc ¶
Sorts case-insensitively, using case-sensitive sorting only where two strings are the same in their lower case forms. Use as an argument to slices.SortFunc().
Types ¶
type Names ¶
type Names struct {
// contains filtered or unexported fields
}
Names is a set of strings which allows for substring search using Find().
func New ¶
Creates and returns a new *Names which maintains lookup lists for all substrings up to a length of maxLookupSubstringRuneCount runes. Increasing maxLookupSubstringRuneCount will increase memory usage. However, it will also increase performance of Find() as well as make overall memory usage more predictable. If you are unsure, start with a value of 1, which is the minimum. Set supportRemove to true if you need to call Remove().
func (*Names) Add ¶
Add adds name to names and returns true if name was not already contained in names; otherwise, Add does nothing and returns false. Add performs in amortized O(n) with n = len(name)*maxLookupSubstringRuneCount.
func (*Names) Contains ¶
Returns true if names contains name, false otherwise.
This method executes in constant time, i.e. O(1).
func (*Names) Find ¶
Returns a slice of all strings containing query. If buffer is non-nil, Find will use it to its full capacity for writing the result to, in an attempt to prevent unnecessary memory allocations.
When disregarding writes to the result slice, Find performs in O(1) when utf8.RuneCountInString(query) <= maxLookupSubstringRuneCount. Otherwise, Find performs in O(n) with n = length of query + total length of all strings in names containing the least common substring of query which is no longer than maxLookupSubstringRuneCount.
func (*Names) IsRemoveSupported ¶
IsRemoveSupported returns true if names can handle calls of Remove() without panicking.
func (*Names) MaxLookupSubstringRuneCount ¶
Returns the maxLookupSubstringRuneCount which was passed to New().
func (*Names) NumSearchNames ¶
Returns the amount of strings in names which would effectively get scanned to find matches when calling Find().
Source Files