org.apache.velocity.tools

## Class ConversionUtils

- java.lang.Object
- - org.apache.velocity.tools.ConversionUtils

    public class ConversionUtils
    extends Object

Utility methods for parsing or otherwise converting between types. Current supported types are Number, Date, Calendar, String, Boolean, Locale and URL

Author:
  Nathan Bubna

### Field Summary

Fields
`static ConversionUtils` `INSTANCE`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`static List` `asList(Object value)`
`static DateFormat` `getDateFormat(int dateStyle, int timeStyle, Locale locale, TimeZone timezone)` Returns a `DateFormat` instance for the specified time style, date style, `Locale`, and `TimeZone`.
`static DateFormat` `getDateFormat(String format, Locale locale, TimeZone timezone)` Returns a `DateFormat` instance for the specified format, `Locale`, and `TimeZone`.
`static DateFormat` `getDateFormat(String dateStyle, String timeStyle, Locale locale, TimeZone timezone)` Returns a `DateFormat` instance for the specified date style, time style, `Locale`, and `TimeZone`.
`static int` `getDateStyleAsInt(String style)` Checks a string to see if it matches one of the standard DateFormat style patterns: full, long, medium, short, or default.
`ConversionUtils` `getInstance()`
`static NumberFormat` `getNumberFormat(int numberStyle, Locale locale)` Returns a `NumberFormat` instance for the specified number style and `Locale`.
`static NumberFormat` `getNumberFormat(String format, Locale locale)` Returns a `NumberFormat` instance for the specified format and `Locale`.
`static int` `getNumberStyleAsInt(String style)` Checks a string to see if it matches one of the standard NumberFormat style patterns: number, currency, percent, integer, or default.
`static Boolean` `toBoolean(Object value)` Converts any Object to a boolean using `toString(Object)` and `Boolean.valueOf(String)`.
`static Calendar` `toCalendar(Date date, Locale locale)`
`static Date` `toDate(Object obj)` Attempts to convert an unidentified `Object` into a `Date`, just short of turning it into a string and parsing it.
`static Date` `toDate(Object obj, String format, Locale locale, TimeZone timezone)` Converts an object to an instance of `Date` using the specified format, `Locale`, and `TimeZone` if the object is not already an instance of Date, Calendar, or Long.
`static Date` `toDate(String str, String format, Locale locale, TimeZone timezone)` Converts an object to an instance of `Date` using the specified format, `Locale`, and `TimeZone` if the object is not already an instance of Date, Calendar, or Long.
`static Locale` `toLocale(String value)` Converts a string to a `Locale`
`static Number` `toNumber(Object obj)` Attempts to convert an unidentified `Object` into a `Number`, just short of turning it into a string and parsing it.
`static Number` `toNumber(Object obj, boolean handleStrings)` Just like `toNumber(Object)` except that you can tell this to attempt parsing the object as a String by passing `true` as the second parameter.
`static Number` `toNumber(Object value, String format, Locale locale)` Converts an object to an instance of `Number` using the specified format and `Locale` to parse it, if necessary.
`static Number` `toNumber(String value, String format, Locale locale)` Converts a string to an instance of `Number` using the specified format and `Locale` to parse it.
`static String` `toString(Collection values)` Returns the first value as a String, if any; otherwise returns null.
`static String` `toString(Object value)` Converts objects to String in a more Tools-ish way than String.valueOf(Object), especially with nulls, Arrays and Collections.
`static URL` `toURL(String value)` Converts a string to a `URL`.
`static URL` `toURL(String value, Object caller)` Converts a string to a `URL`.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### INSTANCE

    public static final ConversionUtils INSTANCE

### Method Detail

#### getInstance

    public ConversionUtils getInstance()

#### getNumberFormat

    public static NumberFormat getNumberFormat(String format,
                                               Locale locale)

Returns a `NumberFormat` instance for the specified format and `Locale`. If the format specified is a standard style pattern, then a number instance will be returned with the number style set to the specified style. If it is a custom format, then a customized `NumberFormat` will be returned.

Parameters:
  `format` - the custom or standard formatting pattern to be used
  `locale` - the `Locale` to be used
Returns:
  an instance of `NumberFormat`
See Also:
  `NumberFormat`

#### getNumberFormat

    public static NumberFormat getNumberFormat(int numberStyle,
                                               Locale locale)

