jcs.util
Class StringUtil

java.lang.Object
  |
  +--jcs.util.StringUtil

public class StringUtil
extends java.lang.Object

A class with miscellaneous methods:

  doCommandArgs:   Validates an array of command-line arguments and tags,
                   and merges the arguments into an array of defaults.
  validateArg:     Checks a keyword arg against permissible values.
  markupString:    Returns the argument string with XML markup replaced
                   with entity symbols (such as "<" for "<").
  isNothing:       Determines if a string is null or whitespace.
  sqlSubstring:    A substring method that uses the SQL rules 
                   for out-of-range args.
  stackTrace2String:  Returns a String with the exception stack trace.
  stream2String:   Returns the argumentInputStream contents as a String.
  string2Stream:   Returns an InputStream on the argument String.
  multiply:        Returns a given String replicated a given number of times.
  genString:       Returns a given string replicated to a given length.
                   
  


Method Summary
static java.lang.String deEntityize(java.lang.String val)
          Translates a String containing the five special XML entities (&gt;, &lt;, &amp;, &apos; and &quot;).
static void doCommandArgs(java.lang.String[] args, java.lang.String[] argTags, java.lang.String[] argVals)
          Checks the command line arguments and merges them with default values for any omitted arguments.
static java.lang.String entityize(java.lang.String val)
          Translates a String containing XML markup characters, (>, <, &, ', and ") to a String with the corresponding entities (&gt;, &lt;, &amp;, &apos;, and &quot;).
static java.lang.String genString(int len, java.lang.String seed)
          Generates a string of given length (mainly for test generation).
static java.lang.String genString(java.lang.String seed, int len)
          Generates a string of given length (mainly for test generation).
static boolean isNothing(java.lang.String val)
          Tests whether the argument is null, empty, or all whitespace.
static java.lang.String multiply(int times, java.lang.String seed)
          Repeats a given string a given number of times (mainly for test generation).
static java.lang.String multiply(java.lang.String seed, int times)
          Repeats a given string a given number of times (mainly for test generation).
static java.lang.String sqlSubstring(java.lang.String C, int startArg, int lengthArg)
          Returns a substring of the given string.
static java.lang.String stackTrace2String(java.lang.Exception e)
          Returns a String with the stack trace of the given Exception.
This is an alternative to using e.printStackTrace(), for cases where you want to save the exception info rather than print it.
static java.lang.String stream2String(java.io.InputStream iStream)
          Returns the contents of the argument InputStream as a String.
static java.io.InputStream string2Stream(java.lang.String iString)
          Returns the stream on the argument string.
static java.lang.String validateArg(java.lang.String arg, java.lang.String permissible, java.lang.String message)
          Verifies that the arg is in the permissible values.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

doCommandArgs

public static void doCommandArgs(java.lang.String[] args,
                                 java.lang.String[] argTags,
                                 java.lang.String[] argVals)
                          throws java.lang.Exception
Checks the command line arguments and merges them with default values for any omitted arguments.

Example Java code:

  public static void main (String args[]) {
  String[] argTags = {"-I", "-O", "-ROW", "-CODE",  "-NAMES", "-UPDATE"};
  String[] argVals = {"", "", "0", "0", "", "no"};
  StringUtil.doCommandArgs(args, argTags, argVals);
  
A call of the doCommandArgs method merges the supplied values in the args array into the default values in the argVals array, using the argTags array to determine the permissible tags and the order of arguments in argVals.

For example, assume that the above main method is in a class named Sample. The following shows a series of calls of Sample, followed by the values that would be in argVals after the call StringUtil.doCommandArgs(args, argTags, argVals).

  Call:  java Sample -ROW 7 -NAMES yes -I /usr/u/smith/input.txt
  Resulting argVals:  {"/usr/u/smith/input.txt", "", "7", "0", "yes", "no"}
    
  Call:  java Sample -O "result.txt" -UPDATE no -CODE "K 7"
  Resulting argVals:  {"", "result.txt", "0", "K 7", "", "no"}
  
Parameters:
args - the string array of user-supplied arguments, as provided in command-line invocation of main
argTags - an array of the legal argument tags, e.g. "-F". (case sensitive)
argVals - an array of the default values of the arguments (or empty strings for arguments with no default)
Throws:
java.lang.Exception - If an argument tag letter is not specifies by the argTags, or the argTags and argVals arrays are not the same length.

isNothing

public static boolean isNothing(java.lang.String val)
Tests whether the argument is null, empty, or all whitespace. This is a convenience method for a common test.
Parameters:
val - a string to be tested for vacuity
Returns:
a boolean indicating the vacuity of val

validateArg

public static java.lang.String validateArg(java.lang.String arg,
                                           java.lang.String permissible,
                                           java.lang.String message)
                                    throws java.lang.IllegalArgumentException
Verifies that the arg is in the permissible values. The "permissible" string contains the permissible keyword values.

Example Java code:

       validateArg("yes", "yes,no,maybe", "Arg must be yse, no, or maybe")
  
Parameters:
arg - a string with the value to be validated
permissible - a string with the valid values. The method simply checks whether the index of arg in permissible is -1.
message - a string that will be included in the exception message
Throws:
java.lang.IllegalArgumentException - Raised if the arg is not in the permissible values

sqlSubstring

public static java.lang.String sqlSubstring(java.lang.String C,
                                            int startArg,
                                            int lengthArg)
                                     throws java.lang.Exception
Returns a substring of the given string. This method uses SQL rules for the FROM and TO values:

         sqlSubstring("abc", S, L)
  

This method is a literal transcription of the rules in the SQL standard, and the variable names are the symbols used in the SQL standard (in caps).

Parameters:
C - a string that is the source for the substring values
startArg - a string that is the initial position of the substring
lengthArg - an int that is the length of the substring
Returns:
a string with the substring result
Throws:
java.lang.Exception - If the end is less than the start

stackTrace2String

public static java.lang.String stackTrace2String(java.lang.Exception e)
Returns a String with the stack trace of the given Exception.
This is an alternative to using e.printStackTrace(), for cases where you want to save the exception info rather than print it.
Parameters:
e - an exception whose stack trace is to be returned
Returns:
a string with the stack trace

entityize

public static java.lang.String entityize(java.lang.String val)
Translates a String containing XML markup characters, (>, <, &, ', and ") to a String with the corresponding entities (&gt;, &lt;, &amp;, &apos;, and &quot;). The deEntityize method does the inverse.
CallResult
  entityize("A>B && C<D") 
  
  "A&gt;B &amp;&amp; C&lt;D"
  
  deEntityize("A&gt;B &amp;&amp; C&lt;D")
  
 "A>B && C<D"
  
Parameters:
val - a string that is to be examined for XML markup
Returns:
a string that is a copy of val with XML markup characters suitably substitutued

deEntityize

public static java.lang.String deEntityize(java.lang.String val)
                                    throws java.lang.Exception
Translates a String containing the five special XML entities (&gt;, &lt;, &amp;, &apos; and &quot;). to a String with the corresponding characters (>, <, &, ', and "). The entityize method does the inverse.
CallResult
  entityize("A>B && C<D") 
  
  "A&gt;B &amp;&amp; C&lt;D"
  
  deEntityize("A&gt;B &amp;&amp; C&lt;D")
  
 "A>B && C<D"
  
Parameters:
val - a string that is to be examined for XML entities.
Returns:
a string that is a copy of val with XML entity characters suitably substituted

stream2String

public static java.lang.String stream2String(java.io.InputStream iStream)
                                      throws java.lang.Exception
Returns the contents of the argument InputStream as a String.
Parameters:
iStream - an InputStream to be returned as a String
Returns:
the contents of the InputStream

string2Stream

public static java.io.InputStream string2Stream(java.lang.String iString)
                                         throws java.lang.Exception
Returns the stream on the argument string.
Parameters:
iString - a String to be returned as a stream
Returns:
the contents of the InputStream

multiply

public static java.lang.String multiply(int times,
                                        java.lang.String seed)
Repeats a given string a given number of times (mainly for test generation). multiply(3, "abc") returns "abcabcabc" multiply(0, "abc") returns "" multiply(n, "") returns "" multiply(null, n) returns null
Parameters:
times - the number of replications
seed - the string that will be replicated to generate the returned string
Returns:
a string with the given number of replications

multiply

public static java.lang.String multiply(java.lang.String seed,
                                        int times)
Repeats a given string a given number of times (mainly for test generation).

multiply(String, int) is simply multiply(int, String), for convenience.


genString

public static java.lang.String genString(int len,
                                         java.lang.String seed)
Generates a string of given length (mainly for test generation). genString(6 "abc") returns "abcabc" genString(5, "abc") returns "abcab" genString(4, "abc") returns "abca" genString(0, "abc") returns "" genString(n, "") returns "" genString(n, null) returns null
Parameters:
len - the length of the returned string
seed - the string that will be replicated to generate the returned string
Returns:
a string of the given length

genString

public static java.lang.String genString(java.lang.String seed,
                                         int len)
Generates a string of given length (mainly for test generation).

genString(String, int) is simply genString(int, String), for convenience.