/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.lang3.text;

import java.util.Arrays;

import org.apache.commons.lang3.StringUtils;

A matcher class that can be queried to determine if a character array
portion matches.

This class comes complete with various factory methods.
If these do not suffice, you can subclass and implement your own matcher.
Since:
2.2
Deprecated:
as of 3.6, use commons-text

StringMatcherFactory instead/**
 * A matcher class that can be queried to determine if a character array
 * portion matches.
 * <p>
 * This class comes complete with various factory methods.
 * If these do not suffice, you can subclass and implement your own matcher.
 *
 * @since 2.2
 * @deprecated as of 3.6, use commons-text
 * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/StringMatcherFactory.html">
 * StringMatcherFactory</a> instead
 */
@Deprecated
public abstract class StrMatcher {

    
Matches the comma character.
/**
     * Matches the comma character.
     */
    private static final StrMatcher COMMA_MATCHER = new CharMatcher(',');
    
Matches the tab character.
/**
     * Matches the tab character.
     */
    private static final StrMatcher TAB_MATCHER = new CharMatcher('\t');
    
Matches the space character.
/**
     * Matches the space character.
     */
    private static final StrMatcher SPACE_MATCHER = new CharMatcher(' ');
    
Matches the same characters as StringTokenizer,
namely space, tab, newline, formfeed.
/**
     * Matches the same characters as StringTokenizer,
     * namely space, tab, newline, formfeed.
     */
    private static final StrMatcher SPLIT_MATCHER = new CharSetMatcher(" \t\n\r\f".toCharArray());
    
Matches the String trim() whitespace characters.
/**
     * Matches the String trim() whitespace characters.
     */
    private static final StrMatcher TRIM_MATCHER = new TrimMatcher();
    
Matches the double quote character.
/**
     * Matches the double quote character.
     */
    private static final StrMatcher SINGLE_QUOTE_MATCHER = new CharMatcher('\'');
    
Matches the double quote character.
/**
     * Matches the double quote character.
     */
    private static final StrMatcher DOUBLE_QUOTE_MATCHER = new CharMatcher('"');
    
Matches the single or double quote character.
/**
     * Matches the single or double quote character.
     */
    private static final StrMatcher QUOTE_MATCHER = new CharSetMatcher("'\"".toCharArray());
    
Matches no characters.
/**
     * Matches no characters.
     */
    private static final StrMatcher NONE_MATCHER = new NoMatcher();