Returns a `NumberFormat` instance for the specified number style and `Locale`.

Parameters:
  `numberStyle` - the number style (number will be ignored if this is less than zero or the number style is not recognized)
  `locale` - the `Locale` to be used
Returns:
  an instance of `NumberFormat` or `null` if an instance cannot be constructed with the given parameters

#### getNumberStyleAsInt

    public static int getNumberStyleAsInt(String style)

Checks a string to see if it matches one of the standard NumberFormat style patterns: number, currency, percent, integer, or default. if it does it will return the integer constant for that pattern. if not, it will return -1.

Parameters:
  `style` - the string to be checked
Returns:
  the int identifying the style pattern
See Also:
  `NumberFormat`

#### toNumber

    public static Number toNumber(Object obj)

Attempts to convert an unidentified `Object` into a `Number`, just short of turning it into a string and parsing it. In other words, this will convert to `Number` from a `Number`, `Calendar`, or `Date`. If it can't do that, it will get the string value and have `toNumber(String,String,Locale)` try to parse it using the default Locale and format.

Parameters:
  `obj` - - the object to convert
Returns:
  the converted Number or null if the conversion failed

#### toNumber

    public static Number toNumber(Object obj,
                                  boolean handleStrings)

Just like `toNumber(Object)` except that you can tell this to attempt parsing the object as a String by passing `true` as the second parameter. If you do so, then it will have `toNumber(String,String,Locale)` try to parse it using the default Locale and format.

Parameters:
  `obj` - the target object
  `handleStrings` - whether to try to convert from a string
Returns:
  the converted Number or null if the conversion failed

#### toNumber

    public static Number toNumber(String value,
                                  String format,
                                  Locale locale)

Converts a string to an instance of `Number` using the specified format and `Locale` to parse it.

Parameters:
  `value` - - the string to convert
  `format` - - the format the number is in
  `locale` - - the `Locale`
Returns:
  the string as a `Number` or `null` if no conversion is possible
See Also:
  `NumberFormat.parse(java.lang.String, java.text.ParsePosition)`

#### toNumber

    public static Number toNumber(Object value,
                                  String format,
                                  Locale locale)

Converts an object to an instance of `Number` using the specified format and `Locale` to parse it, if necessary.

Parameters:
  `value` - - the object to convert
  `format` - - the format the number is in
  `locale` - - the `Locale`
Returns:
  the object as a `Number` or `null` if no conversion is possible
See Also:
  `NumberFormat.parse(java.lang.String, java.text.ParsePosition)`

#### getDateFormat

    public static DateFormat getDateFormat(String format,
                                           Locale locale,
                                           TimeZone timezone)

Returns a `DateFormat` instance for the specified format, `Locale`, and `TimeZone`. If the format specified is a standard style pattern, then a date-time instance will be returned with both the date and time styles set to the specified style. If it is a custom format, then a customized `SimpleDateFormat` will be returned.

Parameters:
  `format` - the custom or standard formatting pattern to be used
  `locale` - the `Locale` to be used
  `timezone` - the `TimeZone` to be used
Returns:
  an instance of `DateFormat`
See Also:
  `SimpleDateFormat`, `DateFormat`

#### getDateFormat

    public static DateFormat getDateFormat(String dateStyle,
                                           String timeStyle,
                                           Locale locale,
                                           TimeZone timezone)

Returns a `DateFormat` instance for the specified date style, time style, `Locale`, and `TimeZone`.

Parameters:
  `dateStyle` - the date style
  `timeStyle` - the time style
  `locale` - the `Locale` to be used
  `timezone` - the `TimeZone` to be used
Returns:
  an instance of `DateFormat`
See Also:
  `getDateFormat(int timeStyle, int dateStyle, Locale locale, TimeZone timezone)`

#### getDateFormat

    public static DateFormat getDateFormat(int dateStyle,
                                           int timeStyle,
                                           Locale locale,
                                           TimeZone timezone)

Returns a `DateFormat` instance for the specified time style, date style, `Locale`, and `TimeZone`.

Parameters:
  `dateStyle` - the date style (date will be ignored if this is less than zero and the date style is not)
  `timeStyle` - the time style (time will be ignored if this is less than zero and the date style is not)
  `locale` - the `Locale` to be used
  `timezone` - the `TimeZone` to be used
