org.locomotive.util
Class StringUtil

java.lang.Object
  |
  +--org.locomotive.util.StringUtil

public class StringUtil
extends java.lang.Object

Utilities for manipulating strings. Should be relatively robust.

A simple example:

String s = "hello \"there\" you\\me"; // produces: hello "there" you\me System.out.println(encodeString(s)); // produces: ["hello \"there\" you\\me"] (less the [ and ] brackets) Vector v = new Vector(); v.addElement(s); v.addElement(s); System.out.println(decodeStrings(encodeStrings(v))); // produces: [hello "there" you\me, hello "there" you\me] Also, there are many methods of the form, "get...()", for parsing values in a specific format or of a specific type out of a string. These methods are analogous to the methods of the same name in the FormData class. Refer to the documentation in that class for an understanding of how to use these get...() methods. Also, @see ParseStringException.


Constructor Summary
StringUtil()
           
 
Method Summary
static java.lang.String CGIUnescape(java.lang.String s)
          takes CGIEncoded strings (normally from the contents of the STDIN in a POST) and unquotes them
static java.lang.String clip(java.lang.String s, int max_length)
          A utility function to trim a string to a given length.
static java.util.Vector decodeStrings(java.lang.String s)
          Takes a string that represents a list of strings and parses them out.
static java.lang.String encodeString(java.lang.String s)
          Take a string and replace all the "'s with \"'s and the \'s with \\'s and surrounds the string with "'s which is necessary for a concatenated list of strings to be sucessfully decoded.
static java.lang.String encodeStrings(java.util.Enumeration e)
          encode strings with the default seperator ", "...
static java.lang.String encodeStrings(java.util.Enumeration e, java.lang.String seperator)
          Take an enumeration of strings and make a big string of encoded strings.
static java.lang.String encodeStrings(java.util.Vector v)
          encode strings with the default seperator ", "...
static java.lang.String encodeStrings(java.util.Vector v, java.lang.String seperator)
          Take a vector of strings and make a big string of encoded strings.
static java.lang.String encodeStringsEfficiently(java.util.Enumeration e)
          encode strings with no seperator (saves some space.) Same thing as encodeStrings(s, "") (call that for even more efficiency :-) ) This will decode just fine.
static java.lang.String encodeStringsEfficiently(java.util.Vector v)
          encode strings with no seperator (saves some space.) Same thing as encodeStrings(s, "") (call that for even more efficiency :-) ) This will decode just fine.
static java.lang.String exceptionStackTrace(java.lang.Throwable e)
          A utility function - given the exception, give us a string that contains the stack trace for it.
static java.lang.String getAlphanum(java.lang.String string_containing_alphanum)
          trims string_containing_alphanum and returns a string containing only alphanumerics.
static java.lang.String getAlphanum(java.lang.String string_containing_alphanum, int minimum_length, int maximum_length, boolean warn_non_alphanum)
          if this field contains non-alphanumerics, then they will be removed.
static java.util.Date getDate(java.lang.String string_containing_date)
          tries to parse a field as a Date in one of the following formats: "MMM d, yyyy", "MM-d-yy", "MM-d-yyyy", "MM/d/yy", "MM/d/yyyy", "d.MM.yy", "d.MM.yyyy"
static java.util.Date getDate(java.lang.String month_field, java.lang.String day_field, java.lang.String year_field)
          tries to parse the three fields, month_field, day_field, and year_field, and create a Date out of them.
static java.lang.String getDigits(java.lang.String string_containing_digits)
          trims string_containing_digits and returns a string containing only digits.
static java.lang.String getDigits(java.lang.String string_containing_digits, int minimum_length, int maximum_length, boolean warn_non_digits)
          if this field contains non-digits, then the non-digits will be removed.
static java.lang.String getTrimmedString(java.lang.String string_value, int minimum_length, int maximum_length)
          This method trims the leading and trailing whitespace in a string, and returns its value.
static void htmlQuoteHash(java.util.Hashtable ht)
          HTML quotes all values in the input hash.