    // -----------------------------------------------------------------------

    
Returns a matcher which matches the comma character.
Returns:
a matcher for a comma/**
     * Returns a matcher which matches the comma character.
     *
     * @return a matcher for a comma
     */
    public static StrMatcher commaMatcher() {
        return COMMA_MATCHER;
    }

    
Returns a matcher which matches the tab character.
Returns:
a matcher for a tab/**
     * Returns a matcher which matches the tab character.
     *
     * @return a matcher for a tab
     */
    public static StrMatcher tabMatcher() {
        return TAB_MATCHER;
    }

    
Returns a matcher which matches the space character.
Returns:
a matcher for a space/**
     * Returns a matcher which matches the space character.
     *
     * @return a matcher for a space
     */
    public static StrMatcher spaceMatcher() {
        return SPACE_MATCHER;
    }

    
Matches the same characters as StringTokenizer,
namely space, tab, newline and formfeed.
Returns:
the split matcher/**
     * Matches the same characters as StringTokenizer,
     * namely space, tab, newline and formfeed.
     *
     * @return the split matcher
     */
    public static StrMatcher splitMatcher() {
        return SPLIT_MATCHER;
    }

    
Matches the String trim() whitespace characters.
Returns:
the trim matcher/**
     * Matches the String trim() whitespace characters.
     *
     * @return the trim matcher
     */
    public static StrMatcher trimMatcher() {
        return TRIM_MATCHER;
    }

    
Returns a matcher which matches the single quote character.
Returns:
a matcher for a single quote/**
     * Returns a matcher which matches the single quote character.
     *
     * @return a matcher for a single quote
     */
    public static StrMatcher singleQuoteMatcher() {
        return SINGLE_QUOTE_MATCHER;
    }

    
Returns a matcher which matches the double quote character.
Returns:
a matcher for a double quote/**
     * Returns a matcher which matches the double quote character.
     *
     * @return a matcher for a double quote
     */
    public static StrMatcher doubleQuoteMatcher() {
        return DOUBLE_QUOTE_MATCHER;
    }

    
Returns a matcher which matches the single or double quote character.
Returns:
a matcher for a single or double quote/**
     * Returns a matcher which matches the single or double quote character.
     *
     * @return a matcher for a single or double quote
     */
    public static StrMatcher quoteMatcher() {
        return QUOTE_MATCHER;
    }

    
Matches no characters.
Returns:
a matcher that matches nothing/**
     * Matches no characters.
     *
     * @return a matcher that matches nothing
     */
    public static StrMatcher noneMatcher() {
        return NONE_MATCHER;
    }

    
Constructor that creates a matcher from a character.
Params:
ch –  the character to match, must not be null
Returns:
a new Matcher for the given char/**
     * Constructor that creates a matcher from a character.
     *
     * @param ch  the character to match, must not be null
     * @return a new Matcher for the given char
     */
    public static StrMatcher charMatcher(final char ch) {
        return new CharMatcher(ch);
    }

    
Constructor that creates a matcher from a set of characters.
Params:
chars –  the characters to match, null or empty matches nothing
Returns:
a new matcher for the given char[]/**
     * Constructor that creates a matcher from a set of characters.
     *
     * @param chars  the characters to match, null or empty matches nothing
     * @return a new matcher for the given char[]
     */
    public static StrMatcher charSetMatcher(final char... chars) {
        if (chars == null || chars.length == 0) {
            return NONE_MATCHER;
        }
        if (chars.length == 1) {
            return new CharMatcher(chars[0]);
        }
        return new CharSetMatcher(chars);
    }

    
Constructor that creates a matcher from a string representing a set of characters.
Params:
chars –  the characters to match, null or empty matches nothing
Returns:
a new Matcher for the given characters/**
     * Constructor that creates a matcher from a string representing a set of characters.
     *
     * @param chars  the characters to match, null or empty matches nothing
     * @return a new Matcher for the given characters
     */
    public static StrMatcher charSetMatcher(final String chars) {
        if (StringUtils.isEmpty(chars)) {
            return NONE_MATCHER;
        }
        if (chars.length() == 1) {
            return new CharMatcher(chars.charAt(0));
        }
        return new CharSetMatcher(chars.toCharArray());
    }

    
Constructor that creates a matcher from a string.
Params:
str –  the string to match, null or empty matches nothing
Returns:
a new Matcher for the given String/**
     * Constructor that creates a matcher from a string.
     *
     * @param str  the string to match, null or empty matches nothing
     * @return a new Matcher for the given String
     */
    public static StrMatcher stringMatcher(final String str) {
        if (StringUtils.isEmpty(str)) {
            return NONE_MATCHER;
        }
        return new StringMatcher(str);
    }