Returns:
  an instance of `DateFormat` or `null` if an instance cannot be constructed with the given parameters

#### getDateStyleAsInt

    public static int getDateStyleAsInt(String style)

Checks a string to see if it matches one of the standard DateFormat style patterns: full, long, medium, short, or default. If it does, it will return the integer constant for that pattern. If not, it will return -1.

Parameters:
  `style` - the string to be checked
Returns:
  the int identifying the style pattern
See Also:
  `DateFormat`

#### toDate

    public static Date toDate(Object obj)

Attempts to convert an unidentified `Object` into a `Date`, just short of turning it into a string and parsing it. In other words, this will convert to `Date` from a `Date`, `Calendar`, or `Number`. If it can't do that, it will return `null`.

Parameters:
  `obj` - - the object to convert
Returns:
  the converted Date, or null if the conversion failed

#### toDate

    public static Date toDate(Object obj,
                              String format,
                              Locale locale,
                              TimeZone timezone)

Converts an object to an instance of `Date` using the specified format, `Locale`, and `TimeZone` if the object is not already an instance of Date, Calendar, or Long.

Parameters:
  `obj` - - the date to convert
  `format` - - the format the date is in
  `locale` - - the `Locale`
  `timezone` - - the `TimeZone`
Returns:
  the object as a `Date` or `null` if no conversion is possible
See Also:
  `getDateFormat(java.lang.String, java.util.Locale, java.util.TimeZone)`, `SimpleDateFormat.parse(java.lang.String, java.text.ParsePosition)`

#### toDate

    public static Date toDate(String str,
                              String format,
                              Locale locale,
                              TimeZone timezone)

Converts an object to an instance of `Date` using the specified format, `Locale`, and `TimeZone` if the object is not already an instance of Date, Calendar, or Long.

Parameters:
  `str` - - the string to parse
  `format` - - the format the date is in
  `locale` - - the `Locale`
  `timezone` - - the `TimeZone`
Returns:
  the string as a `Date` or `null` if the parsing fails
See Also:
  `getDateFormat(java.lang.String, java.util.Locale, java.util.TimeZone)`, `SimpleDateFormat.parse(java.lang.String, java.text.ParsePosition)`

#### toCalendar

    public static Calendar toCalendar(Date date,
                                      Locale locale)

#### toString

    public static String toString(Object value)

Converts objects to String in a more Tools-ish way than String.valueOf(Object), especially with nulls, Arrays and Collections. Null returns null, Arrays and Collections return their first value, or null if they have no values.

Parameters:
  `value` - the object to be turned into a String
Returns:
  the string value of the object or null if the value is null or it is an array whose first value is null

#### toString

    public static String toString(Collection values)

Returns the first value as a String, if any; otherwise returns null.

Parameters:
  `values` - the Collection to be turned into a string
Returns:
  the string value of the first object in the collection or null if the collection is empty

#### toBoolean

    public static Boolean toBoolean(Object value)

Converts any Object to a boolean using `toString(Object)` and `Boolean.valueOf(String)`.

Parameters:
  `value` - the object to be converted
Returns:
  a `Boolean` object for the specified value or `null` if the value is null or the conversion failed

#### toLocale

    public static Locale toLocale(String value)

Converts a string to a `Locale`

Parameters:
  `value` - - the string to parse
Returns:
  the `Locale` or `null` if the parsing fails

#### toURL

    public static URL toURL(String value)

Converts a string to a `URL`. It will first try to treat the string as a File name, then a classpath resource, then finally as a literal URL. If none of these work, then this will return `null`.

Parameters:
  `value` - - the string to parse
Returns:
  the `URL` form of the string or `null`
See Also:
  `File`, `ClassUtils.getResource(String,Object)`, `URL`

#### toURL

    public static URL toURL(String value,
                            Object caller)

Converts a string to a `URL`. It will first try to treat the string as a File name, then a classpath resource, then finally as a literal URL. If none of these work, then this will return `null`.

Parameters:
  `value` - - the string to parse
  `caller` - - the object or Class seeking the url
Returns:
  the `URL` form of the string or `null`
See Also:
  `File`, `ClassUtils.getResource(String,Object)`, `URL`

#### asList

    public static List asList(Object value)