001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.text.matcher;
019
020import org.apache.commons.lang3.CharSequenceUtils;
021
022/**
023 * Determines if a character array portion matches.
024 *
025 * @since 1.3
026 */
027public interface StringMatcher {
028
029    /**
030     * Returns a matcher that matches this matcher followed by the given matcher.
031     *
032     * @param stringMatcher the next matcher.
033     * @return a matcher that matches this matcher followed by the given matcher.
034     * @since 1.9
035     */
036    default StringMatcher andThen(final StringMatcher stringMatcher) {
037        return StringMatcherFactory.INSTANCE.andMatcher(this, stringMatcher);
038    }
039
040    /**
041     * Returns the number of matching characters, zero for no match.
042     * <p>
043     * This method is called to check for a match. The parameter {@code pos} represents the current position to be
044     * checked in the string {@code buffer} (a character array which must not be changed). The API guarantees that
045     * {@code pos} is a valid index for {@code buffer}.
046     * </p>
047     * <p>
048     * The matching code may check one character or many. It may check characters preceding {@code pos} as well as those
049     * after.
050     * </p>
051     * <p>
052     * It must return zero for no match, or a positive number if a match was found. The number indicates the number of
053     * characters that matched.
054     * </p>
055     *
056     * @param buffer the text content to match against, do not change
057     * @param pos the starting position for the match, valid for buffer
058     * @return The number of matching characters, zero for no match
059     * @since 1.9
060     */
061    default int isMatch(final char[] buffer, final int pos) {
062        return isMatch(buffer, pos, 0, buffer.length);
063    }
064
065    /**
066     * Returns the number of matching characters, {@code 0} if there is no match.
067     * <p>
068     * This method is called to check for a match against a source {@code buffer}. The parameter {@code start}
069     * represents the start position to be checked in the {@code buffer} (a character array which MUST not be changed).
070     * The implementation SHOULD guarantees that {@code start} is a valid index in {@code buffer}.
071     * </p>
072     * <p>
073     * The character array may be larger than the active area to be matched. Only values in the buffer between the
074     * specified indices may be accessed, in other words: {@code bufferStart <= start < bufferEnd}.
075     * </p>
076     * <p>
077     * The matching code may check one character or many. It may check characters preceding {@code start} as well as
078     * those after, so long as no checks exceed the bounds specified.
079     * </p>
080     * <p>
081     * It must return zero for no match, or a positive number if a match was found. The number indicates the number of
082     * characters that matched.
083     * </p>
084     *
085     * @param buffer the source text to search, do not change.
086     * @param start the starting position for the match, valid in {@code buffer}.
087     * @param bufferStart the first active index in the buffer, valid in {@code buffer}.
088     * @param bufferEnd the end index (exclusive) of the active buffer, valid in {@code buffer}.
089     * @return The number of matching characters, zero if there is no match.
090     */
091    int isMatch(char[] buffer, int start, int bufferStart, int bufferEnd);
092
093    /**
094     * Returns the number of matching characters, zero for no match.
095     * <p>
096     * This method is called to check for a match. The parameter {@code pos} represents the current position to be
097     * checked in the string {@code buffer} (a character array which must not be changed). The API guarantees that
098     * {@code pos} is a valid index for {@code buffer}.
099     * </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}