static java.lang.String htmlQuoteString(java.lang.String s)
          quotes any string for interpreted display of an HTML page by a browser.
static java.lang.String intArrayToString(int[] int_array, java.lang.String separator)
          Given an array of ints, convert it to one string with the separator as given.
static boolean isAlphanum(java.lang.String string_containing_alphanum)
          tells whether string_containing_alphanum contains only alphanumerics.
static boolean isDigits(java.lang.String string_containing_digits)
          tells whether string_containing_digits contains only digits.
static boolean isEmailAddress(java.lang.String email_address)
          Will tell you whether the email address is a valid SMTP email address.
static boolean isInt(java.lang.String string_value)
          tells whether this string contains an int.
static java.lang.String removeWhitespaces(java.lang.String string_value)
          This method removes all whitespace in string_value.
static java.lang.String shellEscape(java.lang.String s)
          Shell escapes a given string.
static java.lang.String stringArrayToString(java.lang.String[] string_array, java.lang.String separator)
          Given an array of strings, convert it to one string with the separator as given.
static java.lang.String stringArrayToString(java.lang.String[] string_array, java.lang.String separator, int start_index)
          Given an array of strings, convert it to one string with the separator as given.
static int[] stringToIntArray(java.lang.String str, java.lang.String separator)
          This is the opposite of intArrayToString().
static java.lang.String[] stringToStringArray(java.lang.String str, java.lang.String separator)
          This is the opposite of stringArrayToString().
static java.lang.String URLDecode(java.lang.String s)
          Decodes a string encoded with URLEncode.
static java.lang.String URLEncode(java.lang.String s)
          takes an arbitrary string, returns a URLEncoded String everything but letters and numbers are escaped via the "%" sign.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StringUtil

public StringUtil()
Method Detail

decodeStrings

public static java.util.Vector decodeStrings(java.lang.String s)
Takes a string that represents a list of strings and parses them out. Supports using the "\" operator to include "'s in a string, like java. Any non-terminated strings should be kept up to the end of the input string (i.e., using ['s and ]'s as my meta string characters, ["stringone", "Stringtwo", "stringthree] will give a vector of [stringone], [Stringtwo], and [stringthree]. Commas aren't needed in between strings. It just looks for the next ["]. So ["stringone""stringtwo""stringthree"] works just as well. Remember, the ['s I just put in there to be clear about what the strings are... those are treated as normal characters. The "\" character allows anything after itself (\'s at the end of an input string are kept as characters.) So ["stringone" "\"stringtwo"garbage235478"\"string\"three\""] comes out as [stringone] ["stringtwo] and ["string"three"] ... [\\] gives [\], etc.

Why? It allows some handiness. Like if you want to save a bunch of strings in one field in a database and want to allow quotes and slashes and what not.


encodeStringsEfficiently

public static java.lang.String encodeStringsEfficiently(java.util.Enumeration e)
encode strings with no seperator (saves some space.) Same thing as encodeStrings(s, "") (call that for even more efficiency :-) ) This will decode just fine. It just doesn't sacrifice anything for readability.

encodeStringsEfficiently

public static java.lang.String encodeStringsEfficiently(java.util.Vector v)
encode strings with no seperator (saves some space.) Same thing as encodeStrings(s, "") (call that for even more efficiency :-) ) This will decode just fine. It just doesn't sacrifice anything for readability.

encodeStrings

public static java.lang.String encodeStrings(java.util.Enumeration e)
encode strings with the default seperator ", "... i.e. gives you "stringone", "string two", "etc..."

encodeStrings

public static java.lang.String encodeStrings(java.util.Vector v)
encode strings with the default seperator ", "... i.e. gives you "stringone", "string two", "etc..."

encodeStrings

public static java.lang.String encodeStrings(java.util.Vector v,
                                             java.lang.String seperator)
