Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## umontreal.iro.lecuyer.util
Class StringConvert

    java.lang.Object
      umontreal.iro.lecuyer.util.StringConvert

    public class StringConvert

extends Object

Provides utility methods to convert strings into Java objects. The Java class library already contains some facilities to convert strings to many object types, but the target class must be known at compile time. With these utility methods, a conversion can be performed with a target class known at run time.

Method Summary
`static Boolean` | `booleanFromString(String val)` Converts a string `val` to a boolean wrapper object.
`static String` | `byteToString(byte b)` Same as `intToString(int)` for a byte.
`static Duration` | `durationFromString(String str)` Constructs and returns a `Duration` object obtained from the string `str`.
`static
`<T> T`
` | `fromString(URI baseURI, ClassFinder finder, Class<T> cls, String val)` Tries to convert the string `val` into an object of the class `cls` or one of its subclasses or implementations.
`static Object[]` | `getArgumentsFromString(URI baseURI, ClassFinder finder, Class<?>[] paramTypes, String[] vals)` Converts an array of strings `vals` to an array of arguments to be passed to a constructor or method with parameter types `paramTypes`.
`static String[]` | `getArrayElements(String val)` Tokenizes the string `val` into an array of strings using whitespaces or commas as delimiters, and merging back parts surrounded by braces or parentheses.
`static
`<T> T`
` | `getStaticValue(URI baseURI, ClassFinder finder, Class<T> cls, String val)` Converts `val` to an instance of `cls` by considering the string as a call to a constructor, a static method or a static field.
`static String` | `intToString(int i)` Converts the integer value `i` to a string by using `String.valueOf(int)`.
`static String` | `longToString(long l)` Same as `intToString(int)` for a long.
`static
`<T> T`
` | `numberFromString(Class<T> cls, String val)` Converts the string `val` to an instance of `cls` being a subclass of `Number` or a primitive numeric type.
`static String` | `numberToString(Number n)` Formats the number `n` into a string.
`static String` | `shortToString(short s)` Same as `intToString(int)` for a short.
`static
`<T> T`
` | `tryToCallConstructor(URI baseURI, ClassFinder finder, Class<T> cls, String... vals)` Tries to find a compatible constructor in class `cls`, converts the arguments stored into `vals` to the arguments of the constructor, calls it and returns the constructed instance.
`static
`<T> T`
` | `tryToCallMethod(URI baseURI, ClassFinder finder, Class<T> rcls, Class<?> cls, Object o, String name, String... vals)` Tries to call a method named `name` on object `o` with arguments given by `vals`, with expected return value class `rcls`.
`static URI` | `uriFromString(URI baseURI, String uri)` Constructs and returns a new URI from the string `url`, resolved against the base URI `baseURI`.
`static URL` | `urlFromString(URI baseURI, String url)` This method calls `uriFromString(URI,String)` with the given base URI, and URL, and converts the resulting URI into a URL using `URI.toURL()`.
`static
`<T> T`
` | `wrapperFromString(Class<T> cls, String val)` Converts a string to a wrapper object of class `cls`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### fromString

    public static <T> T fromString(URI baseURI,
                                   ClassFinder finder,
                                   Class<T> cls,
                                   String val)
                        throws UnsupportedConversionException,
                               NameConflictException

  Tries to convert the string `val` into an object of the class `cls` or one of its subclasses or implementations. `cls` can be a primitive type, a class type, or an array. When a primitive target type is given, the method returns an object from the corresponding wrapper class. The class finder `finder` is used to resolve class names and will be replaced by `Class.forName(java.lang.String)` if `null`.

  If `cls` is `String` or `Object`, `val` is returned unchanged. If it is `null`, a null pointer is returned. The method tries to use `numberFromString(Class,String)` for numeric types. If `cls` corresponds to the `Duration` class, this method calls `durationFromString(String)`. If `cls.isEnum()` returns `true`, it uses `Enum.valueOf(java.lang.Class, java.lang.String)` to convert the string to an object representing an enum constant. For the `char` type, the first character of the string is returned into the `Character` wrapper object. For boolean type, the method uses `booleanFromString(String)`. Objects of class `URI` are obtained using `uriFromString(URI,String)` while objects of class `URL` are obtained by `urlFromString(URI,String)`. If no previous class is compatible with the target class, the method tries to use `wrapperFromString(Class,String)` to perform the conversion.

  If the target object is from class `Class`, the given string is interpreted as a class name and passed to `findClass` to get a `Class` object, using the class finder to resolve the class name. If `finder` is `null`, `Class.forName(java.lang.String)` is used instead.

  The method also processes arrays in arbitrary depths. For a one-dimensional array, the string is read as a list of tokens separated with commas and for each token, the method is called recursively. The `getArrayElements(java.lang.String)` method is used to perform the tokenization. To encode multi-dimensional arrays, one must encode arrays into tokens by using the brackets. For example, if the target class is `int[][]`, `[1,2],[3,4]` will be converted as a 2D array with `1,2` in the index 0 and `3,4` in the index 1.

  If the target class is not an array and cannot be converted in any ways, the method forwards the call to `getStaticValue(java.net.URI, umontreal.iro.lecuyer.util.ClassFinder, java.lang.Class, java.lang.String)`.

  Parameters:
    `baseURI` - the base URI used by `uriFromString(URI,String)` and `urlFromString(URI,String)`.
    `finder` - the class finder being used to look for classes if necessary.
    `cls` - the target class of the returned object.
    `val` - the string to be converted.
  Returns:
    the converted object.
  Throws:
    `IllegalArgumentException` - if the string cannot be converted, although conversion to the target class is supported.
    `UnsupportedConversionException` - if the target class is not supported by the converter.
    `NameConflictException` - if a name conflict occurs when resolving a class name.

