# Patterns are abstract string motifs (include `String` and `Char`).
interface Pattern
	# Search `self` into `s` from a certain position.
	# Return the position of the first character of the matching section.
	# Return -1 if not found.
	#
	#     assert 'l'.search_index_in("hello world", 0)  == 2
	#     assert 'l'.search_index_in("hello world", 3)  == 3
	#     assert 'z'.search_index_in("hello world", 0)  == -1
	#
	# This method is usually faster than `search_in` if what is
	# required is only the index.
	# Note: in most implementation, `search_in` is implemented with this method.
	protected fun search_index_in(s: Text, from: Int): Int is abstract

	# Search `self` into `s` from a certain position.
	# Return null if not found.
	#
	#     assert 'l'.search_in("hello world", 0).from  == 2
	#     assert 'l'.search_in("hello world", 3).from  == 3
	#     assert 'z'.search_in("hello world", 0)       == null
	#
	# If only the index of the first character if required, see `search_index_in`.
	#
	# Note: Is used by `String::search`, `String::search_from`, and others.
	protected fun search_in(s: Text, from: Int): nullable Match is abstract

	# Search all `self` occurrences into `s`.
	#
	#     assert 'l'.search_all_in("hello world").length  == 3
	#     assert 'z'.search_all_in("hello world").length  == 0
	#
	# Note: Is used by `String::search_all`.
	protected fun search_all_in(s: Text): Array[Match]
	do
		var res = new Array[Match] # Result
		var match = search_in(s, 0)
		while match != null do
			res.add(match)
			match = search_in(s, match.after)
		end
		return res
	end

	# Split `s` using `self` is separator.
	#
	# Returns an array of matches that are between each occurence of `self`.
	# If self is not present, an array with a single match on `s` is retunred.
	#
	#     assert 'l'.split_in("hello world").join("|")  == "he||o wor|d"
	#     assert 'z'.split_in("hello world").join("|")  == "hello world"
	#
	# Note: is used by `String::split`
	protected fun split_in(s: Text): Array[Match]
	do
		var res = new Array[Match] # Result
		var i = 0 # Cursor
		var match = search_in(s, 0)
		while match != null do
			# Compute the splited part length
			var len = match.from - i
			res.add(new Match(s.to_s, i, len))
			i = match.after
			match = search_in(s, i)
		end
		# Add the last part
		res.add(new Match(s.to_s, i, s.length - i))
		return res
	end

	# Is `self` in `s`?
	protected fun is_in(s: Text): Bool do return search_index_in(s, 0) != -1
end