Take a vector of strings and make a big string of encoded strings. This can then be decoded with decodeStrings. Seperator is what comes between each string. Nothing is needed for parsing to work correctly, but adding something like ", " between each string may improve readability. This is NOT the special seperator used by the decoder - this can not be changed (as of now) and is ". This is what comes between the string units. So "hi", "there" has a seperator of [, ] (less the brackets.) The "'s around those words have to be there for the decoder to decode them correctly. An empty vector gives you the empty string back. A vector with one string element which is the empty string gives you the string [""] back (less the [ and ]). A null vector or other errors (like non-strings in the vector) gives you null.

encodeStrings

public static java.lang.String encodeStrings(java.util.Enumeration e,
                                             java.lang.String seperator)
Take an enumeration of strings and make a big string of encoded strings. This can then be decoded with decodeStrings. Seperator is what comes between each string. Nothing is needed for parsing to work correctly, but adding something like ", " between each string may improve readability. This is NOT the special seperator used by the decoder - this can not be changed (as of now) and is ". This is what comes between the string units. So "hi", "there" has a seperator of [, ] (less the brackets.) The "'s around those words have to be there for the decoder to decode them correctly. An empty enumeration gives you the empty string back. A enumeration with one string element which is the empty string gives you the string [""] back (less the [ and ]). A null enumeration or other errors (like non-strings in the enumeration) gives you null.

encodeString

public static java.lang.String encodeString(java.lang.String s)
Take a string and replace all the "'s with \"'s and the \'s with \\'s and surrounds the string with "'s which is necessary for a concatenated list of strings to be sucessfully decoded.

CGIUnescape

public static java.lang.String CGIUnescape(java.lang.String s)
takes CGIEncoded strings (normally from the contents of the STDIN in a POST) and unquotes them

URLDecode

public static java.lang.String URLDecode(java.lang.String s)
Decodes a string encoded with URLEncode.
Parameters:
s - - the URL encoded string.

URLEncode

public static java.lang.String URLEncode(java.lang.String s)
takes an arbitrary string, returns a URLEncoded String everything but letters and numbers are escaped via the "%" sign. The result is suitable for returning to a browser.
Parameters:
s - - the input string.

htmlQuoteHash

public static void htmlQuoteHash(java.util.Hashtable ht)
HTML quotes all values in the input hash.

htmlQuoteString

public static java.lang.String htmlQuoteString(java.lang.String s)
quotes any string for interpreted display of an HTML page by a browser. For instance an & will be quoted to &

shellEscape

public static java.lang.String shellEscape(java.lang.String s)
Shell escapes a given string. Currently remove the following:
|  <  >  !   $  ,  \

exceptionStackTrace

public static java.lang.String exceptionStackTrace(java.lang.Throwable e)
A utility function - given the exception, give us a string that contains the stack trace for it.

clip

public static java.lang.String clip(java.lang.String s,
                                    int max_length)
A utility function to trim a string to a given length. null strings, strings that are less than the length, etc are returned untouched. max_length is the maximum length, NOT the maximum index.

isInt

public static boolean isInt(java.lang.String string_value)
tells whether this string contains an int. If you want the int value, don't use this method, just use Integer.parseInt().

getDigits

public static java.lang.String getDigits(java.lang.String string_containing_digits)
                                  throws ParseStringException
trims string_containing_digits and returns a string containing only digits.
Throws:
ParseStringException - If there are non-digits (other than leading and trailing whitespace), then throws ParseStringException with an error code of DOESNT_FIT_TYPE.

isDigits

public static boolean isDigits(java.lang.String string_containing_digits)
tells whether string_containing_digits contains only digits. if it's null or empty, returns true. Does not throw any ParseStringException.

getDigits

public static java.lang.String getDigits(java.lang.String string_containing_digits,
                                         int minimum_length,
                                         int maximum_length,
                                         boolean warn_non_digits)
                                  throws ParseStringException
if this field contains non-digits, then the non-digits will be removed.
Throws:
ParseStringException - Also, if it does contain non-digits, and warn_non_digits is true, then throws ParseStringException with an error code of DOESNT_FIT_TYPE.