### getArgumentsFromString

    public static Object[] getArgumentsFromString(URI baseURI,
                                                  ClassFinder finder,
                                                  Class<?>[] paramTypes,
                                                  String[] vals)
                                           throws UnsupportedConversionException,
                                                  NameConflictException

  Converts an array of strings `vals` to an array of arguments to be passed to a constructor or method with parameter types `paramTypes`. The method tries to convert `vals[p]` to the class given by `paramTypes[p]` using the `String)` method and stores the result in the returned array.

  Parameters:
    `baseURI` - the base URI used by `fromString(URI,ClassFinder,Class,String)`
    `paramTypes` - the target type of each argument.
    `vals` - the string arguments.
  Returns:
    an array of objects representing each argument.
  Throws:
    `IllegalArgumentException` - if `vals` and `paramTypes` have different lengths or a conversion error occurred.
    `NullPointerException` - if `vals`, `paramTypes` or any elements of these arrays are `null`.
    `UnsupportedConversionException` - if the converter does not support one or more argument class.
    `NameConflictException`

### getStaticValue

    public static <T> T getStaticValue(URI baseURI,
                                       ClassFinder finder,
                                       Class<T> cls,
                                       String val)
                            throws UnsupportedConversionException,
                                   NameConflictException

  Converts `val` to an instance of `cls` by considering the string as a call to a constructor, a static method or a static field. The string must be speficied as a Java expression. The arguments of constructors and static methods are processed by `String)`. The constructed class, the type of the static field, or the return value of the static method must be assignable to the target class. If the conversion fails, an `IllegalArgumentException` is thrown.

  Parameters:
    `baseURI` - the base URI used by `uriFromString(URI,String)` and `urlFromString(URI,String)`.
    `finder` - the class finder being used.
    `cls` - the target class for the conversion.
    `val` - the expression being converted.
  Returns:
    the constructed object.
  Throws:
    `UnsupportedConversionException` - if `String)` fails processing the arguments because the class of the called constructor's arguments, the type of the referenced field, or the return value of the called method are not supported as target classes.
    `NameConflictException` - if a class name conflict arises.
    `IllegalArgumentException` - if the target class is supported but a conversion problem occurs.

