View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements. See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache license, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License. You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the license for the specific language governing permissions and
15   * limitations under the license.
16   */
17  package org.apache.logging.log4j.util;
18  
19  import java.util.Iterator;
20  import java.util.Locale;
21  import java.util.Objects;
22  
23  /**
24   * <em>Consider this class private.</em>
25   * 
26   * @see <a href="http://commons.apache.org/proper/commons-lang/">Apache Commons Lang</a>
27   */
28  public final class Strings {
29  
30      /**
31       * The empty string.
32       */
33      public static final String EMPTY = "";
34      
35      /**
36       * OS-dependent line separator, defaults to {@code "\n"} if the system property {@code ""line.separator"} cannot be
37       * read.
38       */
39      public static final String LINE_SEPARATOR = PropertiesUtil.getProperties().getStringProperty("line.separator",
40              "\n");
41  
42      private Strings() {
43          // empty
44      }
45  
46      /**
47       * Returns a double quoted string.
48       * 
49       * @param str a String
50       * @return {@code "str"}
51       */
52      public static String dquote(final String str) {
53          return Chars.DQUOTE + str + Chars.DQUOTE;
54      }
55  
56      /**
57       * Checks if a String is blank. A blank string is one that is {@code null}, empty, or when trimmed using
58       * {@link String#trim()} is empty.
59       *
60       * @param s the String to check, may be {@code null}
61       * @return {@code true} if the String is {@code null}, empty, or trims to empty.
62       */
63      public static boolean isBlank(final String s) {
64          return s == null || s.trim().isEmpty();
65      }
66  
67      /**
68       * <p>
69       * Checks if a CharSequence is empty ("") or null.
70       * </p>
71       *
72       * <pre>
73       * Strings.isEmpty(null)      = true
74       * Strings.isEmpty("")        = true
75       * Strings.isEmpty(" ")       = false
76       * Strings.isEmpty("bob")     = false
77       * Strings.isEmpty("  bob  ") = false
78       * </pre>
79       *
80       * <p>
81       * NOTE: This method changed in Lang version 2.0. It no longer trims the CharSequence. That functionality is
82       * available in isBlank().
83       * </p>
84       *
85       * <p>
86       * Copied from Apache Commons Lang org.apache.commons.lang3.StringUtils.isEmpty(CharSequence)
87       * </p>
88       *
89       * @param cs the CharSequence to check, may be null
90       * @return {@code true} if the CharSequence is empty or null
91       */
92      public static boolean isEmpty(final CharSequence cs) {
93          return cs == null || cs.length() == 0;
94      }
95  
96      /**
97       * Checks if a String is not blank. The opposite of {@link #isBlank(String)}.
98       *
99       * @param s the String to check, may be {@code null}
100      * @return {@code true} if the String is non-{@code null} and has content after being trimmed.
101      */
102     public static boolean isNotBlank(final String s) {
103         return !isBlank(s);
104     }
105 
106     /**
107      * <p>
108      * Checks if a CharSequence is not empty ("") and not null.
109      * </p>
110      *
111      * <pre>
112      * Strings.isNotEmpty(null)      = false
113      * Strings.isNotEmpty("")        = false
114      * Strings.isNotEmpty(" ")       = true
115      * Strings.isNotEmpty("bob")     = true
116      * Strings.isNotEmpty("  bob  ") = true
117      * </pre>
118      *
119      * <p>
120      * Copied from Apache Commons Lang org.apache.commons.lang3.StringUtils.isNotEmpty(CharSequence)
121      * </p>
122      *
123      * @param cs the CharSequence to check, may be null
124      * @return {@code true} if the CharSequence is not empty and not null
125      */
126     public static boolean isNotEmpty(final CharSequence cs) {
127         return !isEmpty(cs);
128     }
129 
130     /**
131      * Returns a quoted string.
132      * 
133      * @param str a String
134      * @return {@code 'str'}
135      */
136     public static String quote(final String str) {
137         return Chars.QUOTE + str + Chars.QUOTE;
138     }
139 
140     /**
141      * Shorthand for {@code str.toUpperCase(Locale.ROOT);}
142      * @param str The string to upper case.
143      * @return a new string
144      * @see String#toLowerCase(Locale)
145      */
146     public String toRootUpperCase(final String str) {
147         return str.toUpperCase(Locale.ROOT);
148     }
149     
150     /**
151      * <p>
152      * Removes control characters (char &lt;= 32) from both ends of this String returning {@code null} if the String is
153      * empty ("") after the trim or if it is {@code null}.
154      *
155      * <p>
156      * The String is trimmed using {@link String#trim()}. Trim removes start and end characters &lt;= 32.
157      * </p>
158      *
159      * <pre>
160      * Strings.trimToNull(null)          = null
161      * Strings.trimToNull("")            = null
162      * Strings.trimToNull("     ")       = null
163      * Strings.trimToNull("abc")         = "abc"
164      * Strings.trimToNull("    abc    ") = "abc"
165      * </pre>
166      *
167      * <p>
168      * Copied from Apache Commons Lang org.apache.commons.lang3.StringUtils.trimToNull(String)
169      * </p>
170      *
171      * @param str the String to be trimmed, may be null
172      * @return the trimmed String, {@code null} if only chars &lt;= 32, empty or null String input
173      */
174     public static String trimToNull(final String str) {
175         final String ts = str == null ? null : str.trim();
176         return isEmpty(ts) ? null : ts;
177     }
178 
179     /**
180      * <p>Joins the elements of the provided {@code Iterable} into
181      * a single String containing the provided elements.</p>
182      *
183      * <p>No delimiter is added before or after the list. Null objects or empty
184      * strings within the iteration are represented by empty strings.</p>
185      *
186      * @param iterable  the {@code Iterable} providing the values to join together, may be null
187      * @param separator  the separator character to use
188      * @return the joined String, {@code null} if null iterator input
189      */
190     public static String join(final Iterable<?> iterable, final char separator) {
191         if (iterable == null) {
192             return null;
193         }
194         return join(iterable.iterator(), separator);
195     }
196 
197     /**
198      * <p>Joins the elements of the provided {@code Iterator} into
199      * a single String containing the provided elements.</p>
200      *
201      * <p>No delimiter is added before or after the list. Null objects or empty
202      * strings within the iteration are represented by empty strings.</p>
203      *
204      * @param iterator  the {@code Iterator} of values to join together, may be null
205      * @param separator  the separator character to use
206      * @return the joined String, {@code null} if null iterator input
207      */
208     public static String join(final Iterator<?> iterator, final char separator) {
209 
210         // handle null, zero and one elements before building a buffer
211         if (iterator == null) {
212             return null;
213         }
214         if (!iterator.hasNext()) {
215             return EMPTY;
216         }
217         final Object first = iterator.next();
218         if (!iterator.hasNext()) {
219             return Objects.toString(first, EMPTY);
220         }
221 
222         // two or more elements
223         final StringBuilder buf = new StringBuilder(256); // Java default is 16, probably too small
224         if (first != null) {
225             buf.append(first);
226         }
227 
228         while (iterator.hasNext()) {
229             buf.append(separator);
230             final Object obj = iterator.next();
231             if (obj != null) {
232                 buf.append(obj);
233             }
234         }
235 
236         return buf.toString();
237     }
238 
239 }