    //-----------------------------------------------------------------------
    
Constructor.
/**
     * Constructor.
     */
    protected StrMatcher() {
        super();
    }

    
Returns the number of matching characters, zero for no match.
 This method is called to check for a match. The parameter pos represents the current position to be checked in the string buffer (a character array which must not be changed). The API guarantees that pos is a valid index for buffer. 

The character array may be larger than the active area to be matched.
Only values in the buffer between the specified indices may be accessed.
 The matching code may check one character or many. It may check characters preceding pos as well as those after, so long as no checks exceed the bounds specified. 

It must return zero for no match, or a positive number if a match was found.
The number indicates the number of characters that matched.
Params:
buffer –  the text content to match against, do not change
pos –  the starting position for the match, valid for buffer
bufferStart –  the first active index in the buffer, valid for buffer
bufferEnd –  the end index (exclusive) of the active buffer, valid for buffer
Returns:
the number of matching characters, zero for no match/**
     * Returns the number of matching characters, zero for no match.
     * <p>
     * This method is called to check for a match.
     * The parameter {@code pos} represents the current position to be
     * checked in the string {@code buffer} (a character array which must
     * not be changed).
     * The API guarantees that {@code pos} is a valid index for {@code buffer}.
     * <p>
     * The character array may be larger than the active area to be matched.
     * Only values in the buffer between the specified indices may be accessed.
     * <p>
     * The matching code may check one character or many.
     * It may check characters preceding {@code pos} as well as those
     * after, so long as no checks exceed the bounds specified.
     * <p>
     * It must return zero for no match, or a positive number if a match was found.
     * The number indicates the number of characters that matched.
     *
     * @param buffer  the text content to match against, do not change
     * @param pos  the starting position for the match, valid for buffer
     * @param bufferStart  the first active index in the buffer, valid for buffer
     * @param bufferEnd  the end index (exclusive) of the active buffer, valid for buffer
     * @return the number of matching characters, zero for no match
     */
    public abstract int isMatch(char[] buffer, int pos, int bufferStart, int bufferEnd);

    
Returns the number of matching characters, zero for no match.
 This method is called to check for a match. The parameter pos represents the current position to be checked in the string buffer (a character array which must not be changed). The API guarantees that pos is a valid index for buffer. 
 The matching code may check one character or many. It may check characters preceding pos as well as those after. 

It must return zero for no match, or a positive number if a match was found.
The number indicates the number of characters that matched.
Params:
buffer –  the text content to match against, do not change
pos –  the starting position for the match, valid for buffer
Returns:
the number of matching characters, zero for no match
Since:
2.4/**
     * Returns the number of matching characters, zero for no match.
     * <p>
     * This method is called to check for a match.
     * The parameter {@code pos} represents the current position to be
     * checked in the string {@code buffer} (a character array which must
     * not be changed).
     * The API guarantees that {@code pos} is a valid index for {@code buffer}.
     * <p>
     * The matching code may check one character or many.
     * It may check characters preceding {@code pos} as well as those after.
     * <p>
     * It must return zero for no match, or a positive number if a match was found.
     * The number indicates the number of characters that matched.
     *
     * @param buffer  the text content to match against, do not change
     * @param pos  the starting position for the match, valid for buffer
     * @return the number of matching characters, zero for no match
     * @since 2.4
     */
    public int isMatch(final char[] buffer, final int pos) {
        return isMatch(buffer, pos, 0, buffer.length);
    }

    //-----------------------------------------------------------------------
    
Class used to define a set of characters for matching purposes.
/**
     * Class used to define a set of characters for matching purposes.
     */
    static final class CharSetMatcher extends StrMatcher {
        
The set of characters to match. /** The set of characters to match. */
        private final char[] chars;

        
Constructor that creates a matcher from a character array.
Params:
chars –  the characters to match, must not be null/**
         * Constructor that creates a matcher from a character array.
         *
         * @param chars  the characters to match, must not be null
         */
        CharSetMatcher(final char[] chars) {
            super();
            this.chars = chars.clone();
            Arrays.sort(this.chars);
        }

        
Returns whether or not the given character matches.
Params:
buffer –  the text content to match against, do not change
pos –  the starting position for the match, valid for buffer
bufferStart –  the first active index in the buffer, valid for buffer
bufferEnd –  the end index of the active buffer, valid for buffer
Returns:
the number of matching characters, zero for no match/**
         * Returns whether or not the given character matches.
         *
         * @param buffer  the text content to match against, do not change
         * @param pos  the starting position for the match, valid for buffer
         * @param bufferStart  the first active index in the buffer, valid for buffer
         * @param bufferEnd  the end index of the active buffer, valid for buffer
         * @return the number of matching characters, zero for no match
         */
        @Override
        public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
            return Arrays.binarySearch(chars, buffer[pos]) >= 0 ? 1 : 0;
        }
    }

    //-----------------------------------------------------------------------
    
Class used to define a character for matching purposes.
/**
     * Class used to define a character for matching purposes.
     */
    static final class CharMatcher extends StrMatcher {
        
The character to match. /** The character to match. */
        private final char ch;

        
Constructor that creates a matcher that matches a single character.
Params:
ch –  the character to match/**
         * Constructor that creates a matcher that matches a single character.
         *
         * @param ch  the character to match
         */
        CharMatcher(final char ch) {
            super();
            this.ch = ch;
        }

        
Returns whether or not the given character matches.
Params:
buffer –  the text content to match against, do not change
pos –  the starting position for the match, valid for buffer
bufferStart –  the first active index in the buffer, valid for buffer
bufferEnd –  the end index of the active buffer, valid for buffer
Returns:
the number of matching characters, zero for no match/**
         * Returns whether or not the given character matches.
         *
         * @param buffer  the text content to match against, do not change
         * @param pos  the starting position for the match, valid for buffer
         * @param bufferStart  the first active index in the buffer, valid for buffer
         * @param bufferEnd  the end index of the active buffer, valid for buffer
         * @return the number of matching characters, zero for no match
         */
        @Override
        public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
            return ch == buffer[pos] ? 1 : 0;
        }
    }

    //-----------------------------------------------------------------------
    