### getArrayElements

    public static String[] getArrayElements(String val)

  Tokenizes the string `val` into an array of strings using whitespaces or commas as delimiters, and merging back parts surrounded by braces or parentheses. Parentheses always appear in resulting tokens while the surrounding braces are removed. Any consecutive substring of whitespace is replaced by a single whitespace character. This method is different from `String.split(java.lang.String, int)` because it takes braces and parentheses into account.

  For example, the string `1 2 3 4` given to this method would produce an array containing four elements: `1`, `2`, `3`, and `4`. The string `{1,2} {3 4}` will be separated in two strings by this method: `1 2` and `3 4`. The string `{{1 2} 3} a (4 5)` would become an array containing `{ 1 2 } 3`, and `a ( 4 5 )`.

  Parameters:
    `val` - the value to be tokenized.
  Returns:
    an array of strings representing each token.

### numberFromString

    public static <T> T numberFromString(Class<T> cls,
                                         String val)
                              throws UnsupportedConversionException

  Converts the string `val` to an instance of `cls` being a subclass of `Number` or a primitive numeric type. In the `val` argument, the method accepts a number or the special strings `Infinity`, `INF`, `-Infinity`, and `-INF`. For an integer, a short, a long or a byte, infinity is represented using the greatest or smallest acceptable value for the built-in types. For single or double-precision floating points, the infinity can be represented directly. For floating-points, the `nan` string is accepted to denote a NaN.

  Parameters:
    `cls` - the target class.
    `val` - the string being converted.
  Returns:
    the constructed numeric wrapper object.
  Throws:
    `NumberFormatException` - if a conversion problem occurred.
    `UnsupportedConversionException` - if the class is not a supported subclass of `Number` or a primitive numeric type.

### booleanFromString

    public static Boolean booleanFromString(String val)

  Converts a string `val` to a boolean wrapper object. The method accepts `1`, `true`, `yes`, and `on` as a true value and `0`, `false`, `no`, and `off` as a false value.

  Parameters:
    `val` - the value being converted.
  Returns:
    the result of the conversion.
  Throws:
    `IllegalArgumentException` - if the value cannot be converted.

### uriFromString

    public static URI uriFromString(URI baseURI,
                                    String uri)

  Constructs and returns a new URI from the string `url`, resolved against the base URI `baseURI`. If `baseURI` is `null`, this method creates a new URI using the `URI.URI(String)` constructor. Otherwise, it resolves the string `uri` against the base URI to obtain the URI object. Any exception is wrapped into an illegal-argument exception.

  Parameters:
    `baseURI` - the base URI.
    `uri` - the URI to resolve.
  Returns:
    the resolved URI object.

### urlFromString

    public static URL urlFromString(URI baseURI,
                                    String url)

  This method calls `uriFromString(URI,String)` with the given base URI, and URL, and converts the resulting URI into a URL using `URI.toURL()`.

  Parameters:
    `baseURI` - the base URI.
    `url` - the URL.
  Returns:
    the resulting URL object.

### durationFromString

    public static Duration durationFromString(String str)
                                       throws UnsupportedConversionException

  Constructs and returns a `Duration` object obtained from the string `str`. This method uses `DatatypeFactory.newDuration(String)` to perform the conversion.

  Parameters:
    `str` - the string to convert.
  Returns:
    the obtained duration.
  Throws:
    `UnsupportedConversionException` - if the data type factory could not be created.

### wrapperFromString

    public static <T> T wrapperFromString(Class<T> cls,
                                          String val)
                               throws UnsupportedConversionException

  Converts a string to a wrapper object of class `cls`. This method tries to find a constructor for class `cls` taking a `String` as its unique argument. If such a constructor can be found, it is used to instantiate a new object which is returned. If no such constructor can be found and invoked, the method searches for a `valueOf` public static method taking a `String` argument and returning an instance of `cls` or a subclass of `cls`. If the class does not contain an appropriate constructor or static method, an `UnsupportedConversionException` is thrown. If the constructor or method is found but cannot be called successfully, an `IllegalArgumentException` is thrown.

  Parameters:
    `cls` - the target class for the conversion.
    `val` - the value being converted.
  Returns:
    the converted value.
  Throws:
    `IllegalArgumentException` - if an exception occurred during the construction of the wrapper object.
    `UnsupportedConversionException` - if the target class does not contain an appropriate constructor or static method.

