Java tutorial
/* * 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.wicket.util.string; import java.text.DecimalFormat; import java.text.DecimalFormatSymbols; import java.text.NumberFormat; import java.text.ParseException; import java.util.Locale; import org.apache.wicket.util.io.IClusterable; import org.apache.wicket.util.lang.Args; import org.apache.wicket.util.lang.Objects; import org.apache.wicket.util.time.Duration; import org.apache.wicket.util.time.Time; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * Holds an immutable String value and optionally a Locale, with methods to convert to various * types. Also provides some handy parsing methods and a variety of static factory methods. * <p> * Objects can be constructed directly from Strings or by using the valueOf() static factory * methods. The repeat() static factory methods provide a way of generating a String value that * repeats a given char or String a number of times. * <p> * Conversions to a wide variety of types can be found in the to*() methods. A generic conversion * can be achieved with to(Class). * <P> * The beforeFirst(), afterFirst(), beforeLast() and afterLast() methods are handy for parsing * things like paths and filenames. * * @author Jonathan Locke */ public class StringValue implements IClusterable { private static final long serialVersionUID = 1L; private static final Logger LOG = LoggerFactory.getLogger(StringValue.class); /** Locale to be used for formatting and parsing. */ private final Locale locale; /** The underlying string. */ private final String text; /** * @param times * Number of times to repeat character * @param c * Character to repeat * @return Repeated character string */ public static StringValue repeat(final int times, final char c) { final AppendingStringBuffer buffer = new AppendingStringBuffer(times); for (int i = 0; i < times; i++) { buffer.append(c); } return valueOf(buffer); } /** * @param times * Number of times to repeat string * @param s * String to repeat * @return Repeated character string */ public static StringValue repeat(final int times, final String s) { final AppendingStringBuffer buffer = new AppendingStringBuffer(times); for (int i = 0; i < times; i++) { buffer.append(s); } return valueOf(buffer); } /** * Converts the given input to an instance of StringValue. * * @param value * Double precision value * @return String value formatted with one place after decimal */ public static StringValue valueOf(final double value) { return valueOf(value, Locale.getDefault(Locale.Category.FORMAT)); } /** * Converts the given input to an instance of StringValue. * * @param value * Double precision value * @param places * Number of places after decimal * @param locale * Locale to be used for formatting * @return String value formatted with the given number of places after decimal */ public static StringValue valueOf(final double value, final int places, final Locale locale) { if (Double.isNaN(value) || Double.isInfinite(value)) { return valueOf("N/A"); } else { final DecimalFormat format = new DecimalFormat("#." + repeat(places, '#'), new DecimalFormatSymbols(locale)); return valueOf(format.format(value)); } } /** * Converts the given input to an instance of StringValue. * * @param value * Double precision value * @param locale * Locale to be used for formatting * @return String value formatted with one place after decimal */ public static StringValue valueOf(final double value, final Locale locale) { return valueOf(value, 1, locale); } /** * Converts the given input to an instance of StringValue. * * @param object * An object * @return String value for object */ public static StringValue valueOf(final Object object) { return valueOf(Strings.toString(object)); } /** * Converts the given input to an instance of StringValue. * * @param object * An object * @param locale * Locale to be used for formatting * @return String value for object */ public static StringValue valueOf(final Object object, final Locale locale) { return valueOf(Strings.toString(object), locale); } /** * Converts the given input to an instance of StringValue. * * @param string * A string * @return String value for string */ public static StringValue valueOf(final String string) { return new StringValue(string); } /** * Converts the given input to an instance of StringValue. * * @param string * A string * @param locale * Locale to be used for formatting * @return String value for string */ public static StringValue valueOf(final String string, final Locale locale) { return new StringValue(string, locale); } /** * Converts the given input to an instance of StringValue. * * @param buffer * A string buffer * @return String value */ public static StringValue valueOf(final AppendingStringBuffer buffer) { return valueOf(buffer.toString()); } /** * Private constructor to force use of static factory methods. * * @param text * The text for this string value */ protected StringValue(final String text) { this(text, Locale.getDefault()); } /** * Private constructor to force use of static factory methods. * * @param text * The text for this string value * @param locale * the locale for formatting and parsing */ protected StringValue(final String text, final Locale locale) { this.text = text; this.locale = locale; } /** * Gets the substring after the first occurrence given char. * * @param c * char to scan for * @return the substring */ public final String afterFirst(final char c) { return Strings.afterFirst(text, c); } /** * Gets the substring after the last occurrence given char. * * @param c * char to scan for * @return the substring */ public final String afterLast(final char c) { return Strings.afterLast(text, c); } /** * Gets the substring before the first occurrence given char. * * @param c * char to scan for * @return the substring */ public final String beforeFirst(final char c) { return Strings.beforeFirst(text, c); } /** * Gets the substring before the last occurrence given char. * * @param c * char to scan for * @return the substring */ public final String beforeLast(final char c) { return Strings.afterLast(text, c); } /** * Replaces on this text. * * @param searchFor * What to search for * @param replaceWith * What to replace with * @return This string value with searchFor replaces with replaceWith */ public final CharSequence replaceAll(final CharSequence searchFor, final CharSequence replaceWith) { return Strings.replaceAll(text, searchFor, replaceWith); } /** * Converts this StringValue to a given type. * * @param type * The type to convert to * @return The converted value * @throws StringValueConversionException */ @SuppressWarnings({ "unchecked", "rawtypes" }) public final <T> T to(final Class<T> type) throws StringValueConversionException { if (type == null) { return null; } if (type == String.class) { return (T) toString(); } if ((type == Integer.TYPE) || (type == Integer.class)) { return (T) toInteger(); } if ((type == Long.TYPE) || (type == Long.class)) { return (T) toLongObject(); } if ((type == Boolean.TYPE) || (type == Boolean.class)) { return (T) toBooleanObject(); } if ((type == Double.TYPE) || (type == Double.class)) { return (T) toDoubleObject(); } if ((type == Character.TYPE) || (type == Character.class)) { return (T) toCharacter(); } if (type == Time.class) { return (T) toTime(); } if (type == Duration.class) { return (T) toDuration(); } if (type.isEnum()) { return (T) toEnum((Class) type); } throw new StringValueConversionException("Cannot convert '" + toString() + "'to type " + type); } /** * Converts this StringValue to a given type or {@code null} if the value is empty. * * @param type * The type to convert to * @return The converted value * @throws StringValueConversionException */ public final <T> T toOptional(final Class<T> type) throws StringValueConversionException { return Strings.isEmpty(text) ? null : to(type); } /** * Convert this text to a boolean. * * @return This string value as a boolean * @throws StringValueConversionException */ public final boolean toBoolean() throws StringValueConversionException { return Strings.isTrue(text); } /** * Convert to boolean, returning default value if text is inconvertible. * * @param defaultValue * the default value * @return the converted text as a boolean or the default value if text is empty or * inconvertible * @see Strings#isTrue(String) */ public final boolean toBoolean(final boolean defaultValue) { if (text != null) { try { return toBoolean(); } catch (StringValueConversionException x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to a boolean: %s", text, x.getMessage()), x); } } } return defaultValue; } /** * Convert this text to a boolean. * * @return Converted text * @throws StringValueConversionException */ public final Boolean toBooleanObject() throws StringValueConversionException { return Strings.toBoolean(text); } /** * Convert this text to a char. * * @return This string value as a character * @throws StringValueConversionException */ public final char toChar() throws StringValueConversionException { return Strings.toChar(text); } /** * Convert to character, returning default value if text is inconvertible. * * @param defaultValue * the default value * @return the converted text as a primitive char or the default value if text is not a single * character */ public final char toChar(final char defaultValue) { if (text != null) { try { return toChar(); } catch (StringValueConversionException x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to a character: %s", text, x.getMessage()), x); } } } return defaultValue; } /** * Convert this text to a Character. * * @return Converted text * @throws StringValueConversionException */ public final Character toCharacter() throws StringValueConversionException { return toChar(); } /** * Convert this text to a double. * * @return Converted text * @throws StringValueConversionException */ public final double toDouble() throws StringValueConversionException { try { return NumberFormat.getNumberInstance(locale).parse(text).doubleValue(); } catch (ParseException e) { throw new StringValueConversionException("Unable to convert '" + text + "' to a double value", e); } } /** * Convert to double, returning default value if text is inconvertible. * * @param defaultValue * the default value * @return the converted text as a double or the default value if text is empty or inconvertible */ public final double toDouble(final double defaultValue) { if (text != null) { try { return toDouble(); } catch (Exception x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to a double: %s", text, x.getMessage()), x); } } } return defaultValue; } /** * Convert this text to a Double. * * @return Converted text * @throws StringValueConversionException */ public final Double toDoubleObject() throws StringValueConversionException { return toDouble(); } /** * Convert this text to a Duration instance. * * @return Converted text * @throws StringValueConversionException * @see Duration#valueOf(String, java.util.Locale) */ public final Duration toDuration() throws StringValueConversionException { return Duration.valueOf(text, locale); } /** * Convert to duration, returning default value if text is inconvertible. * * @param defaultValue * the default value * @return the converted text as a duration or the default value if text is empty or * inconvertible * @see Duration#valueOf(String, java.util.Locale) */ public final Duration toDuration(final Duration defaultValue) { if (text != null) { try { return toDuration(); } catch (Exception x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to a Duration: %s", text, x.getMessage()), x); } } } return defaultValue; } /** * Convert this text to an int. * * @return Converted text * @throws StringValueConversionException */ public final int toInt() throws StringValueConversionException { try { return Integer.parseInt(text); } catch (NumberFormatException e) { throw new StringValueConversionException("Unable to convert '" + text + "' to an int value", e); } } /** * Convert to integer, returning default value if text is inconvertible. * * @param defaultValue * the default value * @return the converted text as an integer or the default value if text is not an integer */ public final int toInt(final int defaultValue) { if (text != null) { try { return toInt(); } catch (StringValueConversionException x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to an integer: %s", text, x.getMessage()), x); } } } return defaultValue; } /** * Convert this text to an Integer. * * @return Converted text * @throws StringValueConversionException */ public final Integer toInteger() throws StringValueConversionException { try { return new Integer(text); } catch (NumberFormatException e) { throw new StringValueConversionException("Unable to convert '" + text + "' to an Integer value", e); } } /** * Convert this text to a long. * * @return Converted text * @throws StringValueConversionException */ public final long toLong() throws StringValueConversionException { try { return Long.parseLong(text); } catch (NumberFormatException e) { throw new StringValueConversionException("Unable to convert '" + text + "' to a long value", e); } } /** * Convert to long integer, returning default value if text is inconvertible. * * @param defaultValue * the default value * @return the converted text as a long integer or the default value if text is empty or * inconvertible */ public final long toLong(final long defaultValue) { if (text != null) { try { return toLong(); } catch (StringValueConversionException x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to a long: %s", text, x.getMessage()), x); } } } return defaultValue; } /** * Convert this text to a Long. * * @return Converted text * @throws StringValueConversionException */ public final Long toLongObject() throws StringValueConversionException { try { return new Long(text); } catch (NumberFormatException e) { throw new StringValueConversionException("Unable to convert '" + text + "' to a Long value", e); } } /** * Convert to object types, returning null if text is null or empty. * * @return converted * @throws StringValueConversionException */ public final Boolean toOptionalBoolean() throws StringValueConversionException { return Strings.isEmpty(text) ? null : toBooleanObject(); } /** * Convert to object types, returning null if text is null or empty. * * @return converted * @throws StringValueConversionException */ public final Character toOptionalCharacter() throws StringValueConversionException { return Strings.isEmpty(text) ? null : toCharacter(); } /** * Convert to object types, returning null if text is null or empty. * * @return converted * @throws StringValueConversionException */ public final Double toOptionalDouble() throws StringValueConversionException { return Strings.isEmpty(text) ? null : toDoubleObject(); } /** * Convert to object types, returning null if text is null or empty. * * @return converted * @throws StringValueConversionException */ public final Duration toOptionalDuration() throws StringValueConversionException { return Strings.isEmpty(text) ? null : toDuration(); } /** * Convert to object types, returning null if text is null or empty. * * @return converted * @throws StringValueConversionException */ public final Integer toOptionalInteger() throws StringValueConversionException { return Strings.isEmpty(text) ? null : toInteger(); } /** * Convert to object types, returning null if text is null or empty. * * @return converted * @throws StringValueConversionException */ public final Long toOptionalLong() throws StringValueConversionException { return Strings.isEmpty(text) ? null : toLongObject(); } /** * Convert to object types, returning null if text is null. * * @return converted */ public final String toOptionalString() { return text; } /** * Convert to object types, returning null if text is null or empty. * * @return converted * @throws StringValueConversionException */ public final Time toOptionalTime() throws StringValueConversionException { return Strings.isEmpty(text) ? null : toTime(); } /** * @return The string value */ @Override public final String toString() { return text; } /** * Convert to primitive types, returning default value if text is null. * * @param defaultValue * the default value to return of text is null * @return the converted text as a primitive or the default if text is null */ public final String toString(final String defaultValue) { return (text == null) ? defaultValue : text; } /** * Convert this text to a time instance. * * @return Converted text * @throws StringValueConversionException */ public final Time toTime() throws StringValueConversionException { try { return Time.valueOf(text); } catch (ParseException e) { throw new StringValueConversionException("Unable to convert '" + text + "' to a Time value", e); } } /** * Convert to time, returning default value if text is inconvertible. * * @param defaultValue * the default value * @return the converted text as a time or the default value if text is inconvertible. */ public final Time toTime(final Time defaultValue) { if (text != null) { try { return toTime(); } catch (StringValueConversionException x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to a Time: %s", text, x.getMessage()), x); } } } return defaultValue; } /** * Convert this text to an enum. * * @param eClass * enum type * @return The value as an enum * @throws StringValueConversionException */ public final <T extends Enum<T>> T toEnum(Class<T> eClass) throws StringValueConversionException { return Strings.toEnum(text, eClass); } /** * Convert this text to an enum. * * @param defaultValue * This will be returned if there is an error converting the value * @return The value as an enum */ @SuppressWarnings("unchecked") public final <T extends Enum<T>> T toEnum(final T defaultValue) { Args.notNull(defaultValue, "defaultValue"); return toEnum((Class<T>) defaultValue.getClass(), defaultValue); } /** * Convert this text to an enum. * * @param eClass * enum type * @param defaultValue * This will be returned if there is an error converting the value * @return The value as an enum */ public final <T extends Enum<T>> T toEnum(Class<T> eClass, final T defaultValue) { if (text != null) { try { return toEnum(eClass); } catch (StringValueConversionException x) { if (LOG.isDebugEnabled()) { LOG.debug(String.format("An error occurred while converting '%s' to a %s: %s", text, eClass, x.getMessage()), x); } } } return defaultValue; } /** * Convert to enum, returning null if text is null or empty. * * @param eClass * enum type * * @return converted * @throws StringValueConversionException */ public final <T extends Enum<T>> T toOptionalEnum(Class<T> eClass) throws StringValueConversionException { return Strings.isEmpty(text) ? null : toEnum(eClass); } /** * Returns whether the text is null. * * @return <code>true</code> if the text is <code>null</code>, <code>false</code> otherwise. */ public boolean isNull() { return text == null; } /** * Returns whether the text is null or empty * * @return <code>true</code> if the text is <code>null</code> or * <code>.trim().length()==0</code>, <code>false</code> otherwise. */ public boolean isEmpty() { return Strings.isEmpty(text); } /** * {@inheritDoc} */ @Override public int hashCode() { return Objects.hashCode(locale, text); } /** * {@inheritDoc} */ @Override public boolean equals(final Object obj) { if (obj instanceof StringValue) { StringValue stringValue = (StringValue) obj; return Objects.isEqual(text, stringValue.text) && locale.equals(stringValue.locale); } else { return false; } } }