    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 *      https://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}