/*
 * 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
 * 
 *     https://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 javax.jdo.query;

/**
 * Representation of a string in a query.
 */
public interface StringExpression extends ComparableExpression<String>
{
    /**
     * Method to return an expression for this expression added to the passed expression (String concatenation).
     * @param expr The other expression
     * @return The summation
     */
    StringExpression add(Expression<?> expr);

    /**
     * Method to return an expression for this expression added to the passed string (String concatenation).
     * @param str The other string
     * @return The summation
     */
    StringExpression add(String str);

    /**
     * Method to return an expression for the character at a position of this string expression.
     * @param pos The position
     * @return Expression for the character
     */
    CharacterExpression charAt(int pos);

    /**
     * Method to return an expression for the character at a position of this string expression.
     * @param pos The position
     * @return Expression for the character
     */
    CharacterExpression charAt(NumericExpression<Integer> pos);

    /**
     * Method returning an expression for whether this string expression ends with the passed string expression.
     * @param expr The expression that it ends with.
     * @return Whether it ends with the other string
     */
    BooleanExpression endsWith(StringExpression expr);

    /**
     * Method returning an expression for whether this string expression ends with the passed string expression.
     * @param str The string that it ends with.
     * @return Whether it ends with the other string
     */
    BooleanExpression endsWith(String str);

    /**
     * Method returning an expression for whether this string expression is equal to (ignoring case) the 
     * passed string expression.
     * @param expr The expression
     * @return Whether they are equal
     */
    BooleanExpression equalsIgnoreCase(StringExpression expr);

    /**
     * Method returning an expression for whether this string expression is equal to (ignoring case) the 
     * passed string.
     * @param str The string
     * @return Whether they are equal
     */
    BooleanExpression equalsIgnoreCase(String str);

    /**
     * Method to return an expression for the position of the passed string in this string.
     * @param expr The other string
     * @return Expression for the position of the passed string
     */
    NumericExpression<Integer> indexOf(StringExpression expr);

    /**
     * Method to return an expression for the position of the passed string in this string.
     * @param str The other string
     * @return Expression for the position of the passed string
     */
    NumericExpression<Integer> indexOf(String str);

    /**
     * Method to return an expression for the position of the passed string in this string after a position.
     * @param expr The other string
     * @param pos Start point of the search
     * @return Expression for the position of the passed string
     */
    NumericExpression<Integer> indexOf(StringExpression expr, NumericExpression<Integer> pos);

    /**
     * Method to return an expression for the position of the passed string in this string after a position.
     * @param str The other string
     * @param pos Start point of the search
     * @return Expression for the position of the passed string
     */
    NumericExpression<Integer> indexOf(String str, NumericExpression<Integer> pos);

    /**
     * Method to return an expression for the position of the passed string in this string after a position.
     * @param str The other string
     * @param pos Start point of the search
     * @return Expression for the position of the passed string
     */
    NumericExpression<Integer> indexOf(String str, int pos);

    /**
     * Method to return an expression for the position of the passed string in this string after a position.
     * @param expr The other string
     * @param pos Start point of the search
     * @return Expression for the position of the passed string
     */
    NumericExpression<Integer> indexOf(StringExpression expr, int pos);

    /**
     * Method returning a expression for the length of this string.
     * @return Expression for the length
     */
    NumericExpression<Integer> length();

    /**
     * Method to return an expression for whether this string expression matches the provided expression.
     * @param expr The expression to match against
     * @return Whether this expression matches the provided expression
     */
    BooleanExpression matches(StringExpression expr);

    /**
     * Method to return an expression for whether this string expression matches the provided string.
     * @param str String literal to match against
     * @return Whether this expression matches the provided string
     */
    BooleanExpression matches(String str);

    /**
     * Method returning an expression for whether this string expression starts with the passed string expression.
     * @param expr The expression that it starts with.
     * @return Whether it starts with the other string
     */
    BooleanExpression startsWith(StringExpression expr);

    /**
     * Method returning an expression for whether this string expression starts with the passed string.
     * @param str The string that it starts with.
     * @return Whether it starts with the other string
     */
    BooleanExpression startsWith(String str);

    /**
     * Method returning an expression for whether the substring of this string beginning at the specified
     * index starts with the passed string expression.
     * @param expr The expression that it starts with.
     * @param index where to begin looking in this string
     * @return Whether it starts with the other string
     */
    BooleanExpression startsWith(StringExpression expr, int index);

    /**
     * Method returning an expression for whether the substring of this string beginning at the specified
     * index starts with the passed string.
     * @param str The string that it starts with.
     * @param index where to begin looking in this string
     * @return Whether it starts with the other string
     */
    BooleanExpression startsWith(String str, int index);

    /**
     * Method to return an expression for the substring of this string expression.
     * @param pos The position of the start point of the substring
     * @return Expression for the substring
     */
    StringExpression substring(NumericExpression<Integer> pos);

    /**
     * Method to return an expression for the substring of this string expression.
     * @param pos The position of the start point of the substring
     * @return Expression for the substring
     */
    StringExpression substring(int pos);

    /**
     * Method to return an expression for the substring of this string expression.
     * @param startPos The position of the start point of the substring (inclusive, origin 0)
     * @param endPos The position of the end point of the substring (exclusive, origin 0)
     * @return Expression for the substring
     */
    StringExpression substring(NumericExpression<Integer> startPos, NumericExpression<Integer> endPos);

    /**
     * Method to return an expression for the substring of this string expression.
     * @param startPos The position of the start point of the substring (inclusive, origin 0)
     * @param endPos The position of the end point of the substring (exclusive, origin 0)
     * @return Expression for the substring
     */
    StringExpression substring(int startPos, int endPos);

    /**
     * Method to return a StringExpression representing this string expression in lower case.
     * @return The lower case expression
     */
    StringExpression toLowerCase();

    /**
     * Method to return a StringExpression representing this string expression in upper case.
     * @return The upper case expression
     */
    StringExpression toUpperCase();

    /**
     * Method returning a string expression with whitespace trimmed from start and end.
     * @return String expression with whitespace trimmed
     */
    StringExpression trim();
}