runematcher

type Matcher interface {
	fmt.Stringer

	// Matches determines a true or false value for the given character.
	Matches(r rune) bool

	// Negate returns a matcher that matches any character not matched by this matcher.
	Negate() Matcher

	// And returns a matcher that matches any character matched by both this matcher and other.
	And(other Matcher) Matcher

	// Or returns a matcher that matches any character matched by either this matcher or other.
	Or(other Matcher) Matcher

	// MatchesAnyOf returns true if a character sequence contains at least one matching character.
	//
	// Equivalent to !MatchesNoneOf(sequence)
	MatchesAnyOf(str string) bool

	// MatchesAllOf returns true if a character sequence contains only matching characters.
	MatchesAllOf(str string) bool

	// MatchesNoneOf returns true if a character sequence contains no matching characters.
	//
	// Equivalent to !MatchesAnyOf(sequence).
	MatchesNoneOf(str string) bool

	// IndexIn returns the index of the first matching character in a character sequence,
	// starting from a given position, or -1 if no character matches after that position.
	IndexIn(str string, start int) int

	// IndexInRunes returns the index of the first matching character in a character sequence,
	// starting from a given position, or -1 if no character matches after that position.
	IndexInRunes(runes []rune, start int) int

	// LastIndexIn returns the index of the last matching character in a character sequence,
	// or -1 if no matching character is present.
	LastIndexIn(str string) int

	// CountIn returns the number of matching characters found in a character sequence.
	CountIn(str string) int

	// RemoveFrom returns a string containing all non-matching characters of a character sequence, in order.
	RemoveFrom(str string) string

	// RetainFrom returns a string containing all matching characters of a character sequence, in order.
	RetainFrom(str string) string

	// ReplaceFromRune returns a string copy of the input character sequence, with each matching character
	// replaced by a given replacement character.
	ReplaceFromRune(str string, replacement rune) string

	// ReplaceFrom returns a string copy of the input character sequence, with each matching character
	// replaced by a given replacement sequence.
	ReplaceFrom(str string, replacement string) string

	// TrimFrom returns a substring of the input character sequence that omits all matching characters
	// from the beginning and from the end of the string.
	TrimFrom(str string) string

	// TrimLeadingFrom returns a substring of the input character sequence that omits all matching characters
	// from the beginning of the string.
	TrimLeadingFrom(str string) string

	// TrimTrailingFrom returns a substring of the input character sequence that omits all matching characters
	// from the end of the string.
	TrimTrailingFrom(str string) string

	// CollapseFrom returns a string copy of the input character sequence, with each group of consecutive matching
	// characters replaced by a single replacement character.
	CollapseFrom(str string, replacement rune) string

	// TrimAndCollapseFrom collapses groups of matching characters exactly as CollapseFrom(str, replacement) does,
	// except that groups of matching characters at the start or end of the sequence are removed without replacement.
	TrimAndCollapseFrom(str string, replacement rune) string
}