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.logging.log4j.util;
018
019import java.util.Locale;
020
021/**
022 * <em>Consider this class private.</em>
023 * 
024 * @see <a href="http://commons.apache.org/proper/commons-lang/">Apache Commons Lang</a>
025 */
026public final class Strings {
027
028    /**
029     * The empty string.
030     */
031    public static final String EMPTY = "";
032
033    private Strings() {
034        // empty
035    }
036
037    /**
038     * Returns a double quoted string.
039     * 
040     * @param str a String
041     * @return {@code "str"}
042     */
043    public static String dquote(final String str) {
044        return Chars.DQUOTE + str + Chars.DQUOTE;
045    }
046
047    /**
048     * Checks if a String is blank. A blank string is one that is {@code null}, empty, or when trimmed using
049     * {@link String#trim()} is empty.
050     *
051     * @param s the String to check, may be {@code null}
052     * @return {@code true} if the String is {@code null}, empty, or trims to empty.
053     */
054    public static boolean isBlank(final String s) {
055        return s == null || s.trim().isEmpty();
056    }
057
058    /**
059     * <p>
060     * Checks if a CharSequence is empty ("") or null.
061     * </p>
062     *
063     * <pre>
064     * Strings.isEmpty(null)      = true
065     * Strings.isEmpty("")        = true
066     * Strings.isEmpty(" ")       = false
067     * Strings.isEmpty("bob")     = false
068     * Strings.isEmpty("  bob  ") = false
069     * </pre>
070     *
071     * <p>
072     * NOTE: This method changed in Lang version 2.0. It no longer trims the CharSequence. That functionality is
073     * available in isBlank().
074     * </p>
075     *
076     * <p>
077     * Copied from Apache Commons Lang org.apache.commons.lang3.StringUtils.isEmpty(CharSequence)
078     * </p>
079     *
080     * @param cs the CharSequence to check, may be null
081     * @return {@code true} if the CharSequence is empty or null
082     */
083    public static boolean isEmpty(final CharSequence cs) {
084        return cs == null || cs.length() == 0;
085    }
086
087    /**
088     * Checks if a String is not blank. The opposite of {@link #isBlank(String)}.
089     *
090     * @param s the String to check, may be {@code null}
091     * @return {@code true} if the String is non-{@code null} and has content after being trimmed.
092     */
093    public static boolean isNotBlank(final String s) {
094        return !isBlank(s);
095    }
096
097    /**
098     * <p>
099     * Checks if a CharSequence is not empty ("") and not null.
100     * </p>
101     *
102     * <pre>
103     * Strings.isNotEmpty(null)      = false
104     * Strings.isNotEmpty("")        = false
105     * Strings.isNotEmpty(" ")       = true
106     * Strings.isNotEmpty("bob")     = true
107     * Strings.isNotEmpty("  bob  ") = true
108     * </pre>
109     *
110     * <p>
111     * Copied from Apache Commons Lang org.apache.commons.lang3.StringUtils.isNotEmpty(CharSequence)
112     * </p>
113     *
114     * @param cs the CharSequence to check, may be null
115     * @return {@code true} if the CharSequence is not empty and not null
116     */
117    public static boolean isNotEmpty(final CharSequence cs) {
118        return !isEmpty(cs);
119    }
120
121    /**
122     * Returns a quoted string.
123     * 
124     * @param str a String
125     * @return {@code 'str'}
126     */
127    public static String quote(final String str) {
128        return Chars.QUOTE + str + Chars.QUOTE;
129    }
130
131    /**
132     * Shorthand for {@code str.toUpperCase(Locale.ROOT);}
133     * @param str The string to upper case.
134     * @return a new string
135     * @see String#toLowerCase(Locale)
136     */
137    public String toRootUpperCase(final String str) {
138        return str.toUpperCase(Locale.ROOT);
139    }
140    
141    /**
142     * <p>
143     * Removes control characters (char &lt;= 32) from both ends of this String returning {@code null} if the String is
144     * empty ("") after the trim or if it is {@code null}.
145     *
146     * <p>
147     * The String is trimmed using {@link String#trim()}. Trim removes start and end characters &lt;= 32.
148     * </p>
149     *
150     * <pre>
151     * Strings.trimToNull(null)          = null
152     * Strings.trimToNull("")            = null
153     * Strings.trimToNull("     ")       = null
154     * Strings.trimToNull("abc")         = "abc"
155     * Strings.trimToNull("    abc    ") = "abc"
156     * </pre>
157     *
158     * <p>
159     * Copied from Apache Commons Lang org.apache.commons.lang3.StringUtils.trimToNull(String)
160     * </p>
161     *
162     * @param str the String to be trimmed, may be null
163     * @return the trimmed String, {@code null} if only chars &lt;= 32, empty or null String input
164     */
165    public static String trimToNull(final String str) {
166        final String ts = str == null ? null : str.trim();
167        return isEmpty(ts) ? null : ts;
168    }
169}