### tryToCallConstructor

    public static <T> T tryToCallConstructor(URI baseURI,
                                             ClassFinder finder,
                                             Class<T> cls,
                                             String... vals)
                                  throws UnsupportedConversionException,
                                         NameConflictException,
                                         NoSuchMethodException

  Tries to find a compatible constructor in class `cls`, converts the arguments stored into `vals` to the arguments of the constructor, calls it and returns the constructed instance. For each constructor with the appropriate number of arguments, argument `vals[i]` is converted to the type of the argument `i` of the constructor, using `String[])`. If one conversion fails, the other constructors are tried. If all conversion fail, an exception is thrown.

  Parameters:
    `baseURI` - the base URI used by `uriFromString(URI,String)` and `urlFromString(URI,String)`.
    `finder` - the class finder used by `String[])`.
    `cls` - the target class.
    `vals` - the arguments for the constructor.
  Returns:
    the constructed instance.
  Throws:
    `UnsupportedConversionException` - if some arguments could not be converted.
    `NameConflictException` - if a name conflict occurred during class name resolving.
    `IllegalArgumentException` - if the conversion of an argument is supported by `String)`, but some errors occurred, or an exception occurred during the call to the constructor.
    `NoSuchMethodException` - if no appropriate constructor could be found.

### tryToCallMethod

    public static <T> T tryToCallMethod(URI baseURI,
                                        ClassFinder finder,
                                        Class<T> rcls,
                                        Class<?> cls,
                                        Object o,
                                        String name,
                                        String... vals)
                             throws UnsupportedConversionException,
                                    NameConflictException,
                                    NoSuchMethodException

  Tries to call a method named `name` on object `o` with arguments given by `vals`, with expected return value class `rcls`. The method searches for all public methods in `cls` taking `vals.length` arguments (0 argument if `vals` is `null`), and tries to convert the arguments using `String[])`. If `o` is `null`, the search will be restricted to static methods.

  Parameters:
    `baseURI` - the base URI used by `uriFromString(URI,String)` and `urlFromString(URI,String)`.
    `finder` - the class finder used by `String[])`.
    `rcls` - the target class of the return type.
    `cls` - the class defining the method to be invoked.
    `o` - the object on which the method is invoked, should be an instance of the class represented by `cls`.
    `name` - the name of the method.
    `vals` - the arguments for the method.
  Returns:
    the return value.
  Throws:
    `UnsupportedConversionException` - if some arguments are not compatible with `String)`.
    `NameConflictException` - if a name conflict occurs during a class name resolution.
    `IllegalArgumentException` - if no method can be found or some conversions failed.
    `NoSuchMethodException` - if no appropriate method could be found.

### intToString

    public static String intToString(int i)

  Converts the integer value `i` to a string by using `String.valueOf(int)`. If `i` is equal to the minimum or maximum value of an integer, `-Infinity` or `Infinity` are returned, respectively.

  Parameters:
    `i` - the integer being formatted.
  Returns:
    the formatted integer.

### byteToString

    public static String byteToString(byte b)

  Same as `intToString(int)` for a byte.

  Parameters:
    `b` - the byte being formatted.
  Returns:
    the formatted byte.

### shortToString

    public static String shortToString(short s)

  Same as `intToString(int)` for a short.

  Parameters:
    `s` - the short integer being formatted.
  Returns:
    the formatted value.

### longToString

    public static String longToString(long l)

  Same as `intToString(int)` for a long.

  Parameters:
    `l` - the long integer being formatted.
  Returns:
    the formatted value.

### numberToString

    public static String numberToString(Number n)

  Formats the number `n` into a string. If `n` is an instance of wrapped primitive numeric type, the appropriate `convert` static method of this class is called to perform the conversion. Otherwise, `Object.toString()` is used. This method is used to return `Infinity`, and `NaN` as required, instead of large or small values.

  Parameters:
    `n` - the number being formatted.
  Returns:
    the formatted value.

Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

To submit a bug or ask questions, send an e-mail to Richard Simard.