Source code

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 */
017package org.apache.commons.io;
018
019import java.util.Objects;
020import java.util.stream.Stream;
021
022/**
023 * Enumeration of IO case sensitivity.
024 * <p>
025 * Different filing systems have different rules for case-sensitivity.
026 * Windows is case-insensitive, UNIX is case-sensitive.
027 * </p>
028 * <p>
029 * This class captures that difference, providing an enumeration to
030 * control how file name comparisons should be performed. It also provides
031 * methods that use the enumeration to perform comparisons.
032 * </p>
033 * <p>
034 * Wherever possible, you should use the {@code check} methods in this
035 * class to compare file names.
036 * </p>
037 *
038 * @since 1.3
039 */
040public enum IOCase {
041
042    /**
043     * The constant for case-sensitive regardless of operating system.
044     */
045    SENSITIVE("Sensitive", true),
046
047    /**
048     * The constant for case-insensitive regardless of operating system.
049     */
050    INSENSITIVE("Insensitive", false),
051
052    /**
053     * The constant for case sensitivity determined by the current operating system.
054     * Windows is case-insensitive when comparing file names, UNIX is case-sensitive.
055     * <p>
056     * <strong>Note:</strong> This only caters for Windows and Unix. Other operating
057     * systems (e.g. OSX and OpenVMS) are treated as case-sensitive if they use the
058     * UNIX file separator and case-insensitive if they use the Windows file separator
059     * (see {@link java.io.File#separatorChar}).
060     * </p>
061     * <p>
062     * If you serialize this constant on Windows, and deserialize on Unix, or vice
063     * versa, then the value of the case-sensitivity flag will change.
064     * </p>
065     */
066    SYSTEM("System", FileSystem.getCurrent().isCaseSensitive());
067
068    /** Serialization version. */
069    private static final long serialVersionUID = -6343169151696340687L;
070
071    /**
072     * Looks up an IOCase by name.
073     *
074     * @param name  the name to find
075     * @return the IOCase object
076     * @throws IllegalArgumentException if the name is invalid
077     */
078    public static IOCase forName(final String name) {
079        return Stream.of(IOCase.values()).filter(ioCase -> ioCase.getName().equals(name)).findFirst()
080                .orElseThrow(() -> new IllegalArgumentException("Illegal IOCase name: " + name));
081    }
082
083    /**
084     * Tests for cases sensitivity in a null-safe manner.
085     *
086     * @param ioCase an IOCase.
087     * @return true if the input is non-null and {@link #isCaseSensitive()}.
088     * @since 2.10.0
089     */
090    public static boolean isCaseSensitive(final IOCase ioCase) {
091        return ioCase != null && ioCase.isCaseSensitive();
092    }
093
094    /**
095     * Returns the given value if not-null, the defaultValue if null.
096     *
097     * @param value the value to test.
098     * @param defaultValue the default value.
099     * @return the given value if not-null, the defaultValue if null.
100     * @since 2.12.0
101     */
102    public static IOCase value(final IOCase value, final IOCase defaultValue) {
103        return value != null ? value : defaultValue;
104    }
105
106    /** The enumeration name. */
107    private final String name;
108
109    /** The sensitivity flag. */
110    private final transient boolean sensitive;
111
112    /**
113     * Constructs a new instance.
114     *
115     * @param name  the name.
116     * @param sensitive  the sensitivity.
117     */
118    IOCase(final String name, final boolean sensitive) {
119        this.name = name;
120        this.sensitive = sensitive;
121    }
122
123    /**
124     * Compares two strings using the case-sensitivity rule.
125     * <p>
126     * This method mimics {@link String#compareTo} but takes case-sensitivity
127     * into account.
128     * </p>
129     *
130     * @param str1  the first string to compare, not null.
131     * @param str2  the second string to compare, not null.
132     * @return true if equal using the case rules.
133     * @throws NullPointerException if either string is null.
134     */
135    public int checkCompareTo(final String str1, final String str2) {
136        Objects.requireNonNull(str1, "str1");
137        Objects.requireNonNull(str2, "str2");
138        return sensitive ? str1.compareTo(str2) : str1.compareToIgnoreCase(str2);
139    }
140
141    /**
142     * Checks if one string ends with another using the case-sensitivity rule.
143     * <p>
144     * This method mimics {@link String#endsWith} but takes case-sensitivity
145     * into account.
146     * </p>
147     *
148     * @param str  the string to check.
149     * @param end  the end to compare against.
150     * @return true if equal using the case rules, false if either input is null.
151     */
152    public boolean checkEndsWith(final String str, final String end) {
153        if (str == null || end == null) {
154            return false;
155        }
156        final int endLen = end.length();
157        return str.regionMatches(!sensitive, str.length() - endLen, end, 0, endLen);
158    }
159
160    /**
161     * Compares two strings using the case-sensitivity rule.
162     * <p>
163     * This method mimics {@link String#equals} but takes case-sensitivity
164     * into account.
165     * </p>
166     *
167     * @param str1  the first string to compare.
168     * @param str2  the second string to compare.
169     * @return true if equal using the case rules.
170     */
171    public boolean checkEquals(final String str1, final String str2) {
172        return str1 == str2 || str1 != null && (sensitive ? str1.equals(str2) : str1.equalsIgnoreCase(str2));
173    }
174
175    /**
176     * Checks if one string contains another starting at a specific index using the
177     * case-sensitivity rule.
178     * <p>
179     * This method mimics parts of {@link String#indexOf(String, int)}
180     * but takes case-sensitivity into account.
181     * </p>
182     *
183     * @param str  the string to check.
184     * @param strStartIndex  the index to start at in str.
185     * @param search  the start to search for.
186     * @return the first index of the search String,
187     *  -1 if no match or {@code null} string input.
188     * @since 2.0
189     */
190    public int checkIndexOf(final String str, final int strStartIndex, final String search) {
191        if (str != null && search != null) {
192            final int endIndex = str.length() - search.length();
193            if (endIndex >= strStartIndex) {
194                for (int i = strStartIndex; i <= endIndex; i++) {
195                    if (checkRegionMatches(str, i, search)) {
196                        return i;
197                    }
198                }
199            }
200        }
201        return -1;
202    }
203
204    /**
205     * Checks if one string contains another at a specific index using the case-sensitivity rule.
206     * <p>
207     * This method mimics parts of {@link String#regionMatches(boolean, int, String, int, int)}
208     * but takes case-sensitivity into account.
209     * </p>
210     *
211     * @param str  the string to check.
212     * @param strStartIndex  the index to start at in str.
213     * @param search  the start to search for,.
214     * @return true if equal using the case rules.
215     */
216    public boolean checkRegionMatches(final String str, final int strStartIndex, final String search) {
217        return str != null && search != null && str.regionMatches(!sensitive, strStartIndex, search, 0, search.length());
218    }
219
220    /**
221     * Checks if one string starts with another using the case-sensitivity rule.
222     * <p>
223     * This method mimics {@link String#startsWith(String)} but takes case-sensitivity
224     * into account.
225     * </p>
226     *
227     * @param str  the string to check.
228     * @param start  the start to compare against.
229     * @return true if equal using the case rules, false if either input is null.
230     */
231    public boolean checkStartsWith(final String str, final String start) {
232        return str != null && start != null && str.regionMatches(!sensitive, 0, start, 0, start.length());
233    }
234
235    /**
236     * Gets the name of the constant.
237     *
238     * @return the name of the constant
239     */
240    public String getName() {
241        return name;
242    }
243
244    /**
245     * Does the object represent case-sensitive comparison.
246     *
247     * @return true if case-sensitive.
248     */
249    public boolean isCaseSensitive() {
250        return sensitive;
251    }
252
253    /**
254     * Replaces the enumeration from the stream with a real one.
255     * This ensures that the correct flag is set for SYSTEM.
256     *
257     * @return the resolved object.
258     */
259    private Object readResolve() {
260        return forName(name);
261    }
262
263    /**
264     * Gets a string describing the sensitivity.
265     *
266     * @return a string describing the sensitivity.
267     */
268    @Override
269    public String toString() {
270        return name;
271    }
272
273}