isAlphanum

public static boolean isAlphanum(java.lang.String string_containing_alphanum)
tells whether string_containing_alphanum contains only alphanumerics. If it's null or empty, returns true. Does not throw any ParseStringException.

getAlphanum

public static java.lang.String getAlphanum(java.lang.String string_containing_alphanum)
                                    throws ParseStringException
trims string_containing_alphanum and returns a string containing only alphanumerics.
Throws:
ParseStringException - If there are non-alphanumerics, then throws ParseStringException with an error code of DOESNT_FIT_TYPE.

getAlphanum

public static java.lang.String getAlphanum(java.lang.String string_containing_alphanum,
                                           int minimum_length,
                                           int maximum_length,
                                           boolean warn_non_alphanum)
                                    throws ParseStringException
if this field contains non-alphanumerics, then they will be removed.
Throws:
ParseStringException - If it does contain non-alphanumerics, and warn_non_alphanum is true, then throws ParseStringException with an error code of DOESNT_FIT_TYPE.

getTrimmedString

public static java.lang.String getTrimmedString(java.lang.String string_value,
                                                int minimum_length,
                                                int maximum_length)
                                         throws ParseStringException
This method trims the leading and trailing whitespace in a string, and returns its value.
Throws:
ParseStringException - If the field is shorter than the minimum length, or if it is longer than the maximum length, throws a ParseStringException with an error code of TOO_SHORT or TOO_LONG, respectively. However, it will NOT throw an exception if there is whitespace in the field.

removeWhitespaces

public static java.lang.String removeWhitespaces(java.lang.String string_value)
This method removes all whitespace in string_value. It will NOT throw an error if there is whitespace in the field.

getDate

public static java.util.Date getDate(java.lang.String string_containing_date)
tries to parse a field as a Date in one of the following formats: "MMM d, yyyy", "MM-d-yy", "MM-d-yyyy", "MM/d/yy", "MM/d/yyyy", "d.MM.yy", "d.MM.yyyy"
Returns:
If it could not parse the field as a Date, will return null.

getDate

public static java.util.Date getDate(java.lang.String month_field,
                                     java.lang.String day_field,
                                     java.lang.String year_field)
                              throws ParseStringException
tries to parse the three fields, month_field, day_field, and year_field, and create a Date out of them. The month_field argument can be either a number from 1-12 or at least the first three letters of the name of a month, upper or lower case.
Throws:
ParseStringException - If one of the three fields is null, will throw a ParseStringException.

isEmailAddress

public static boolean isEmailAddress(java.lang.String email_address)
Will tell you whether the email address is a valid SMTP email address. The email address should have at least one '@', at least one '.' after then '@', and should have only alphanumeric characters or characters in: [+@.'%-_!] (not including the brackets [ ]). (This method was copied largely from StringConstraint.checkForIsEmail())

stringArrayToString

public static java.lang.String stringArrayToString(java.lang.String[] string_array,
                                                   java.lang.String separator)
Given an array of strings, convert it to one string with the separator as given. Converts separator to "" if it is null.

stringArrayToString

public static java.lang.String stringArrayToString(java.lang.String[] string_array,
                                                   java.lang.String separator,
                                                   int start_index)
Given an array of strings, convert it to one string with the separator as given. Converts separator to "" if it is null. start_index is set to 0 if less than 0.

intArrayToString

public static java.lang.String intArrayToString(int[] int_array,
                                                java.lang.String separator)
Given an array of ints, convert it to one string with the separator as given.

stringToStringArray

public static java.lang.String[] stringToStringArray(java.lang.String str,
                                                     java.lang.String separator)
This is the opposite of stringArrayToString(). Given a string containing a separator, break it into an array of strings and return that.

stringToIntArray

public static int[] stringToIntArray(java.lang.String str,
                                     java.lang.String separator)
This is the opposite of intArrayToString(). Given a string containing a separator, break it into an array of strings and return that.