Class used to define a set of characters for matching purposes.
/**
     * Class used to define a set of characters for matching purposes.
     */
    static final class StringMatcher extends StrMatcher {
        
The string to match, as a character array. /** The string to match, as a character array. */
        private final char[] chars;

        
Constructor that creates a matcher from a String.
Params:
str –  the string to match, must not be null/**
         * Constructor that creates a matcher from a String.
         *
         * @param str  the string to match, must not be null
         */
        StringMatcher(final String str) {
            super();
            chars = str.toCharArray();
        }

        
Returns whether or not the given text matches the stored string.
Params:
buffer –  the text content to match against, do not change
pos –  the starting position for the match, valid for buffer
bufferStart –  the first active index in the buffer, valid for buffer
bufferEnd –  the end index of the active buffer, valid for buffer
Returns:
the number of matching characters, zero for no match/**
         * Returns whether or not the given text matches the stored string.
         *
         * @param buffer  the text content to match against, do not change
         * @param pos  the starting position for the match, valid for buffer
         * @param bufferStart  the first active index in the buffer, valid for buffer
         * @param bufferEnd  the end index of the active buffer, valid for buffer
         * @return the number of matching characters, zero for no match
         */
        @Override
        public int isMatch(final char[] buffer, int pos, final int bufferStart, final int bufferEnd) {
            final int len = chars.length;
            if (pos + len > bufferEnd) {
                return 0;
            }
            for (int i = 0; i < chars.length; i++, pos++) {
                if (chars[i] != buffer[pos]) {
                    return 0;
                }
            }
            return len;
        }

        @Override
        public String toString() {
            return super.toString() + ' ' + Arrays.toString(chars);
        }

    }

    //-----------------------------------------------------------------------
    
Class used to match no characters.
/**
     * Class used to match no characters.
     */
    static final class NoMatcher extends StrMatcher {

        
Constructs a new instance of NoMatcher. /**
         * Constructs a new instance of {@code NoMatcher}.
         */
        NoMatcher() {
            super();
        }

        
Always returns false. 
Params:
buffer –  the text content to match against, do not change
pos –  the starting position for the match, valid for buffer
bufferStart –  the first active index in the buffer, valid for buffer
bufferEnd –  the end index of the active buffer, valid for buffer
Returns:
the number of matching characters, zero for no match/**
         * Always returns {@code false}.
         *
         * @param buffer  the text content to match against, do not change
         * @param pos  the starting position for the match, valid for buffer
         * @param bufferStart  the first active index in the buffer, valid for buffer
         * @param bufferEnd  the end index of the active buffer, valid for buffer
         * @return the number of matching characters, zero for no match
         */
        @Override
        public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
            return 0;
        }
    }

    //-----------------------------------------------------------------------
    
Class used to match whitespace as per trim().
/**
     * Class used to match whitespace as per trim().
     */
    static final class TrimMatcher extends StrMatcher {

        
Constructs a new instance of TrimMatcher. /**
         * Constructs a new instance of {@code TrimMatcher}.
         */
        TrimMatcher() {
            super();
        }

        
Returns whether or not the given character matches.
Params:
buffer –  the text content to match against, do not change
pos –  the starting position for the match, valid for buffer
bufferStart –  the first active index in the buffer, valid for buffer
bufferEnd –  the end index of the active buffer, valid for buffer
Returns:
the number of matching characters, zero for no match/**
         * Returns whether or not the given character matches.
         *
         * @param buffer  the text content to match against, do not change
         * @param pos  the starting position for the match, valid for buffer
         * @param bufferStart  the first active index in the buffer, valid for buffer
         * @param bufferEnd  the end index of the active buffer, valid for buffer
         * @return the number of matching characters, zero for no match
         */
        @Override
        public int isMatch(final char[] buffer, final int pos, final int bufferStart, final int bufferEnd) {
            return buffer[pos] <= 32 ? 1 : 0;
        }
    }

}