1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.text.matcher;
19
20 import org.apache.commons.lang3.CharSequenceUtils;
21
22 /**
23 * Determines if a character array portion matches.
24 *
25 * @since 1.3
26 */
27 public interface StringMatcher {
28
29 /**
30 * Returns a matcher that matches this matcher followed by the given matcher.
31 *
32 * @param stringMatcher the next matcher.
33 * @return a matcher that matches this matcher followed by the given matcher.
34 * @since 1.9
35 */
36 default StringMatcher andThen(final StringMatcher stringMatcher) {
37 return StringMatcherFactory.INSTANCE.andMatcher(this, stringMatcher);
38 }
39
40 /**
41 * Returns the number of matching characters, zero for no match.
42 * <p>
43 * This method is called to check for a match. The parameter {@code pos} represents the current position to be
44 * checked in the string {@code buffer} (a character array which must not be changed). The API guarantees that
45 * {@code pos} is a valid index for {@code buffer}.
46 * </p>
47 * <p>
48 * The matching code may check one character or many. It may check characters preceding {@code pos} as well as those
49 * after.
50 * </p>
51 * <p>
52 * It must return zero for no match, or a positive number if a match was found. The number indicates the number of
53 * characters that matched.
54 * </p>
55 *
56 * @param buffer the text content to match against, do not change
57 * @param pos the starting position for the match, valid for buffer
58 * @return The number of matching characters, zero for no match
59 * @since 1.9
60 */
61 default int isMatch(final char[] buffer, final int pos) {
62 return isMatch(buffer, pos, 0, buffer.length);
63 }
64
65 /**
66 * Returns the number of matching characters, {@code 0} if there is no match.
67 * <p>
68 * This method is called to check for a match against a source {@code buffer}. The parameter {@code start}
69 * represents the start position to be checked in the {@code buffer} (a character array which MUST not be changed).
70 * The implementation SHOULD guarantees that {@code start} is a valid index in {@code buffer}.
71 * </p>
72 * <p>
73 * The character array may be larger than the active area to be matched. Only values in the buffer between the
74 * specified indices may be accessed, in other words: {@code bufferStart <= start < bufferEnd}.
75 * </p>
76 * <p>
77 * The matching code may check one character or many. It may check characters preceding {@code start} as well as
78 * those after, so long as no checks exceed the bounds specified.
79 * </p>
80 * <p>
81 * It must return zero for no match, or a positive number if a match was found. The number indicates the number of
82 * characters that matched.
83 * </p>
84 *
85 * @param buffer the source text to search, do not change.
86 * @param start the starting position for the match, valid in {@code buffer}.
87 * @param bufferStart the first active index in the buffer, valid in {@code buffer}.
88 * @param bufferEnd the end index (exclusive) of the active buffer, valid in {@code buffer}.
89 * @return The number of matching characters, zero if there is no match.
90 */
91 int isMatch(char[] buffer, int start, int bufferStart, int bufferEnd);
92
93 /**
94 * Returns the number of matching characters, zero for no match.
95 * <p>
96 * This method is called to check for a match. The parameter {@code pos} represents the current position to be
97 * checked in the string {@code buffer} (a character array which must not be changed). The API guarantees that
98 * {@code pos} is a valid index for {@code buffer}.
99 * </p>
100 * <p>
101 * The matching code may check one character or many. It may check characters preceding {@code pos} as well as those
102 * after.
103 * </p>
104 * <p>
105 * It must return zero for no match, or a positive number if a match was found. The number indicates the number of
106 * characters that matched.
107 * </p>
108 *
109 * @param buffer the text content to match against, do not change
110 * @param pos the starting position for the match, valid for buffer
111 * @return The number of matching characters, zero for no match
112 * @since 1.9
113 */
114 default int isMatch(final CharSequence buffer, final int pos) {
115 return isMatch(buffer, pos, 0, buffer.length());
116 }
117
118 /**
119 * Returns the number of matching characters, {@code 0} if there is no match.
120 * <p>
121 * This method is called to check for a match against a source {@code buffer}. The parameter {@code start}
122 * represents the start position to be checked in the {@code buffer} (a character array which MUST not be changed).
123 * The implementation SHOULD guarantees that {@code start} is a valid index in {@code buffer}.
124 * </p>
125 * <p>
126 * The character array may be larger than the active area to be matched. Only values in the buffer between the
127 * specified indices may be accessed, in other words: {@code bufferStart <= start < bufferEnd}.
128 * </p>
129 * <p>
130 * The matching code may check one character or many. It may check characters preceding {@code start} as well as
131 * those after, so long as no checks exceed the bounds specified.
132 * </p>
133 * <p>
134 * It must return zero for no match, or a positive number if a match was found. The number indicates the number of
135 * characters that matched.
136 * </p>
137 *
138 * @param buffer the source text to search, do not change.
139 * @param start the starting position for the match, valid in {@code buffer}.
140 * @param bufferStart the first active index in the buffer, valid in {@code buffer}.
141 * @param bufferEnd the end index (exclusive) of the active buffer, valid in {@code buffer}.
142 * @return The number of matching characters, zero if there is no match.
143 * @since 1.9
144 */
145 default int isMatch(final CharSequence buffer, final int start, final int bufferStart, final int bufferEnd) {
146 return isMatch(CharSequenceUtils.toCharArray(buffer), start, bufferEnd, bufferEnd);
147 }
148
149 /**
150 * Returns the size of the matching string. Defaults to 0.
151 *
152 * @return the size of the matching string.
153 * @since 1.9
154 */
155 default int size() {
156 return 0;
157 }
158
159 }