/*::.
==================================================================================================================================
=================================================¦ Copyright © 2007 Allen Baker ¦=================================================
                                                 +------------------------------+
File:       UString.java
Originator: Allen Baker (2007.01.07 20:30)
LayoutRev:  5
================================================================================================================================== */



/*.
==========================================================================================
Package
------------------------------------------------------------------------------------------ */
package cosmicabyss.com.lib;



/*.
==========================================================================================
Imports
------------------------------------------------------------------------------------------ */
import java.io.*;
import java.util.*;
import java.util.regex.*;
import java.nio.charset.*;
import java.lang.reflect.*;
import java.nio.file.*;



/*::
======================================================================================================================== *//**
This class is intended to act as a full, and more powerful replacement for the methods of Java's String class or as a
source of String-related static utility methods.<P>

The Java String class (String) is final, meaning that you cannot add methods to it or improve it in any way by creating
a subclass of it. This is an annoyance because it forces the user to create a separate String utility class containing
any utility methods the user needs for Strings, and to then switch back and forth between the String class and the
String utility class.<P>

This class provides static methods that are equivalent to all the String class's instance and static methods. In other
words, it replicates the String class's entire API with the caveat that all of String's instance methods are provided as
static methods by UString. And since all the methods are static, they all require a String parameter to operate upon.
However, as an improvement over the String class, this String parameter is generic in all the UString methods. This
means that objects of any class that can be converted into a String can be passed into any of the UString methods.
(UString also makes public the method it uses for converting instances of other classes to Strings.)<P>

uString goes further by providing additional methods not found in the String class. These additional methods greatly
extend the power of UString beyond that of String.<P>

Taken together, the above mentioned characteristics of UString result in a class that can be used as a more powerful
replacement for String's API. Since UString is a utility* class, instances of UString cannot be created. String
variables must be created as instances of Java's String class and then UString can be used to perform all the operations
on them. This limitation of UString is eliminated by another custom class named "XString".<P>

The most obvious differences between this class and the standard Java String class are:<P>
   <BLOCKQUOTE>
      => Because they are all static, the methods of this class require a String parameter to operate upon.<BR>
      => Unlike the String class, this UString class is not final. Therefore, it is possible to add methods to it at any
         Time.<BR>
      => Most of the methods of this class take generic parameters where the corresponding methods of the standard Java
         String class would take concrete parameter types.<BR>
      => While providing exactly the same methods as the String class, this class also offers numerous additional
         Methods that extend the functionality that can be applied to Strings.<BR>
      => This class provides case-insensitive versions of many of the String class methods. These are named by appending
         "IgnoreCase" to the end of the method name.
   </BLOCKQUOTE>

<P>
   <DL>
      <DT>
         <B>
            Example usage:
         </B>
         <DD>
            <BLOCKQUOTE>
               <PRE id="unindent">
                  no example provided
               </PRE>
            </BLOCKQUOTE>
         </DD>
      </DT>
      <DT>
         <B>
            View Source:
         </B>
         <DD>
            <A href="UString.java.html">
               uString.java
            </A>
         </DD>
      </DT>
      <DT>
         <B>
            Author:
         </B>
         <DD>
            <A href="mailto:sourcecode.v01@cosmicabyss.com">
               Allen Baker
            </A>
         </DD>
      </DT>
   </DL>
*//*
======================================================================================================================== */
public class UString
   {



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Private  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*.
   ==========================================================================================
   Class Constants
      DFLT_WORD_WRAP_REGEX:
         Template for word wrapping by using a regular expression
   ------------------------------------------------------------------------------------------ */
   private static final String  DFLT_WORD_WRAP_REGEX  = "(\\S\\S{%LINEWIDTH%,}|.{1,%LINEWIDTH%})(\\s+|$)";
   /*.
   ==========================================================================================
   Class variables
      cPatternMap:
         Stores already compiled regular expressions in a map for quick retrieval.
      cRecurseCounter:
         Is used by indexAfterDelimitedSpan() to stop infinite recursion in a controlled
         manner.
   ------------------------------------------------------------------------------------------ */
   private static HashMap<String,Pattern>  cPatternMap     = new HashMap<String,Pattern>();
   private static int                      cRecurseCounter = 0;



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method does the actual word wrapping by breaking the input String into separate Strings using
   the specified Pattern.

   <P><B>Implementation: </B><A HREF="UString.java.html#000">View source</A>

   @return
      An ArrayList into which this method puts the lines it generates from the String.

   @param
      pStr is the String that is word wrapped.
   @param
      pPattern is the compiled regualar expression that is used to break the String into multiple word
      wrapped Strings.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static <Type1> ArrayList<String> wordWrappedLines
      (
      Type1    pStr,
      Pattern  pPattern
      )
      {
      String  str = UString.toString(pStr);

      ArrayList<String>  lines   = new ArrayList<String>();
      Matcher            matcher = pPattern.matcher(str);
      while (matcher.find())
         {
         lines.add(matcher.group());
         }
      return lines;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method compiles a regular expression for word wrapping at the specified line length into a
   Pattern.

   <P><B>Implementation: </B><A HREF="UString.java.html#001">View source</A>

   @return
      A Pattern for word wrapping at the specified line length into a Pattern.

   @param
      pLineWidth is the line length that a Pattern will be compiled for.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static Pattern wordWrapPattern(int pLineWidth)
      {
      String  regEx = DFLT_WORD_WRAP_REGEX.replace
         (
         "%LINEWIDTH%",UString.toString(pLineWidth)
         );
      Pattern  pttrn = cPatternMap.get(regEx);
      if (pttrn == null)
         {
         pttrn = Pattern.compile(regEx);
         cPatternMap.put(regEx,pttrn);
         }
      return pttrn;
      }



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Inner Classes  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*::
   ======================================================================================================================== *//**
   This class implements the UCapitalizer interface and provides a method for basicEnglish capitalization.
   *//*
   ======================================================================================================================== */
   public static class BasicEnglishCapitalizer implements UCapitalizer
      {



      /*:                                    
      ====================================================================================================
      [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
      ==================================================================================================== *//**
      This method does basic English capitalization of the String representation of pStr. I.e., the first
      word in each sentence is capitalized.<P>

      Caveat: The first word of the String representation of pStr is considered to be the first word of a
              Sentence.

      <P><B>Implementation: </B><A HREF="UString.java.html#002">View source</A>

      </A>

      </A>

      @return
         A new String that is equivalent to the String representation of pStr but with capitalization.

      @param
         pStr is the primitive type value or object whose String representation will be capitalized.
      *//*
      ---------------------------------------------------------------------------------------------------- */
      public <Type1> String capitalize(Type1 pStr)
         {
         String   str = UString.toString(pStr);
         /*.
         ==========================================================================================
         Capitalize stand alone I
         ------------------------------------------------------------------------------------------ */
         str = str.replace(" i ", " I ");
         /*.
         ==========================================================================================
         This does the capitalization of first words in sentences
         ------------------------------------------------------------------------------------------ */
         char[]   strChrs    = str.toCharArray();
         boolean  mayNeedCap = false;
         boolean  needCap    = true;
         for (int i=0; i<strChrs.length; i++)
            {
            if ( ! Character.isWhitespace(strChrs[i]))
               {
               if (needCap)
                  {
                  strChrs[i] = Character.toUpperCase(strChrs[i]);
                  mayNeedCap = false;
                  needCap    = false;
                  }
               if (UString.containsChar(".?!",strChrs[i]))
                  {
                  mayNeedCap = true;
                  }
               else
                  {
                  mayNeedCap = false;
                  }
               }
            else
               {
               if (mayNeedCap)
                  {
                  mayNeedCap = false;
                  needCap    = true;
                  }
               }
            }
         /*.
         ==========================================================================================
         Now we're done
         ------------------------------------------------------------------------------------------ */
         return new String(strChrs);
         }



      }  // class BasicEnglishCapitalizer



   /*::
   ======================================================================================================================== *//**
   This class implements the UCapitalizer interface and provides a method for capitalizing the first letter of each word.
   *//*
   ======================================================================================================================== */
   public static class CapitalizeAllWords implements UCapitalizer
      {



      /*:                                    
      ====================================================================================================
      [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
      ==================================================================================================== *//**
      This method does capitalization of the String representation of pStr. I.e., each word in each
      sentence is capitalized.<P>

      <P><B>Implementation: </B><A HREF="UString.java.html#003">View source</A>

      </A>

      </A>

      @return
         A new String that is equivalent to the String representation of pStr but with capitalization.

      @param
         pStr is the primitive type value or object whose String representation will be capitalized.
      *//*
      ---------------------------------------------------------------------------------------------------- */
      public <Type1> String capitalize(Type1 pStr)
         {
         String   str        = UString.toString(pStr);
         char[]   strChrs    = str.toCharArray();
         boolean  needCap    = true;
         for (int i=0; i<strChrs.length; i++)
            {
            if ( ! Character.isWhitespace(strChrs[i]))
               {
               if (needCap)
                  {
                  strChrs[i] = Character.toUpperCase(strChrs[i]);
                  needCap    = false;
                  }
               }
            else
               {
               needCap = true;
               }
            }
         return new String(strChrs);
         }



      }  // class CapitalizeAllWords



   /*::
   ======================================================================================================================== *//**
   This class implements the UCapitalizer interface and provides a method for basic English capitalization.
   *//*
   ======================================================================================================================== */
   public static class BasicEnglishCapitalizerNoFirst implements UCapitalizer
      {



      /*:                                    
      ====================================================================================================
      [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
      ==================================================================================================== *//**
      This method does basic English capitalization of the String representation of pStr. I.e., the first
      word in each sentence is capitalized.<P>

      Caveat: The first word of the String representation of pStr is NOT considered to be the first word
              Of a sentence.

      <P><B>Implementation: </B><A HREF="UString.java.html#004">View source</A>

      </A>

      </A>

      @return
         A new String that is equivalent to the String representation of pStr but with capitalization.

      @param
         pStr is the primitive type value or object whose String representation will be capitalized.
      *//*
      ---------------------------------------------------------------------------------------------------- */
      public <Type1> String capitalize(Type1 pStr)
         {
         String   str = UString.toString(pStr);
         /*.
         ==========================================================================================
         Capitalize stand alone I
         ------------------------------------------------------------------------------------------ */
         str = str.replace(" i ", " I ");
         /*.
         ==========================================================================================
         This does the capitalization of first words in sentences
         ------------------------------------------------------------------------------------------ */
         char[]   strChrs    = str.toCharArray();
         boolean  mayNeedCap = false;
         boolean  needCap    = false;
         for (int i=0; i<strChrs.length; i++)
            {
            if ( ! Character.isWhitespace(strChrs[i]))
               {
               if (needCap)
                  {
                  strChrs[i] = Character.toUpperCase(strChrs[i]);
                  mayNeedCap = false;
                  needCap    = false;
                  }
               if (UString.containsChar(".?!",strChrs[i]))
                  {
                  mayNeedCap = true;
                  }
               else
                  {
                  mayNeedCap = false;
                  }
               }
            else
               {
               if (mayNeedCap)
                  {
                  mayNeedCap = false;
                  needCap    = true;
                  }
               }
            }
         return new String(strChrs);
         }



      }  // class BasicEnglishCapitalizerNoFirst



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Public Static Methods  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  The String API  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#005">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int length(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.length();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#006">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isEmpty(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.isEmpty();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#007">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> char charAt(Type1 pStr, int index)
      {
      String  str = UString.toString(pStr);
      return str.charAt(index);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#008">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int codePointAt(Type1 pStr, int index)
      {
      String  str = UString.toString(pStr);
      return str.codePointAt(index);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#009">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int codePointBefore(Type1 pStr, int index)
      {
      String  str = UString.toString(pStr);
      return str.codePointBefore(index);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#010">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int codePointCount(Type1 pStr, int beginIndex, int endIndex)
      {
      String  str = UString.toString(pStr);
      return str.codePointCount(beginIndex,endIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#011">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int offsetByCodePoints(Type1 pStr, int index, int codePointOffset)
      {
      String  str = UString.toString(pStr);
      return str.offsetByCodePoints(index,codePointOffset);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#012">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> void getChars(Type1 pStr, int srcBegin, int srcEnd, char dst[], int dstBegin)
      {
      String  str = UString.toString(pStr);
      str.getChars(srcBegin,srcEnd,dst,dstBegin);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#013">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> byte[] getBytes(Type1 pStr, Type2 charsetName) throws UnsupportedEncodingException
      {
      String  str  = UString.toString(pStr);
      String  name = UString.toString(charsetName);
      return str.getBytes(name);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#014">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> byte[] getBytes(Type1 pStr, Charset charset)
      {
      String  str = UString.toString(pStr);
      return str.getBytes(charset);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#015">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> byte[] getBytes(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.getBytes();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#016">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean equals(Type1 pStr, Object anObject)
      {
      String  str = UString.toString(pStr);
      return str.equals(anObject);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#017">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean contentEquals(Type1 pStr, StringBuffer sb)
      {
      String  str = UString.toString(pStr);
      return str.contentEquals(sb);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#018">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean contentEquals(Type1 pStr, CharSequence cs)
      {
      String  str = UString.toString(pStr);
      return str.contentEquals(cs);
      }
   public static <Type1, Type2> boolean contentEquals(Type1 pStr, Type2 pCs)
      {
      String  str = UString.toString(pStr);
      String  cs  = UString.toString(pCs);
      return str.contentEquals(cs);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#019">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean equalsIgnoreCase(Type1 pStr, Type2 anotherString)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(anotherString);
      return str.equalsIgnoreCase(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#020">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int compareTo(Type1 pStr, Type2 anotherString)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(anotherString);
      return str.compareTo(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#021">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int compareToIgnoreCase(Type1 pStr, Type2 other)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.compareToIgnoreCase(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#022">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean regionMatches(Type1 pStr, int toffset, Type2 other, int ooffset, int len)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.regionMatches(toffset,oth,ooffset,len);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#023">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean regionMatches(Type1 pStr, boolean ignoreCase, int toffset,
      Type1 other, int ooffset, int len)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.regionMatches(ignoreCase,toffset,oth,ooffset,len);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#024">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean startsWith(Type1 pStr, Type2 pPrefix, int toffset)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(pPrefix);
      return str.startsWith(oth,toffset);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#025">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean startsWith(Type1 pStr, Type2 pPrefix)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(pPrefix);
      return str.startsWith(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#026">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean endsWith(Type1 pStr, Type2 suffix)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(suffix);
      return str.endsWith(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#027">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int hashCode(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.hashCode();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#028">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int indexOf(Type1 pStr, int ch)
      {
      String  str = UString.toString(pStr);
      return str.indexOf(ch);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#029">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int indexOf(Type1 pStr, int ch, int fromIndex)
      {
      String  str = UString.toString(pStr);
      return str.indexOf(ch,fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#030">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int lastIndexOf(Type1 pStr, int ch)
      {
      String  str = UString.toString(pStr);
      return str.lastIndexOf(ch);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#031">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int lastIndexOf(Type1 pStr, int ch, int fromIndex)
      {
      String  str = UString.toString(pStr);
      return str.lastIndexOf(ch,fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#032">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int indexOf(Type1 pStr, Type2 other)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.indexOf(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#033">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int indexOf(Type1 pStr, Type2 other, int fromIndex)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.indexOf(oth,fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#034">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int lastIndexOf(Type1 pStr, Type2 other)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.lastIndexOf(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#035">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int lastIndexOf(Type1 pStr, Type2 other, int fromIndex)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.lastIndexOf(oth,fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#036">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String substring(Type1 pStr, int beginIndex)
      {
      String  str = UString.toString(pStr);
      return str.substring(beginIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#037">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String substring(Type1 pStr, int beginIndex, int endIndex)
      {
      String  str = UString.toString(pStr);
      return str.substring(beginIndex,endIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#038">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> CharSequence subSequence(Type1 pStr, int beginIndex, int endIndex)
      {
      String  str = UString.toString(pStr);
      return str.subSequence(beginIndex,endIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#039">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String concat(Type1 pStr, Type2 other)
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);
      return str.concat(oth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#040">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String replace(Type1 pStr, char oldChar, char newChar)
      {
      String  str = UString.toString(pStr);
      return str.replace(oldChar,newChar);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#041">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean matches(Type1 pStr, Type2 regex)
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);
      return str.matches(rgx);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#042">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean contains(Type1 pStr, CharSequence s)
      {
      String  str = UString.toString(pStr);
      return str.contains(s);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#043">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean contains(Type1 pStr, Type2 pS)
      {
      String  str = UString.toString(pStr);
      String  s   = UString.toString(pS);
      return str.contains(s);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces instances of substrings matching the regular expression in regex with a string
   generated from the regular expression in replacement.<P>

   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#044">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> String replaceFirst(Type1 pStr, Type2 regex, Type3 replacement)
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);
      String  rpl = UString.toString(replacement);
      return str.replaceFirst(rgx,rpl);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces instances of substrings matching the regular expression in regex with a string
   generated from the regular expression in replacement.<P>

   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#045">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> String replaceAll(Type1 pStr, Type2 regex, Type3 replacement)
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);
      String  rpl = UString.toString(replacement);
      return str.replaceAll(rgx,rpl);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#046">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String replace(Type1 pStr, CharSequence target, CharSequence replacement)
      {
      String  str = UString.toString(pStr);
      return str.replace(target,replacement);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#047">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String[] split(Type1 pStr, Type2 regex, int limit)
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);
      return str.split(rgx,limit);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#048">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String[] split(Type1 pStr, Type2 regex)
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);
      return str.split(rgx);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#049">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String toLowerCase(Type1 pStr, Locale locale)
      {
      String  str = UString.toString(pStr);
      return str.toLowerCase(locale);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#050">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String toLowerCase(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.toLowerCase();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#051">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String toUpperCase(Type1 pStr, Locale locale)
      {
      String  str = UString.toString(pStr);
      return str.toUpperCase(locale);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#052">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String toUpperCase(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.toUpperCase();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#053">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String trim(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.trim();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#054">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> char[] toCharArray(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.toCharArray();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#055">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String format(Type1 format, Object... args)
      {
      String  fmt = UString.toString(format);
      return String.format(fmt,args);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#056">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String format(Locale l, Type1 format, Object... args)
      {
      String  fmt = UString.toString(format);
      return String.format(l,fmt,args);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#057">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(Object obj)
      {
      return String.valueOf(obj);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#058">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(char data[])
      {
      return String.valueOf(data);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#059">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(char data[], int offset, int count)
      {
      return String.valueOf(data,offset,count);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#060">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String copyValueOf(char data[], int offset, int count)
      {
      return String.copyValueOf(data,offset,count);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#061">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String copyValueOf(char data[])
      {
      return String.copyValueOf(data);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#062">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(boolean b)
      {
      return String.valueOf(b);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#063">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(char c)
      {
      return String.valueOf(c);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#064">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(int i)
      {
      return String.valueOf(i);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#065">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(long l)
      {
      return String.valueOf(l);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#066">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(float f)
      {
      return String.valueOf(f);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#067">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String valueOf(double d)
      {
      return String.valueOf(d);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#068">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String intern(Type1 pStr)
   {
   String  str = UString.toString(pStr);
   return str.intern();
   }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  The Extensions  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method adds the string representation of pPrefix to the beginning of the string representation
   of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#069">View source</A>

   @return
      A new string comopsed as pPrefix + pStr

   @param
      pStr is the Object whose String representation is given a prefix.
   @param
      pPrefix is the Object whose String representation is added to the beginning of the string
      representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String appendPrefix(Type1 pStr, Type2 pPrefix)
      {
      String  str    = UString.toString(pStr);
      String  prefix = UString.toString(pPrefix);
      return prefix += str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method adds the string representation of pSuffix to the endning of the string representation
   of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#070">View source</A>

   @return
      A new string comopsed as pStr + pSuffix

   @param
      pStr is the Object whose String representation is given a suffix.
   @param
      pSuffix is the Object whose String representation is added to the endning of the string
      representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String appendSuffix(Type1 pStr, Type2 pSuffix)
      {
      String  str    = UString.toString(pStr);
      String  suffix = UString.toString(pSuffix);
      return str += suffix;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a String of the specified length and filled with the specified char.

   <P><B>Implementation: </B><A HREF="UString.java.html#071">View source</A>

   @return
      A new String containing pLength pFillChars

   @param
      pLength is the length of the String to be created.
   @param
      pFillChar is the the character to be stored in every character position in the String.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String fill(int pLength, char pFillChar)
      {
      char[]  charArray = new char[pLength];
      Arrays.fill(charArray, pFillChar);
      return new String(charArray);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a String representation of pStr.<P>

   If pStr is a File, this method creates a String containing the content of the file decoded from
   bytes to characters using the platform's default charset.<P>

   Char[] and byte[] are handled differently than all other arrays of primitive types.<P>

   A char[] is converted directly into a String where each char[] element is represented as one
   character. So a char[] containing these elements: 'a', 'b', 'c' would be converted to this String:
   "abc".<P>

   A byte[] is converted directly into a String where each byte[] element is represented as two
   characters. So a byte[] containing these elements: (97 << 4) & 98, (99 << 4) & 100 would be
   converted to this String: "abcd".<P>

   All other arrays of primitive types are represented as comma separated lists of their elements. For
   example, an int[] containing these elements: 1, 2, 3 would be converted to this String: [1, 2, 3]

   <P><B>Implementation: </B><A HREF="UString.java.html#072">View source</A>

   @return
      A new String containing the String representation of pStr

   @param
      pStr is the primitive type value or object whose String representation will be returned. If pStr
      is a File, the entire content of the File is returned as a String.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String toString(Type1 pStr)
      {
      /*.
      ==========================================================================================
      Low-hanging fruit
      ------------------------------------------------------------------------------------------ */
      if (pStr == null)
         {
         return null;
         }
      if (pStr instanceof String)
         {
         return (String)pStr;
         }
      if (pStr instanceof XString)
         {
         return ((XString)pStr).toString();
         }
      if (pStr instanceof StringBuffer)
         {
         return ((StringBuffer)pStr).toString();
         }
      if (pStr instanceof File)
         {
         try
            {
            String  pathName = ((File)pStr).getCanonicalPath();
            byte[]  encoded  = Files.readAllBytes(Paths.get(pathName));
            return new String(encoded);
            }
         catch (Exception e)
            {
            return "Ustring.toString(File)_Open_Error";
            }
         }
      /*.
      ==========================================================================================
      Arrays
      ------------------------------------------------------------------------------------------ */
      if (pStr.getClass().isArray())
         {
         if (pStr instanceof char[])
            {
            return (new String((char[])pStr));
            }
         if (pStr instanceof byte[])
            {
            return (new String((byte[])pStr));
            }
         if (pStr instanceof boolean[])
            {
            return (Arrays.toString((boolean[])pStr));
            }
         if (pStr instanceof double[])
            {
            return (Arrays.toString((double[])pStr));
            }
         if (pStr instanceof float[])
            {
            return (Arrays.toString((float[])pStr));
            }
         if (pStr instanceof int[])
            {
            return (Arrays.toString((int[])pStr));
            }
         if (pStr instanceof short[])
            {
            return (Arrays.toString((short[])pStr));
            }
         if (pStr instanceof long[])
            {
            return (Arrays.toString((long[])pStr));
            }
         }
      /*.
      ==========================================================================================
      Everything else
      ------------------------------------------------------------------------------------------ */
      try
         {
         Method methodToFind = null;
         /*.
         ==========================================================================================
         If String has a valueOf(pStr) method
         ------------------------------------------------------------------------------------------ */
         Class<?>[]  args = {pStr.getClass()};
         methodToFind = String.class.getMethod("valueOf", args);
         if (methodToFind != null)
            {
            return String.valueOf(pStr);
            }
         /*.
         ==========================================================================================
         If pStr has a toString() method
         ------------------------------------------------------------------------------------------ */
         methodToFind = pStr.getClass().getMethod("toString", (Class<?>[]) null);
         if (methodToFind != null)
            {
            return pStr.toString();
            }
         }
      catch (Exception e)
         {
         }
      /*.
      ==========================================================================================
      Last resort
      ------------------------------------------------------------------------------------------ */
      return ((Object)pStr).toString();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates an String[] representation of pStr[].

   <P><B>Implementation: </B><A HREF="UString.java.html#073">View source</A>

   @return
      A new String[] containing the String representation of the elements of pStr[]

   @param
      pStr is the array of primitive type values or objects that are converted into Strings
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String[] toStringArray(Type1[] pStr)
      {
      String[]  result = new String[pStr.length];
      for (int i=0; i<pStr.length; i++)
         {
         result[i] = UString.toString(pStr[i]);
         }
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates an String[] representation of pStr[].

   <P><B>Implementation: </B><A HREF="UString.java.html#074">View source</A>

   @return
      A new String[] containing the String representation of the elements of pStr[]

   @param
      pStr is the array of primitive type values or objects that are converted into Strings
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String[] toStringArray(List<Type1> pStr)
      {
      Object[]  a = pStr.toArray();
      return toStringArray(a);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method converts the parameter to its no-case representation.

   <P><B>Implementation: </B><A HREF="UString.java.html#075">View source</A>

   @return
      A reference to a new String in a no-case representation.

   @param
      pStr is the String that is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String noCase(String pStr)
      {
      if (pStr == null)
         {
         return null;
         }
      else
         {
         return pStr.toUpperCase();
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method converts the parameter to its no-case representation.

   <P><B>Implementation: </B><A HREF="UString.java.html#076">View source</A>

   @return
      A new char in a no-case representation.

   @param
      pChar is the Char that is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static char noCase(char pChar)
      {
      return Character.toUpperCase(pChar);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method converts the parameter to its no-case representation.

   <P><B>Implementation: </B><A HREF="UString.java.html#077">View source</A>

   @return
      A new StringBuffer in a no-case representation.

   @param
      pBuf is the StringBuffer that is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static StringBuffer noCase(StringBuffer pBuf)
      {
      if (pBuf == null)
         {
         return null;
         }
      else
         {
         return new StringBuffer(UString.noCase(UString.toString(pBuf)));
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method converts the parameter to its no-case representation.

   <P><B>Implementation: </B><A HREF="UString.java.html#078">View source</A>

   @return
      A new String in a no-case representation.

   @param
      pSeq is the CharSequence that is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String noCase(CharSequence pSeq)
      {
      if (pSeq == null)
         {
         return null;
         }
      else
         {
         return UString.noCase(UString.toString(pSeq));
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method converts the parameter to its no-case representation.

   <P><B>Implementation: </B><A HREF="UString.java.html#079">View source</A>

   @return
      A new int in a no-case representation.

   @param
      pCodePoint is the int that is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static int noCase(int pCodePoint)
      {
      return Character.toUpperCase(pCodePoint);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method converts the parameter to its no-case representation.

   <P><B>Implementation: </B><A HREF="UString.java.html#080">View source</A>

   @return
      A new whatever in a no-case representation.

   @param
      pStr is the Object whose String representation is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String noCase(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return UString.noCase(str);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns true if, and only if, the String is either null or empty (i.e. "").
      <BLOCKQUOTE>
         Note: The isEmpty() method in Java's standard String class returns true if, and only if, the
               String is <B><I>not null</I></B> and is empty (i.e. ""); otherwise, it returns false. If
               it is passed a null reference, it will throw a NullPointerException.
      </BLOCKQUOTE>


   <P><B>Implementation: </B><A HREF="UString.java.html#081">View source</A>

   @return
      This method returns true if, and only if, the String is either null or empty (i.e. "");
      otherwise, it returns false.

   @param
      pStr is the Object whose String representation is tested.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isNullOrEmpty(Type1 pStr)
      {
      return ((pStr == null) || UString.toString(pStr).isEmpty());
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns true if, and only if, the String is either null, or empty (i.e. ""),.or contains
   only whitespace.
      <BLOCKQUOTE>
         Note: The isEmpty() method in Java's standard String class returns true if, and only if, the
               String is <B><I>not null</I></B> and is empty (i.e. ""); otherwise, it returns false. If
               it is passed a null reference, it will throw a NullPointerException.
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#082">View source</A>

   @return
      This method returns true if, and only if, the String is either null, or empty (i.e. ""),.or
      contains only whitespace; otherwise, it returns false.

   @param
      pStr is the Object whose String representation is tested.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isNullOrEmptyOrWhitespace(Type1 pStr)
      {
      return ((pStr == null) || UString.toString(pStr).trim().isEmpty());
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns true if, and only if, the String is not null, and not empty (i.e. ""),.but
   contains only whitespace.
      <BLOCKQUOTE>
         Note: The isEmpty() method in Java's standard String class returns true if, and only if, the
               String is <B><I>not null</I></B> and is empty (i.e. ""); otherwise, it returns false. If
               it is passed a null reference, it will throw a NullPointerException.
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#083">View source</A>

   @return
      This method returns true if, and only if, the String is not null, and not empty (i.e. ""),.but
      contains only whitespace; otherwise, it returns false.

   @param
      pStr is the Object whose String representation is tested.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isNonEmptyWhitespace(Type1 pStr)
      {
      return ((pStr != null) && (! UString.toString(pStr).isEmpty()) && UString.toString(pStr).trim().isEmpty());
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method decides if all the letters in a string are upper case or not. Digits and all other
   non-letters are ignored and do not effect the outcome of this method().

   <P><B>Implementation: </B><A HREF="UString.java.html#084">View source</A>

   @return
      This method returns true if all the letters in the string are upper case, otherwise, it returns
      false.

   @param
      pStr is the object whose string representation is tested.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isAllUpperCase(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      for (int idx = 0; idx < str.length(); idx++)
         {
         if (Character.isLetter(str.charAt(idx)) && Character.isLowerCase(str.charAt(idx))) return false;
         }
      return true;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method decides if all the letters in a string are lower case or not. Digits and all other
   non-letters are ignored and do not effect the outcome of this method().

   <P><B>Implementation: </B><A HREF="UString.java.html#085">View source</A>

   @return
      This method returns true if all the letters in the string are lower case, otherwise, it returns
      false.

   @param
      pStr is the object whose string representation is tested.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isAllLowerCase(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      for (int idx = 0; idx < str.length(); idx++)
         {
         if (Character.isLetter(str.charAt(idx)) && Character.isUpperCase(str.charAt(idx))) return false;
         }
      return true;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns a String containing the SET of characters that are in the String representation
   of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#086">View source</A>

   @return
      A reference to a new String containing the SET of characters that are in the String
      representation of pStr.

   @param
      pStr is the Object whose String representation is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String charSet(Type1 pStr)
      {
      String  str = UString.toString(pStr);

      char[]              strChrs = str.toCharArray();
      HashSet<Character>  charSet = new HashSet<Character>();
      for (int i=0; i<strChrs.length; i++)
         {
         charSet.add(new Character(strChrs[i]));
         }
      StringBuffer  sb = new StringBuffer(charSet.size());
      for (Character c : charSet)
         {
         sb.append(c.charValue());
         }
      return sb.toString();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns a String containing the SET of characters that are in the String representation
   of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#087">View source</A>

   @return
      A reference to a new String containing the SET of characters that are in the String
      representation of pStr.

   @param
      pStr is the Object whose String representation is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String charSetIgnoreCase(Type1 pStr)
      {
      String  str = UString.noCase(UString.toString(pStr));

      return UString.charSet(str);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes a leading and trailing substring from the String representation of pStr.
      <BLOCKQUOTE>
         For example, if a this method were called as follows:
            <BLOCKQUOTE>
               <PRE id="unindent">
                  trim("XX-some other chars-xx", "XX")
               </PRE>
            </BLOCKQUOTE>
        Then this method would return a String comprising this sequence of characters:
           <BLOCKQUOTE>
              <PRE id="unindent">
                  "-some other chars-xx"
              </PRE>
           </BLOCKQUOTE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#088">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading and
      trailing substring removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pPrefixSuffix is the Object whose String representation is the substring that will be trimmed
      from the left and right of the String representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trim(Type1 pStr, Type2 pPrefixSuffix)
      {
      String  result = UString.toString(pStr);
      result = UString.trimLeft(result, pPrefixSuffix);
      result = UString.trimRight(result, pPrefixSuffix);
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes a leading and trailing substring from the String representation of pStr,
   ignoring case.
      <BLOCKQUOTE>
         For example, if a this method were called as follows:
            <BLOCKQUOTE>
               <PRE id="unindent">
                  trimIgnoreCase("XX-some other chars-xx", "XX")
               </PRE>
            </BLOCKQUOTE>
        Then this method would return a String comprising this sequence of characters:
           <BLOCKQUOTE>
              <PRE id="unindent">
                  "-some other chars-"
              </PRE>
           </BLOCKQUOTE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#089">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading and
      trailing substring removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pPrefixSuffix is the Object whose String representation is the substring that will be trimmed
      from the left and right of the String representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimIgnoreCase(Type1 pStr, Type2 pPrefixSuffix)
      {
      String  result = UString.toString(pStr);
      result = UString.trimLeftIgnoreCase(result, pPrefixSuffix);
      result = UString.trimRightIgnoreCase(result, pPrefixSuffix);
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the characters that are in a character set from the beginning and the end of the
   String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#090">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading and
      trailing character set characters removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pCharset is the Object whose String representation is used as the set of characters to remove.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimCharset(Type1 pStr, Type2 pCharset)
      {
      String  result = UString.toString(pStr);
      result = UString.trimLeftCharset(result, pCharset);
      result = UString.trimRightCharset(result, pCharset);
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the characters that are in a character set from the beginning and the end of the
   String representation of pStr, ignoring case.

   <P><B>Implementation: </B><A HREF="UString.java.html#091">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading and
      trailing character set characters removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pCharset is the Object whose String representation is used as the set of characters to remove.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimCharsetIgnoreCase(Type1 pStr, Type2 pCharset)
      {
      String  result = UString.toString(pStr);
      result = UString.trimLeftCharsetIgnoreCase(result, pCharset);
      result = UString.trimRightCharsetIgnoreCase(result, pCharset);
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the characters that are in a character set from the beginning of the String
   representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#092">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading
      character set characters removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pCharset is the Object whose String representation is used as the set of characters to remove.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimLeftCharset(Type1 pStr, Type2 pCharset)
      {
      String        str     = UString.toString(pStr);
      String        charset = UString.toString(pCharset);
      StringBuffer  c       = new StringBuffer();
      int           i       = 0;
      /*.
      ==========================================================================================
      Skip past the whitespace
      ------------------------------------------------------------------------------------------ */
      for (i=0; i<str.length(); i++)
         {
         boolean  charIsInCharset  = (charset.indexOf(str.charAt(i)) != (-1));
         if ( ! charIsInCharset) break;
         }
      /*.
      ==========================================================================================
      Copy what's left of the string
      ------------------------------------------------------------------------------------------ */
      for (; i<str.length(); i++)
         {
         c.append(str.charAt(i));
         }
      /*.
      ==========================================================================================
      Return it as a String
      ------------------------------------------------------------------------------------------ */
      return new String(c);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the characters that are in a character set from the beginning of the String
   representation of pStr, ignoring case.

   <P><B>Implementation: </B><A HREF="UString.java.html#093">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading
      character set characters removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pCharset is the Object whose String representation is used as the set of characters to remove.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimLeftCharsetIgnoreCase(Type1 pStr, Type2 pCharset)
      {
      String        str     = UString.toString(pStr);
      String        charset = UString.toString(pCharset);
      StringBuffer  c       = new StringBuffer();
      int           i       = 0;
      /*.
      ==========================================================================================
      Skip past the whitespace
      ------------------------------------------------------------------------------------------ */
      for (i=0; i<str.length(); i++)
         {
         boolean  charIsInCharset  = (UString.indexOfIgnoreCase(charset, str.charAt(i)) != (-1));
         if ( ! charIsInCharset) break;
         }
      /*.
      ==========================================================================================
      Copy what's left of the string
      ------------------------------------------------------------------------------------------ */
      for (; i<str.length(); i++)
         {
         c.append(str.charAt(i));
         }
      /*.
      ==========================================================================================
      Return it as a String
      ------------------------------------------------------------------------------------------ */
      return new String(c);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the characters that are in a character set from the end of the String
   representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#094">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the trailing
      character set characters removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pCharset is the Object whose String representation is used as the set of characters to remove.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimRightCharset(Type1 pStr, Type2 pCharset)
      {
      String        str     = UString.toString(pStr);
      String        charset = UString.toString(pCharset);
      StringBuffer  c       = new StringBuffer();
      int           i       = 0;
      int           j       = 0;
      /*.
      ==========================================================================================
      Skip past the whitespace
      ------------------------------------------------------------------------------------------ */
      for (i=str.length(); i>0; i--)
         {
         boolean  charIsInCharset  = (charset.indexOf(str.charAt(i - 1)) != (-1));
         if ( ! charIsInCharset) break;
         }
      /*.
      ==========================================================================================
      Copy what's left of the string
      ------------------------------------------------------------------------------------------ */
      for (j=0; j<i; j++)
         {
         c.append(str.charAt(j));
         }
      /*.
      ==========================================================================================
      Return it as a String
      ------------------------------------------------------------------------------------------ */
      return new String(c);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the characters that are in a character set from the end of the String
   representation of pStr, ignoring case.

   <P><B>Implementation: </B><A HREF="UString.java.html#095">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the trailing
      character set characters removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pCharset is the Object whose String representation is used as the set of characters to remove.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimRightCharsetIgnoreCase(Type1 pStr, Type2 pCharset)
      {
      String        str     = UString.toString(pStr);
      String        charset = UString.toString(pCharset);
      StringBuffer  c       = new StringBuffer();
      int           i       = 0;
      int           j       = 0;
      /*.
      ==========================================================================================
      Skip past the whitespace
      ------------------------------------------------------------------------------------------ */
      for (i=str.length(); i>0; i--)
         {
         boolean  charIsInCharset  = (UString.indexOfIgnoreCase(charset, str.charAt(i - 1)) != (-1));
         if ( ! charIsInCharset) break;
         }
      /*.
      ==========================================================================================
      Copy what's left of the string
      ------------------------------------------------------------------------------------------ */
      for (j=0; j<i; j++)
         {
         c.append(str.charAt(j));
         }
      /*.
      ==========================================================================================
      Return it as a String
      ------------------------------------------------------------------------------------------ */
      return new String(c);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the whitespace from the beginning of the String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#096">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading
      whitespace removed.

   @param
      pStr is the Object whose String representation is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String trimLeft(Type1 pStr)
      {
      String        str = UString.toString(pStr);
      StringBuffer  c   = new StringBuffer();
      int           i   = 0;
      /*.
      ==========================================================================================
      Skip past the whitespace
      ------------------------------------------------------------------------------------------ */
      for (i=0; i<str.length(); i++)
         {
         if ( ! Character.isWhitespace(str.charAt(i))) break;
         }
      /*.
      ==========================================================================================
      Copy what's left of the string
      ------------------------------------------------------------------------------------------ */
      for (; i<str.length(); i++)
         {
         c.append(str.charAt(i));
         }
      /*.
      ==========================================================================================
      Return it as a String
      ------------------------------------------------------------------------------------------ */
      return new String(c);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes a leading substring from the String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#097">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading
      substring removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pPrefix is the substring that will be trimmed from the String representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimLeft(Type1 pStr, Type2 pPrefix)
      {
      String  str = UString.toString(pStr);
      String  pfx = UString.toString(pPrefix);

      if (str.startsWith(pfx))
         {
         return str.substring(pfx.length(), str.length());
         }
      return str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes a leading substring from the String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#098">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading
      substring removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      pPrefix is the substring that will be trimmed from the String representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimLeftIgnoreCase(Type1 pStr, Type2 pPrefix)
      {
      String  str = UString.toString(pStr);
      String  pfx = UString.toString(pPrefix);

      String  tmp = UString.trimLeft
         (
         UString.noCase(str),UString.noCase(pfx)
         );
      if (tmp.length() != str.length())
         {
         returnb>
            (
            str.substring(pfx.length(),str.length())
            );
         }
      else
         {
         return str;
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the whitespace from the end of the String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#099">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the trailing
      whitespace removed.

   @param
      pStr is the Object whose String representation is operated on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String trimRight(Type1 pStr)
      {
      String        str = UString.toString(pStr);
      StringBuffer  c   = new StringBuffer();
      int           i   = 0;
      int           j   = 0;
      /*.
      ==========================================================================================
      Skip past the whitespace
      ------------------------------------------------------------------------------------------ */
      for (i=str.length(); i>0; i--)
         {
         if ( ! Character.isWhitespace(str.charAt(i-1))) break;
         }
      /*.
      ==========================================================================================
      Copy what's left of the string
      ------------------------------------------------------------------------------------------ */
      for (j=0; j<i; j++)
         {
         c.append(str.charAt(j));
         }
      /*.
      ==========================================================================================
      Return it as a String
      ------------------------------------------------------------------------------------------ */
      return new String(c);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes a trailing substring from the String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#100">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the trailing
      substring removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      Suffix is the substring that will be trimmed from the String representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimRight(Type1 pStr, Type2 suffix)
      {
      String  str = UString.toString(pStr);
      String  sfx = UString.toString(suffix);

      if (str.endsWith(sfx))
         {
         return str.substring(0, str.length() - sfx.length());
         }
      return str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes a trailing substring from the String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#101">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the trailing
      substring removed.

   @param
      pStr is the Object whose String representation is operated on.
   @param
      Suffix is the substring that will be trimmed from the String representation of pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String trimRightIgnoreCase(Type1 pStr, Type2 suffix)
      {
      String  str = UString.toString(pStr);
      String  sfx = UString.toString(suffix);

      String  tmp = UString.trimRight
         (
         UString.noCase(str),UString.noCase(sfx)
         );
      if (tmp.length() != str.length())
         {
         returnb>
            (
            str.substring(0, str.length() - sfx.length())
            );
         }
      else
         {
         return str;
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method appends pPadChar to a the String representation of pStr until the resulting String is
   pFieldSize characters long.

   <P><B>Implementation: </B><A HREF="UString.java.html#102">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the trailing
      characters added.

   @param
      pStr is the Object whose String representation will be aligned.
   @param
      pFieldSize is the size of resulting String including its appended characters.
   @param
      pPadChar is the char to append to the String
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String alignLeft
      (
      Type1  pStr,
      int   pFieldSize,
      char  pPadChar
      )
      {
      String  str = UString.toString(pStr);
      int     n   = pFieldSize - str.length();
      if (n > 0)
         {
         char[]  padChars = new char[n];
         Arrays.fill(padChars,pPadChar);
         str = str + (new String(padChars));
         }
      return str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method prepends pPadChar to a the String representation of pStr until the resulting String is
   pFieldSize characters long.

   <P><B>Implementation: </B><A HREF="UString.java.html#103">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading
      characters added.

   @param
      pStr is the Object whose String representation will be aligned.
   @param
      pFieldSize is the size of resulting String including its prepended characters.
   @param
      pPadChar is the char to prepend to the String
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String alignRight
      (
      Type1  pStr,
      int   pFieldSize,
      char  pPadChar
      )
      {
      String  str = UString.toString(pStr);
      int     n   = pFieldSize - str.length();
      if (n > 0)
         {
         char[]  padChars = new char[n];
         Arrays.fill(padChars,pPadChar);
         str = (new String(padChars)) + str;
         }
      return str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method prepends and appends pPadChar in equal quantities to a String representation of pStr
   until the resulting String is pFieldSize characters long. It centers the String representation of
   pStr in a field that is pFieldSize characters long with pPadChars filling out the left and right of
   the field.

   <P><B>Implementation: </B><A HREF="UString.java.html#104">View source</A>

   @return
      A new String that is equivalent to the String representation of pStr but with the leading and
      trailing characters added.

   @param
      pStr is the Object whose String representation will be aligned.
   @param
      pFieldSize is the size of resulting String including its prepended and appended characters.
   @param
      pPadChar is the char to prepend and append to the String
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String alignCenter
      (
      Type1  pStr,
      int   pFieldSize,
      char  pPadChar
      )
      {
      String  str = UString.toString(pStr);
      int     n   = pFieldSize - str.length();
      n   = (n/2) + str.length();
      str = UString.alignRight(str,n,pPadChar);
      return UString.alignLeft(str,pFieldSize,pPadChar);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces all the tabs in the String representation of pStr with the appropriate number
   of spaces.

   <P><B>Implementation: </B><A HREF="UString.java.html#105">View source</A>

   @return
      A new String that is equivalent to the specified String with the tab characters replaced by space
      characters.

   @param
      pStr is the object whose String representation will be detabbed and returned.
   @param
      pTabSize is the number of spaces between tab stops.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String detab(Type1 pStr, int pTabSize)
      {
      String        str = UString.toString(pStr);
      StringBuffer  sb  = new StringBuffer("");
      int           p   = 0;

      while (p < str.length())
         {
         int  oldp = p;
         p = str.indexOf("\t", p);
         if (p == -1)
            {
            sb.append(str.substring(oldp));
            break;
            }
         sb.append(str.substring(oldp, p));
         int  nspaces = pTabSize-(sb.length() % pTabSize);
         for (int i = 0; i < nspaces; i++)
            {
            sb.append(' ');
            }
         p++;
         }
      return sb.toString();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces spaces with tabs in the String representation of pStr.

   <P><B>Implementation: </B><A HREF="UString.java.html#106">View source</A>

   @return
      A new String that is equivalent to the specified String with the tab characters inserted.

   @param
      pStr is the Object whose String representation will be entabbed and returned.
   @param
      pTabSize is the number of spaces between tab stops.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String entab(Type1 pStr, int pTabSize)
      {
      String        str       = UString.toString(pStr);
      char[]        in        = str.toCharArray();
      StringBuffer  sb        = new StringBuffer("");
      int           charcount = 0;
      char          c         = '@';
      int           col       = 0;
      int           newcol;

      boolean  eoln = (charcount >= in.length);
      while ( ! eoln)
         {
         newcol = col;
         while (( ! eoln) && (c = in[charcount++]) == ' ')
            {
            eoln = (charcount >= in.length);
            newcol++;
            if (newcol % pTabSize == 0)
               {
               sb.append('\t');
               col = newcol;
               }
            }
         eoln = (charcount >= in.length);
         while (col < newcol)
            {
            sb.append(' ');
            col++;
            }
         if ( ! eoln)
            {
            sb.append(c);
            col = (c == '\n' || c == '\r' ? 1 : col + 1);
            }
         }
      if (in.length>0) sb.append(c);
      return sb.toString();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns a new String resulting from replacing all occurrences of pOldString in the
   specified String with pNewString.<P>

   This method repeatedly checks the resulting string for occurrences of pOldString and replaces them
   if they exist. The checking continues until there are no occurrences of pOldString in the result.
   The reason for this is to handle situations like this: say that pStr = "AAA", pOldString = "AA", and
   pNewString = "A". Running replace() one time would result in this string: "AA". Running
   iteratingReplace() one time would result in this string: "A".

   <P><B>Implementation: </B><A HREF="UString.java.html#107">View source</A>

   @return
      A new String that is equivalent to the specified String with the all occurrences of pOldString in
      the specified String replaced with pNewString.

   @param
      pStr is the specified String.
   @param
      pOldString is the substring to replace.
   @param
      pNewString is the string with which to replace the instances of pOldString.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> String iteratingReplace
      (
      Type1  pStr,
      Type2  pOldString,
      Type3  pNewString
      )
      {
      String  str    = UString.toString(pStr);
      String  oldStr = UString.toString(pOldString);
      String  newStr = UString.toString(pNewString);

      while (str.contains(oldStr))
         {
         str = str.replace(oldStr,newStr);
         }
      return str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns a new String resulting from replacing all occurrences of pOldString in the
   specified String with pNewString.<P>

   This method repeatedly checks the resulting string for occurrences of pOldString and replaces them
   if they exist. The checking continues until there are no occurrences of pOldString in the result.
   The reason for this is to handle situations like this: say that pStr = "AAA", pOldString = "AA", and
   pNewString = "A". Running replace() one time would result in this string: "AA". Running
   iteratingReplace() one time would result in this string: "A".

   <P><B>Implementation: </B><A HREF="UString.java.html#108">View source</A>

   @return
      A new String that is equivalent to the specified String with the all occurrences of pOldString in
      the specified String replaced with pNewString.

   @param
      pStr is the specified String.
   @param
      pOldString is the substring to replace.
   @param
      pNewString is the string with which to replace the instances of pOldString.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> String iteratingReplaceIgnoreCase
      (
      Type1  pStr,
      Type2  pOldString,
      Type3  pNewString
      )
      {
      String  str    = UString.toString(pStr);
      String  oldStr = UString.toString(pOldString);
      String  newStr = UString.toString(pNewString);

      while (UString.containsIgnoreCase(str,oldStr))
         {
         str = UString.replaceIgnoreCase(str,oldStr,newStr);
         }
      return str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method takes a string and generates a hash of it in which each character is replaced with a
   character in the range ' ' to '~'.

   <P><B>Implementation: </B><A HREF="UString.java.html#109">View source</A>

   @return
      A string with the same length as the input string and in which every character is in the range of
      the 95 characters from ' ' to '~'.

   @param
      pStr the string that is hashed
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String asciiHash(Type1 pStr)
      {
      String  str      = UString.toString(pStr);
      char[]  ca       = str.toCharArray();
      long    caLength = (long)ca.length;
      Random  random   = new Random(257);
      long    i;
      long    hash;
      /*.
      ==========================================================================================
      Convert each ajacent pair of characters into a long and then hash each pair into the range
      ' ' to '~'. The last character is paired up with the first character.
      ------------------------------------------------------------------------------------------ */
      for (i=0L; i<caLength; i++)
         {
         /*.
         ==========================================================================================
         Get the indexes of the next sequential pair of ajacent characters
         ------------------------------------------------------------------------------------------ */
         long  c1 = i;
         long  c2 = (i + 1L) % caLength;
         /*.
         ==========================================================================================
         Use them to generate a hash value in the range 0..94 (inclusive)
         ------------------------------------------------------------------------------------------ */
         hash = ((long)ca[(int)c1] * (long)ca[(int)c2] * (long)random.nextInt(131)) % 95L;
         /*.
         ==========================================================================================
         Shift the hash into the range 32..126 which corresponds to the characters in the range '
         '..'~'
         ------------------------------------------------------------------------------------------ */
         hash += 32L;
         /*.
         ==========================================================================================
         Convert the hash back into a character and replace the second character in the pair of
         ajacent characters with the hash character
         ------------------------------------------------------------------------------------------ */
         ca[(int)c2] = (char)hash;
         }
      return new String(ca);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method takes a string and generates a hash of it in which each character is replaced with a
   character in the range ' ' to '~'.

   <P><B>Implementation: </B><A HREF="UString.java.html#110">View source</A>

   @return
      A string with the same length as the input string and in which every character is in the range of
      the 95 characters from ' ' to '~'.

   @param
      pStr the string that is hashed
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String asciiHashIgnoreCase(Type1 pStr)
      {
      return UString.asciiHash(UString.noCase(pStr));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the leading white space in the input String as a new String.

   <P><B>Implementation: </B><A HREF="UString.java.html#111">View source</A>

   @return
      A String containing the leading white space in the input String. If the String is null or empty,
      this method returns an empty String.

   @param
      pStr is the String for which the leading white space is returned.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String whitespacePrefix(Type1 pStr)
      {
      /*.
      ==========================================================================================
      Convert the generic parameter types to concrete types
      ------------------------------------------------------------------------------------------ */
      String  str = UString.toString(pStr);
      /*.
      ==========================================================================================
      Take care of boundry conditions:
         <BLOCKQUOTE>
            => If there is no String, return an empty String.
         </BLOCKQUOTE>
      ------------------------------------------------------------------------------------------ */
      if (UString.isNullOrEmpty(str)) return("");
      /*.
      ==========================================================================================
      Find the first non-whitespace character in the String or the end of the String, whichever
      comes first.
      ------------------------------------------------------------------------------------------ */
      int idx = 0;
      for (idx = 0; idx < str.length(); idx++)
         {
         if (! Character.isWhitespace(str.charAt(idx))) break;
         }
      /*.
      ==========================================================================================
      Return the substring that is composed of all the consecutive whitespace characters
      beginning at the first character in the String. If 0 == idx, substring returns an empty
      String ("").
      ------------------------------------------------------------------------------------------ */
      return str.substring(0, idx);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the length of the leading white space in the input String as an int.

   <P><B>Implementation: </B><A HREF="UString.java.html#112">View source</A>

   @return
      A int containing the length of the leading white space in the input String.

   @param
      pStr is the String for which the leading white space length is returned.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int whitespacePrefixLength(Type1 pStr)
      {
      String str = whitespacePrefix(pStr);
      return str.length();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method backs up from a given starting point in a String until it runs into either the start of
   the String or a "\n". It then returns the whitespace prefix starting from that point.

   <P><B>Implementation: </B><A HREF="UString.java.html#113">View source</A>

   @return
      This method returns the whitespace prefix of the line of text that contains the pIdx'th character
      in a String.

   @param
      pStr is the object whose String representation is searched for a whitespace prefix.
   @param
      pIdx is the index into pStr from which to back up looking for a whitespace prefix.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String whitespacePrefixOfLineContainingIndex(Type1 pStr, int pIdx)
      {
      String  line = UString.lineContainingIndex(pStr, pIdx);
      return whitespacePrefix(line);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the leading white space and line comment delimiters ("//") in a String as a new
   String.
      <BLOCKQUOTE>
         For example, if a String comprised this sequence of characters:
            <BLOCKQUOTE>
               <PRE id="unindent">
                  "  //  // /<--That is not a comment delimiter because it has only 1 slash"
               </PRE>
            </BLOCKQUOTE>
        Then this method would return a String comprising this sequence of characters:
           <BLOCKQUOTE>
              <PRE id="unindent">
                 "  //  // "
              </PRE>
           </BLOCKQUOTE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#114">View source</A>

   @return
      A String containing the leading white space and line comment delimiters ("//") in the input
      String. If the String is null or empty, this method returns an empty String.

   @param
      pStr is the object whose String representation is searched for a whitespace prefix.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String whitespaceAndLineCommentPrefix(Type1 pStr)
      {
      /*.
      ==========================================================================================
      Convert the generic parameter types to concrete types
      ------------------------------------------------------------------------------------------ */
      String  str = UString.toString(pStr);
      /*.
      ==========================================================================================
      Take care of boundry conditions:
         <BLOCKQUOTE>
            => If there is no String, return an empty String.
         </BLOCKQUOTE>
      ------------------------------------------------------------------------------------------ */
      if (UString.isNullOrEmpty(str)) return("");
      /*.
      ==========================================================================================
      From the begining of the string, skip past all the whitespace and double slashes
      ------------------------------------------------------------------------------------------ */
      String  state = "Start";
      int     idx   = 0;
      char    curr  = '\u0000';
      while ((idx >= 0) && (idx < str.length()) && (state != "Exit"))
         {
         curr = str.charAt(idx);
         switch (state)
            {
            case "Start":
               if      (Character.isWhitespace(curr))  {state = "InWhitespace";                }
               else if (curr == '/')                   {state = "StartingSingleLineComment";   }
               else                                    {state = "Exit";                        }
               break;
            case "InWhitespace":
               if      (Character.isWhitespace(curr))  {state = "InWhitespace";                }
               else if (curr == '/')                   {state = "StartingSingleLineComment";   }
               else                                    {state = "Exit";                        }
               break;
            case "StartingSingleLineComment":
               if      (curr == '/')                   {state = "InSingleLineComment";         }
               else                                    {state = "Exit";                 idx--; }
               break;
            case "InSingleLineComment":
               if      (Character.isWhitespace(curr))  {state = "InWhitespace";                }
               else if (curr == '/')                   {state = "StartingSingleLineComment";   }
               else                                    {state = "Exit";                        }
               break;
            case "Exit":
               break;
            }
         idx++;
         }
      /*.
      ==========================================================================================
      If we indexed past the whitespace and comment delimiters and into the text part of the
      string, then back up one.
      ------------------------------------------------------------------------------------------ */
      if ((! (Character.isWhitespace(curr))) && (! (curr == '/')))
         {
         idx--;
         }
      /*.
      ==========================================================================================
      Return the substring that is composed of all the consecutive whitespace characters and
      double slashes beginning at the first character in the String. If 0 == idx, substring
      returns an empty String ("").
      ------------------------------------------------------------------------------------------ */
      return str.substring(0, idx);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method backs up from a given index in a String until it runs into either the start of the
   String or a "\n". It then returns the entire line prefix starting from that point. The prefix will
   include the whitespace as well as comment delimiters in cases where the line was commented out.

   <P><B>Implementation: </B><A HREF="UString.java.html#115">View source</A>

   @return
      This method returns the line prefix of the line of text that contains the pIdx'th character in a
      String.

   @param
      pStr is the object whose String representation is searched for a line prefix.
   @param
      pIdx is the index into pStr from which to back up looking for a line prefix.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String linePrefixOfLineContainingIndex(Type1 pStr, int pIdx)
      {
      String  line = UString.lineContainingIndex(pStr, pIdx);
      return UString.whitespaceAndLineCommentPrefix(line);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method is for counting the number of newlines immediately preceeding an index in a String. If
   the index is immediately preceeded by text, then this method returns a count of zero newlines. If it
   is immediately preceeded by a single line comment delimiter (double forward slash) or if it is
   immediately preceeded by whitespace or any sequential combination of single line comment delimiters
   and whitespace, this method will skip over the comment delimiters and/or whitespaces looking for
   newlines. If/when it finds a newline, it counts that newline and all other newlines that
   consecutively and exclusively preceed it and returns the count.

   <P><B>Implementation: </B><A HREF="UString.java.html#116">View source</A>

   @return
      This method returns the number of newlines between pIdx and the nearest text prior to it that is
      not whitespace nor a single-line comment

   @param
      pStr is the object whose String representation is searched for newlines.
   @param
      pIdx is the index into pStr from which to back up looking for newlines.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int newlinesBeforeIndex(Type1 pStr, int pIdx)
      {
      String  state        = "Start";
      String  str          = UString.toString(pStr);
      int     newlineCount = 0;
      int     idx          = pIdx;
      while ((idx >= 0) && (state != "Exit"))
         {
         char  curr = str.charAt(idx);
         idx--;
         switch (state)
            {
            case "Start":
               if      (curr == ' ')  {state = "InWhitespace";                              }
               else if (curr == '/')  {state = "StartingSingleLineComment";                 }
               else if (curr == '\n') {state = "InNewlines";                newlineCount++; }
               else                   {state = "Exit";                                      }
               break;
            case "InWhitespace":
               if      (curr == ' ')  {state = "InWhitespace";                              }
               else if (curr == '/')  {state = "StartingSingleLineComment";                 }
               else if (curr == '\n') {state = "InNewlines";                newlineCount++; }
               else                   {state = "Exit";                                      }
               break;
            case "InNewlines":
               if      (curr == '\n') {state = "InNewlines";                newlineCount++; }
               else                   {state = "Exit";                                      }
               break;
            case "StartingSingleLineComment":
               if      (curr == '/')  {state = "InSingleLineComment";                       }
               else                   {state = "Exit";                                      }
               break;
            case "InSingleLineComment":
               if      (curr == ' ')  {state = "InWhitespace";                              }
               else if (curr == '/')  {state = "InSingleLineComment";                       }
               else if (curr == '\n') {state = "InNewlines";                newlineCount++; }
               else                   {state = "Exit";                                      }
               break;
            case "Exit":
               break;
            }
         }
      /*.
      ==========================================================================================
      Return how many newlines we found
      ------------------------------------------------------------------------------------------ */
      return newlineCount;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method is for counting the number of newlines immediately following an index in a String. If
   the index is immediately followed by text, then this method returns a count of zero newlines. If it
   is immediately followed by a single line comment delimiter (double forward slash) or if it is
   immediately followed by whitespace or any sequential combination of single line comment delimiters
   and whitespace, this method will skip over the comment delimiters and/or whitespaces looking for
   newlines. If/when it finds a newline, it counts that newline and all other newlines that
   consecutively and exclusively follow it and returns the count.

   <P><B>Implementation: </B><A HREF="UString.java.html#117">View source</A>

   @return
      This method returns the number of newlines between pIdx and the nearest text after to it that is
      not whitespace nor a single-line comment

   @param
      pStr is the object whose String representation is searched for newlines.
   @param
      pIdx is the index into pStr from which to begin looking for newlines.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int newlinesAfterIndex(Type1 pStr, int pIdx)
      {
      String  state        = "Start";
      String  str          = UString.toString(pStr);
      int     strLength    = str.length();
      int     newlineCount = 0;
      int     idx          = pIdx;
      while ((idx < strLength) && (state != "Exit"))
         {
         char  curr = str.charAt(idx);
         idx++;
         switch (state)
            {
            case "Start":
               if      (curr == ' ')  {state = "Start";                                     }
               else if (curr == '/')  {state = "StartingSingleLineComment";                 }
               else if (curr == '\n') {state = "Start";                     newlineCount++; }
               else                   {state = "Exit";                                      }
               break;
            case "StartingSingleLineComment":
               if      (curr == '/')  {state = "Start";                                     }
               else                   {state = "Exit";                                      }
               break;
            case "Exit":
               break;
            }
         }
      /*.
      ==========================================================================================
      Return how many newlines we found
      ------------------------------------------------------------------------------------------ */
      return newlineCount;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the line of text containing pStr.charAt(pIdx). The line begins at either
   pStr.charAt(0) or at the character AFTER the first newline prior to pStr.charAt(pIdx), whichever has
   the greater index (whichever comes last). The line ends at either pStr.charAt(pStr.length()-1) or AT
   the first newline after to pStr.charAt(pIdx), whichever has the smaller index (whichever comes
   first). Examples:
      <BLOCKQUOTE>
         <PRE id="unindent">
            lineContainingIndex(           "This is the line\nfollowng text",  4) returns "This is the line\n"
                                 012345678 901234 5678901234567890
            lineContainingIndex("preceedng\nThis is the line\nfollowng text", 14) returns "This is the line\n"
                                 012345678 901234 5678901234567890
            lineContainingIndex(           "This is the line"               ,  4) returns "This is the line"
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#118">View source</A>

   @return
      A String containing the line which includes the pStr character pointed to by pIdx. If pStr ==
      null || pStr.equals("") || (pIdx < 0) || (pIdx >= pStr.length()) then this method returns the
      empty String.

   @param
      pStr is an object whose String representation contains a character a index pIdx.
   @param
      pIdx is the index into pStr for which the containing line is returned.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String lineContainingIndex(Type1 pStr, int pIdx)
      {
      /*.
      ==========================================================================================
      Convert the generic parameter types to concrete types
      ------------------------------------------------------------------------------------------ */
      String  str = UString.toString(pStr);
      /*.
      ==========================================================================================
      Now get beginIdx which will point to the first character in the line and endIdx which will
      point to the last character (which may be the terminating newline)
      ------------------------------------------------------------------------------------------ */
      int  beginIdx = indexOfStartOfLineContainingIndex(str, pIdx);
      int  endIdx   = indexOfEndOfLineContainingIndex(str, pIdx);
      /*.
      ==========================================================================================
      If either one of them failed, return an empty String.
      ------------------------------------------------------------------------------------------ */
      if ((beginIdx == (-1)) || (endIdx == (-1))) return "";
      /*.
      ==========================================================================================
      Now get the substring. If beginIdx > endIdx, this will fail and we'll return an empty
      string. If beginIdx == endIdx, this will return the 1-char that they point at as a String
      ------------------------------------------------------------------------------------------ */
      String  result = null;
      try
         {
         result = str.substring(beginIdx, endIdx + 1);
         }
      catch (IndexOutOfBoundsException e)
         {
         result = "";
         }
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the index into a String of the first character in the line that contains the
   pIdx'th character.<P>

   A line is considered to be a sequence of characters and their terminating newline. It does not
   include the newline preceding the sequence. Here are some example Strings -- in the left column --
   in which the dollar sign ($) represents a newline character. Under each String is a series of
   circumflex accents (^) that indicate the span of the line under the specific condition given in the
   right column:
      <BLOCKQUOTE>
         <PRE id="unindent">
            +---------------------------------------------------+----------------------------------------------+
            |  STRING WITH SPAN OF LINE INDICATED               |  UNDER THIS CONDITION                        |
            +---------------------------------------------------+----------------------------------------------+
            |  "this line has no newlines."                     |                                              |
            |   ^^^^^^^^^^^^^^^^^^^^^^^^^^                      |  pIdx points to any character in the String  |
            |                                                   |                                              |
            |  "$preceding newline but no terminating newline." |                                              |
            |    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  |  0 < pIdx < String.length()                  |
            |   ^                                               |  pIdx = 0                                    |
            |                                                   |                                              |
            |  "$preceding newline and a terminating newline.$" |                                              |
            |                                                ^  |  pIdx = String.length() - 1                  |
            |    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  |  0 < pIdx < String.length()                  |
            |   ^                                               |  pIdx = 0                                    |
            |                                                   |                                              |
            |  "$"                                              |                                              |
            |   ^                                               |  pIdx = 0                                    |
            |                                                   |                                              |
            |  "$$"                                             |                                              |
            |   ^                                               |  pIdx = 0                                    |
            |    ^                                              |  0 < pIdx < String.length()                  |
            +---------------------------------------------------+----------------------------------------------+
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#119">View source</A>

   @return
      This method returns the index into a String of the first character in the line that contains the
      pIdx'th character. It returns -1 if pStr is null or empty. It returns -1 if pIdx is out of range
      of valid indexes for pStr.

   @param
      pStr is the object whose String representation is searched.
   @param
      pIdx is the index of a character within pStr. The line within pStr that contains the character at
      index pIdx is the line whose starting index is returned.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int indexOfStartOfLineContainingIndex(Type1 pStr, int pIdx)
      {
      /*.
      ==========================================================================================
      Convert the generic parameter types to concrete types
      ------------------------------------------------------------------------------------------ */
      String  str = UString.toString(pStr);
      /*.
      ==========================================================================================
      Take care of boundry conditions:
         <BLOCKQUOTE>
            => If there is no String or if the index is out of range, return -1.<BR>
            => If the String is only one char long, return its index, i.e. 0, regardless of what
               Character is at index 0.<BR>
            => If pIdx is already pointing to the first character in the string, then we cannot
               Back up from there to find the start of the String or a preceding newline so we
               return 0, regardless of what character is at index 0.<BR>
            => If pIdx is pointing at a newline and the character immediately preceding is also
               A Newline, then return pIdx as the beginning of the line (it is also the end of
               the same line).
         </BLOCKQUOTE>
      ------------------------------------------------------------------------------------------ */
      if (UString.isNullOrEmpty(str) || (pIdx < 0) || (pIdx >= str.length())) return(-1);
      if (str.length() == 1) return 0;
      if (pIdx == 0) return pIdx;
      if ((str.charAt(pIdx) == '\n') && (str.charAt(pIdx - 1) == '\n')) return pIdx;
      /*.
      ==========================================================================================
      If pIdx is the index of a newline, it is interpreted as being the newline at the end of
      the line that has the pIdx'th character in it. So, to get things off on the right foot, we
      point to the character before the newline that pIdx is pointing at. We know there is a
      character of some sort before it because the boundry conditions above eliminated the
      scenarios where there is no preceding character.
      ------------------------------------------------------------------------------------------ */
      int  beginIdx = pIdx;
      if (str.charAt(beginIdx) == '\n') beginIdx--;
      /*.
      ==========================================================================================
      Look for the beginning of the String or a newline.
         If pIdx is the index of a newline, it is interpreted as being the newline at the end of
         the line that has the pIdx'th character in it.
      ------------------------------------------------------------------------------------------ */
      while ((beginIdx > 0) && (str.charAt(beginIdx) != '\n'))
         {
         beginIdx--;
         }
      /*.
      ==========================================================================================
      If beginIdx is pointing at a newline, increment past it
      ------------------------------------------------------------------------------------------ */
      if (str.charAt(beginIdx) == '\n')
         {
         beginIdx++;
         }
      /*.
      ==========================================================================================
      Now return the index of the start of the line containing the specified index
      ------------------------------------------------------------------------------------------ */
      return beginIdx;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the index into a String of the last character in the line that contains the
   pIdx'th character.<P>

   A line is considered to be a sequence of characters and their terminating newline. It does not
   include the newline preceding the sequence. Here are some example Strings -- in the left column --
   in which the dollar sign ($) represents a newline character. Under each String is a series of
   circumflex accents (^) that indicate the span of the line under the specific condition given in the
   right column:
      <BLOCKQUOTE>
         <PRE id="unindent">
            +---------------------------------------------------+----------------------------------------------+
            |  STRING WITH SPAN OF LINE INDICATED               |  UNDER THIS CONDITION                        |
            +---------------------------------------------------+----------------------------------------------+
            |  "this line has no newlines."                     |                                              |
            |   ^^^^^^^^^^^^^^^^^^^^^^^^^^                      |  pIdx points to any character in the String  |
            |                                                   |                                              |
            |  "$preceding newline but no terminating newline." |                                              |
            |    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  |  0 < pIdx < String.length()                  |
            |   ^                                               |  pIdx = 0                                    |
            |                                                   |                                              |
            |  "$preceding newline and a terminating newline.$" |                                              |
            |                                                ^  |  pIdx = String.length() - 1                  |
            |    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  |  0 < pIdx < String.length()                  |
            |   ^                                               |  pIdx = 0                                    |
            |                                                   |                                              |
            |  "$"                                              |                                              |
            |   ^                                               |  pIdx = 0                                    |
            |                                                   |                                              |
            |  "$$"                                             |                                              |
            |   ^                                               |  pIdx = 0                                    |
            |    ^                                              |  0 < pIdx < String.length()                  |
            +---------------------------------------------------+----------------------------------------------+
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#120">View source</A>

   @return
      This method returns the index into a String of the last character in the line that contains the
      pIdx'th character. It returns -1 if pStr is null or empty. It returns -1 if pStr is out of range
      of valid indexes for pStr.

   @param
      pStr is the object whose String representation is searched.
   @param
      pIdx is the index of the character within pStr. The line within pStr that contains the character
      at index pIdx is the line whose ending index is returned.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int indexOfEndOfLineContainingIndex(Type1 pStr, int pIdx)
      {
      /*.
      ==========================================================================================
      Convert the generic parameter types to concrete types
      ------------------------------------------------------------------------------------------ */
      String  str = UString.toString(pStr);
      /*.
      ==========================================================================================
      Take care of boundry conditions:
         <BLOCKQUOTE>
            => If there is no String or if the index is out of range, return -1.<BR>
            => If the String is only one char long, return its index, i.e. 0, regardless of what
               Character is at index 0.<BR>
            => If pIdx is already pointing to the last character in the string, then return it,
               Regardless of what character is at pIdx.<BR>
            => If pIdx is pointing at a newline, then return pIdx as the endning of the line.
         </BLOCKQUOTE>
      ------------------------------------------------------------------------------------------ */
      if (UString.isNullOrEmpty(str) || (pIdx < 0) || (pIdx >= str.length())) return(-1);
      if (str.length() == 1) return 0;
      if (pIdx == (str.length() - 1)) return pIdx;
      if (str.charAt(pIdx) == '\n') return pIdx;
      /*.
      ==========================================================================================
      Look for the end of the String or a newline.
      ------------------------------------------------------------------------------------------ */
      int  endIdx = pIdx;
      while (endIdx < str.length())
         {
         if (str.charAt(endIdx) == '\n') break;
         endIdx++;
         }
      /*.
      ==========================================================================================
      If the end index went past the last char in the string, back up to point at it.
      ------------------------------------------------------------------------------------------ */
      boolean  pastEnd = endIdx >= str.length();
      if (pastEnd)
         {
         endIdx = str.length() - 1;
         }
      /*.
      ==========================================================================================
      Now return the index of the end of the line containing the specified index
      ------------------------------------------------------------------------------------------ */
      return endIdx;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method word wraps the String representation of pStr using the default line length.

   <P><B>Implementation: </B><A HREF="UString.java.html#121">View source</A>

   @return
      An ArrayList into which this method puts the lines it generates from the String.

   @param
      pStr is the object whose String representation is word wrapped.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> ArrayList<String> wordWrap(Type1 pStr)
      {
      return UString.wordWrap(pStr,ConsoleMessage.defaultLineLength(),null);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method word wraps the String representation of pStr using the default line length and applies
   the capitalizer to the content of the String.

   <P><B>Implementation: </B><A HREF="UString.java.html#122">View source</A>

   @return
      An ArrayList into which this method puts the lines it generates from the String.

   @param
      pStr is the object whose String representation is word wrapped.
   @param
      pCapitalize turns the optional capitalization on (true) or off (false)
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> ArrayList<String> wordWrap
      (
      Type1          pStr,
      UCapitalizer  pCapitalizer
      )
      {
      return UString.wordWrap(pStr,ConsoleMessage.defaultLineLength(),pCapitalizer);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method word wraps the String representation of pStr using the specified line length.

   <P><B>Implementation: </B><A HREF="UString.java.html#123">View source</A>

   @return
      An ArrayList into which this method puts the lines it generates from the String.

   @param
      pStr is the object whose String representation is word wrapped.
   @param
      pLineLength is the line length at which the String is word wrapped.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> ArrayList<String> wordWrap(Type1 pStr, int pLineLength)
      {
      return UString.wordWrap(pStr,pLineLength,null);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method word wraps the String representation of pStr using the specified line length and applies
   the capitalizer to the content of the String.<P>

   This method does not wrap sections of the String representation of pStr that are delimited by any of
   the following pairs of delimiters:
      <BLOCKQUOTE>
         <PRE id="unindent">
            [PRE id="unindent"] [/PRE]
            [BLOCKQUOTE]        [/BLOCKQUOTE]
            [CODE]              [/CODE]
            //                  \n
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#124">View source</A>

   @return
      An ArrayList into which this method puts the lines it generates from the String.

   @param
      pStr is the object whose String representation is word wrapped.
   @param
      pLineLength is the line length at which the String is word wrapped.
   @param
      pCapitalize is a text modifier that applies capitalization rules (such as capitalizing the word
      "I" and the first letter of each sentence) to a string. This parameter may be set to null to
      indicate that the string should not be modified.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> ArrayList<String> wordWrap
      (
      Type1         pStr,
      int           pLineLength,
      UCapitalizer  pCapitalizer
      )
      {
      /*.
      ==========================================================================================
      This is where the resulting compressed chunks go to be returned from this method.
      ------------------------------------------------------------------------------------------ */
      ArrayList<String>  results = new ArrayList<String>();
      /*.
      ==========================================================================================
      Turn the parameter into a String
      ------------------------------------------------------------------------------------------ */
      String  str = UString.toString(pStr);
      /*.
      ==========================================================================================
      We do not wrap sections that are delimited by any of the following pairs of delimiters:
         <BLOCKQUOTE>
            <PRE id="unindent">
               [PRE id="unindent"] [/PRE]
               [BLOCKQUOTE]        [/BLOCKQUOTE]
               [CODE]              [/CODE]
               //                  \n
            </PRE>
         </BLOCKQUOTE>
      Find them and recursively word-wrap the chunks of text surrounding them. Use an
      upper-cased version of the string as a way of finding the tag pairs in a case-insensitive
      way.<P>

      Begin by finding the first occurrence of all the beginning and ending delimiters that we
      do not wrap.
      ------------------------------------------------------------------------------------------ */
      String   strUpr          = str.toUpperCase();
      String   startStr        = null;
      int      startStrLen     = 0;
      String   endStr          = null;
      int      endStrLen       = 0;
      int      startIdx        = 0;
      int      endIdx          = 0;
      int[]    regexResult;

      regexResult = UString.indexOfRegexIgnoreCase(strUpr, Const.REGEX_PRE_START_TAG, 0);
      int      startPreIdx = regexResult[0];
      int      startPreLen = regexResult[2];

      regexResult = UString.indexOfRegexIgnoreCase(strUpr, Const.REGEX_CODE_START_TAG, 0);
      int      startCodeIdx = regexResult[0];
      int      startCodeLen = regexResult[2];

      regexResult = UString.indexOfRegexIgnoreCase(strUpr, Const.REGEX_LINE_COMMENT_START, 0);
      int      startCommentIdx = regexResult[0];
      int      startCommentLen = regexResult[2];

      boolean  isStartPre      = (startPreIdx     != (-1));
      boolean  isStartCode     = (startCodeIdx    != (-1));
      boolean  isStartComment  = (startCommentIdx != (-1));
      /*.
      ==========================================================================================
      Turn the -1's into MAXINTs so they can be used to find the smallest index so we can locate
      which delimiter came first in the String.
      ------------------------------------------------------------------------------------------ */
      if (startPreIdx     == (-1)) startPreIdx     = (Integer.MAX_VALUE);
      if (startCodeIdx    == (-1)) startCodeIdx    = (Integer.MAX_VALUE);
      if (startCommentIdx == (-1)) startCommentIdx = (Integer.MAX_VALUE);
      /*.
      ==========================================================================================
      If any of the delimiters are present, pick the one that comes first in the string and that
      is the one we will process.
         Their indexes cannot be equal unless they are all equal to Integer.MAX_VALUE. If that's
         the case, none of the start delimiters is present.
      ------------------------------------------------------------------------------------------ */
      boolean  doPre       = (startPreIdx     < startCodeIdx) && (startPreIdx     < startCommentIdx);
      boolean  doCode      = (startCodeIdx    < startPreIdx)  && (startCodeIdx    < startCommentIdx);
      boolean  doComment   = (startCommentIdx < startPreIdx)  && (startCommentIdx < startCodeIdx   );
      boolean  doDelimiter = (doPre || doCode || doComment);
      /*.
      ==========================================================================================
      If there is a start delimiter ...
      ------------------------------------------------------------------------------------------ */
      if (doDelimiter)
         {
         /*.
         ==========================================================================================
         Set the processing parameters to process the first one.
         ------------------------------------------------------------------------------------------ */
         if (doPre)
            {
            startStr    = Const.REGEX_PRE_START_TAG;
            startIdx    = startPreIdx;
            startStrLen = startPreLen;
            endStr      = Const.REGEX_PRE_END_TAG;
            endStrLen   = Const.REGEX_PRE_END_TAG.length();
            }
         else if (doCode)
            {
            startStr    = Const.REGEX_CODE_START_TAG;
            startIdx    = startCodeIdx;
            startStrLen = startCodeLen;
            endStr      = Const.REGEX_CODE_END_TAG;
            endStrLen   = Const.REGEX_CODE_END_TAG.length();
            }
         else if (doComment)
            {
            startStr = Const.REGEX_LINE_COMMENT_START;
            endStr   = Const.REGEX_LINE_COMMENT_END;
            startIdx = startCommentIdx;
            }
         /*.
         ==========================================================================================
         Find the delimited section and recursively word-wrap the chunks of text surrounding it.
         ------------------------------------------------------------------------------------------ */
         if (startIdx != (Integer.MAX_VALUE))
            {
            endIdx = indexAfterDelimitedSpanRegex(strUpr, startStr, endStr, startIdx + startStrLen, true);
            /*.
            ==========================================================================================
            Now we are finished with the upper-cased string so release it to the gargage collector (it
            could be very big).
            ------------------------------------------------------------------------------------------ */
            strUpr = null;
            /*.
            ==========================================================================================
            Only recursively word-wrap the chunks of text surrounding a properly formed delimited
            section. If there is an end delimiter (meaning we have a well-formed delimited section),
            then ...
            ------------------------------------------------------------------------------------------ */
            if (endIdx != (-1))
               {
               /*.
               ==========================================================================================
               If the well-formed delimited section is a single line comment then simply add it to our
               results and then recursively wordwrap everything following it and add the lines thus
               created to our results. Then we're done.
               ------------------------------------------------------------------------------------------ */
               String  tmp = str.substring(startIdx, endIdx);
               if (tmp.startsWith("//"))
                  {
                  results.add(tmp);
                  results.addAll(UString.wordWrap(str.substring(endIdx, str.length()), pLineLength, pCapitalizer));
                  }
               /*.
               ==========================================================================================
               Otherwise, this well-formed delimited section is not a single line comment so go through
               the process of recursive wordwrapping. This is the core of this method's wordwrapping
               algorithm.
               ------------------------------------------------------------------------------------------ */
               else
                  {
                  /*.
                  ==========================================================================================
                  Get the line prefix for the line on which the delimiter is located.
                  ------------------------------------------------------------------------------------------ */
                  String  indent = linePrefixOfLineContainingIndex(str, startIdx);
                  /*.
                  ==========================================================================================
                  Break the String into 3 chunks:
                     <BLOCKQUOTE>
                        1) the chunk from the start of the string up to an including the start delimiter
                           (this Chunk will always include at least a start delimiter),<BR>
                        2) the chunk between (but excluding) the start and end delimiters,<BR>
                        3) and the chunk including the end delimiter and the remainder of the string after
                           The end delimiter (this chunk will always include at least an end delimiter).
                     </BLOCKQUOTE>
                  ------------------------------------------------------------------------------------------ */
                  String  chunk1           = str.substring(0, startIdx + startStrLen);
                  String  chunk2           = (indent + str.substring(startIdx + startStrLen, endIdx - endStrLen));
                  String  chunk3           = (indent + str.substring(endIdx - endStrLen, str.length()));
                  String  appendedLastLine = null;
                  /*.
                  ==========================================================================================
                  Wrap chunk 1 and add the lines thus created to the results ArrayList.
                  ------------------------------------------------------------------------------------------ */
                  results.addAll(UString.wordWrap(chunk1, pLineLength, pCapitalizer));
                  /*.
                  ==========================================================================================
                  Get a copy of the last line of chunk 1 from the results ArrayList and append chunk 2 (the
                  chunk we are not wrapping) to it.
                  ------------------------------------------------------------------------------------------ */
                  appendedLastLine = results.get(results.size()-1);
                  appendedLastLine = appendedLastLine + chunk2;
                  /*.
                  ==========================================================================================
                  Remove the last line of chunk 1 from the results ArrayList and replace it with the copy to
                  which that we appended chunk 2.
                  ------------------------------------------------------------------------------------------ */
                  results.remove(results.size()-1);
                  results.add(appendedLastLine);
                  /*.
                  ==========================================================================================
                  Wrap chunk 3 and add the lines thus created to a temporary chunk 3 results ArrayList.
                  ------------------------------------------------------------------------------------------ */
                  ArrayList<String>  chunk3Results = new ArrayList<String>();
                  chunk3Results.addAll(UString.wordWrap(chunk3, pLineLength, pCapitalizer));
                  /*.
                  ==========================================================================================
                  Get a copy of the last line of the results ArrayList and append the first line of the
                  chunk 3 results ArrayList to it
                  ------------------------------------------------------------------------------------------ */
                  appendedLastLine = results.get(results.size()-1);
                  appendedLastLine = appendedLastLine + chunk3Results.get(0).trim();
                  /*.
                  ==========================================================================================
                  Remove the last line of the results ArrayList and replace it with the copy to which that
                  we appended the first line of the chunk 3 results ArrayList.
                  ------------------------------------------------------------------------------------------ */
                  results.remove(results.size()-1);
                  results.add(appendedLastLine);
                  /*.
                  ==========================================================================================
                  Remove the first line from the chunk 3 results ArrayList and add its remaining lines to
                  the final results ArrayList.
                  ------------------------------------------------------------------------------------------ */
                  chunk3Results.remove(0);
                  results.addAll(chunk3Results);
                  /*.
                  ==========================================================================================
                  Return the completed results ArrayList.
                  ------------------------------------------------------------------------------------------ */
                  return results;
                  }
               }
            }
         }
      /*.
      ==========================================================================================
      We end up here if there are no [well-formed] delimited sections in pStr to process; so we
      will wordwrap the entire pStr.
      ------------------------------------------------------------------------------------------ */
      /*.
      ==========================================================================================
      This next thing is necessary because empty lines terminated with a \n are eliminated by
      the string tokenizer that we are getting ready to use. The reason this is necessary is
      that if there is an empty line (a line containing only a \n), then the tokenizer would
      completely eliminate it. What we want is to keep the empty line and the way we do that is
      by inserting the string - "%NE...NE%" {keep this thing misspelled in this comment else it
      too will be deleted}, letting the tokenizer generate a line with nothing but the string
      (the \n being eliminated) and then replacing the string with an empty string, thus
      including the empty line as a segment in our results.
      ------------------------------------------------------------------------------------------ */
      str = UString.replace(str,"\n","%NEWLINE%\n");
      /*.
      ==========================================================================================
      If the input string has embedded '\n's, break it up creating separate strings for each
      '\n'-delimeted segment.
      ------------------------------------------------------------------------------------------ */
      ArrayList<String>  segments = UString.tokenizedString(str,"\n");
      /*.
      ==========================================================================================
      Clean up all the segments by deleting all the %NEWLINE"s, trimming all trailing whitespace
      from each segment, and detabbing each segment.
      ------------------------------------------------------------------------------------------ */
      ArrayList<String>  cleanSegments = new ArrayList<String>();
      for (String  sgmnt : segments)
         {
         sgmnt = UString.replace(sgmnt,"%NEWLINE%","");
         if (sgmnt.trim().equals(""))
            {
            cleanSegments.add("");
            }
         else
            {
            String  tmp = UString.trimRight(sgmnt);
            tmp         = UString.detab(tmp,3);
            cleanSegments.add(tmp);
            }
         }
      /*.
      ==========================================================================================
      Get the indent of the first segment
      ------------------------------------------------------------------------------------------ */
      String  currIndent =
         (
         (cleanSegments.size() > 0)? UString.whitespacePrefix(cleanSegments.get(0)) : ""
         );
      /*.
      ==========================================================================================
      Combine segments that should be wrapped as a single unit. If adjacent segments have the
      same indent, they are assumed to belong together in the same unit.
      ------------------------------------------------------------------------------------------ */
      ArrayList<String>  units     = new ArrayList<String>();
      String             currUnit  = "";
      int                unitCount = 0;
      for (String  sgmnt : cleanSegments)
         {
         String   trimmedSegment  = UString.trim(sgmnt);
         String   thisIndent      = UString.whitespacePrefix(sgmnt);
         /*.
         ==========================================================================================
         A blank line (segment) signals the end of a unit
         ------------------------------------------------------------------------------------------ */
         if (sgmnt.equals(""))
            {
            currUnit = currIndent + UString.trimRight(currUnit);
            units.add(currUnit);

            currIndent = "";
            currUnit   = "";
            }
         /*.
         ==========================================================================================
         Otherwise, if this line (segment) starts with a bullet or certain other delimiters, that
         means it is the start of a new unit so save the current unit and start a new unit with
         this segment.
         ------------------------------------------------------------------------------------------ */
         else ifb>
            (
            UString.startsWith(trimmedSegment, "| ")                        ||
            UString.startsWith(trimmedSegment, "=>")                        ||
            UString.startsWith(trimmedSegment, "->")                        ||
            UString.startsWith(trimmedSegment, "1)")                        ||
            UString.startsWith(trimmedSegment, "2)")                        ||
            UString.startsWith(trimmedSegment, "3)")                        ||
            UString.startsWith(trimmedSegment, "4)")                        ||
            UString.startsWith(trimmedSegment, "5)")                        ||
            UString.startsWith(trimmedSegment, "6)")                        ||
            UString.startsWith(trimmedSegment, "7)")                        ||
            UString.startsWith(trimmedSegment, "8)")                        ||
            UString.startsWith(trimmedSegment, "9)")                        ||
            UString.startsWithIgnoreCase(trimmedSegment, "<BLOCKQUOTE>")    ||
            UString.startsWithIgnoreCase(trimmedSegment, "<DL>")            ||
            UString.startsWithIgnoreCase(trimmedSegment, "<DT>")            ||
            UString.startsWithIgnoreCase(trimmedSegment, "<DD>")            ||
            UString.startsWithIgnoreCase(trimmedSegment, "<P>")             ||
            UString.startsWithIgnoreCase(trimmedSegment, "<BR>")            ||
            UString.startsWithIgnoreCase(trimmedSegment, "<UL>")            ||
            UString.startsWithIgnoreCase(trimmedSegment, "<LI>")            ||
            UString.startsWithIgnoreCase(trimmedSegment, "ToDo:")           ||
            UString.startsWithIgnoreCase(trimmedSegment, "Tricky Stuff:")   ||
            UString.startsWithIgnoreCase(trimmedSegment, "Big Assumption:") ||
            UString.startsWithIgnoreCase(trimmedSegment, "Assumption:")     ||
            UString.startsWithIgnoreCase(trimmedSegment, "Kludge Alert:")   ||
            UString.startsWithIgnoreCase(trimmedSegment, "Kludge Warning:") ||
            UString.startsWithIgnoreCase(trimmedSegment, "Alert:")          ||
            UString.startsWithIgnoreCase(trimmedSegment, "Warning:")        ||
            UString.startsWithIgnoreCase(trimmedSegment, "Caveat:")         ||
            UString.startsWithIgnoreCase(trimmedSegment, "Notice:")         ||
            UString.startsWithIgnoreCase(trimmedSegment, "Note:")
            )
            {
            currUnit = currIndent + UString.trimRight(currUnit);
            units.add(currUnit);

            currIndent = thisIndent;
            currUnit   = (UString.trimLeft(sgmnt,thisIndent) + " ");
            }
         /*.
         ==========================================================================================
         Otherwise, if this line (segment) has the same indent, it is part of the current unit.
         ------------------------------------------------------------------------------------------ */
         else if (thisIndent.equals(currIndent))
            {
            if ((unitCount > 0) && (currUnit.equals("")))
               {
               units.add(currUnit);
               }
            currUnit += (UString.trimLeft(sgmnt,thisIndent) + " ");
            }
         /*.
         ==========================================================================================
         Otherwise, this line (segment) has a different indent, so save the current unit and start
         a new unit with this segment.
         ------------------------------------------------------------------------------------------ */
         else
            {
            currUnit = currIndent + UString.trimRight(currUnit);
            units.add(currUnit);

            currIndent = thisIndent;
            currUnit   = (UString.trimLeft(sgmnt,thisIndent) + " ");
            }
         unitCount++;
         }
         currUnit = currIndent + UString.trimRight(currUnit);
         units.add(currUnit);
      /*.
      ==========================================================================================
      Wrap all the units
      ------------------------------------------------------------------------------------------ */
      results = new ArrayList<String>();
      for (String  unit : units)
         {
         /*.
         ==========================================================================================
         If capitalization was requested, this is where we do it.
         ------------------------------------------------------------------------------------------ */
         if (pCapitalizer != null)
            {
            unit = pCapitalizer.capitalize(unit);
            }
         /*.
         ==========================================================================================
         The word wrapper will discard empty lines so we have to explicitly put them into the final
         list
         ------------------------------------------------------------------------------------------ */
         if (unit.trim().equals(""))
            {
            results.add("");
            }
         /*.
         ==========================================================================================
         Otherwise, it's not an empty line so wrap the unit into lines and put each line into the
         list
         ------------------------------------------------------------------------------------------ */
         else
            {
            /*.
            ==========================================================================================
            Figure out the unit's indent
            ------------------------------------------------------------------------------------------ */
            String  indent = UString.whitespacePrefix(unit);
            /*.
            ==========================================================================================
            Figure out if this unit starts with a bullet. If it does, we are going to remove the
            bullet, indent the unit enough to accomadate the bullet, wrap the unit, and then put the
            bullet back on the first line.
            ------------------------------------------------------------------------------------------ */
            String   trimmedUnit       = UString.trim(unit);
            String   bullet           = "";
            String   bulletLineIndent = indent;   // this is how much we indent the first line of a bulleted unit
            boolean  isBullet         = false;
            if (UString.startsWith(trimmedUnit, "."))
               {
               isBullet = true;
               bullet   = ". ";
               indent  += "  ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "|"))
               {
               isBullet = true;
               bullet   = "| ";
               indent  += "  ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "=>"))
               {
               isBullet = true;
               bullet   = "=> ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "->"))
               {
               isBullet = true;
               bullet   = "-> ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "1)"))
               {
               isBullet = true;
               bullet   = "1) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "2)"))
               {
               isBullet = true;
               bullet   = "2) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "3)"))
               {
               isBullet = true;
               bullet   = "3) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "4)"))
               {
               isBullet = true;
               bullet   = "4) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "5)"))
               {
               isBullet = true;
               bullet   = "5) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "6)"))
               {
               isBullet = true;
               bullet   = "6) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "7)"))
               {
               isBullet = true;
               bullet   = "7) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "8)"))
               {
               isBullet = true;
               bullet   = "8) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWith(trimmedUnit, "9)"))
               {
               isBullet = true;
               bullet   = "9) ";
               indent  += "   ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWithIgnoreCase(trimmedUnit, "Tricky Stuff:"))
               {
               isBullet = true;
               bullet   = "Tricky Stuff: ";
               indent  += "              ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWithIgnoreCase(trimmedUnit, "Big Assumption:"))
               {
               isBullet = true;
               bullet   = "Big Assumption: ";
               indent  += "                ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWithIgnoreCase(trimmedUnit, "Assumption:"))
               {
               isBullet = true;
               bullet   = "Assumption: ";
               indent  += "            ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWithIgnoreCase(trimmedUnit, "Warning:"))
               {
               isBullet = true;
               bullet   = "Warning: ";
               indent  += "         ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWithIgnoreCase(trimmedUnit, "Caveat:"))
               {
               isBullet = true;
               bullet   = "Caveat: ";
               indent  += "        ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWithIgnoreCase(trimmedUnit, "Notice:"))
               {
               isBullet = true;
               bullet   = "Notice: ";
               indent  += "        ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            else if (UString.startsWithIgnoreCase(trimmedUnit, "Note:"))
               {
               isBullet = true;
               bullet   = "Note: ";
               indent  += "      ";   // this is how much we indent all bulleted unit lines subsequent to the first.
               unit = UString.trimLeft(unit, bulletLineIndent + bullet).toString();
               unit = indent + unit;
               }
            /*.
            ==========================================================================================
            Now wrap the unit. This turns the unit into one or more lines of the right length.
            ------------------------------------------------------------------------------------------ */
            Pattern            pattern = UString.wordWrapPattern(pLineLength - indent.length());
            ArrayList<String>  lines   = UString.wordWrappedLines(UString.trimLeft(unit,indent),pattern);
            /*.
            ==========================================================================================
            Now, for each line produced by wrapping the unit...
            ------------------------------------------------------------------------------------------ */
            for (String ln : lines)
               {
               ln = ln.trim();
               /*.
               ==========================================================================================
               First, take care of some issues that exist only when a capitalizer has been applied.
               ------------------------------------------------------------------------------------------ */
               if (pCapitalizer != null)
                  {
                  /*.
                  ==========================================================================================
                  This gets rid of spurious double spaces in English sentences. We only do this if a
                  capitalizer has been sent into this method because that is an indication that what we are
                  wordwrapping is the English text in a comment.
                  ------------------------------------------------------------------------------------------ */
                  ln = ln.replace("  ", " ");
                  /*.
                  ==========================================================================================
                  The capitalizer, if one is used, may uppercase some letters we don't want changed from
                  lower case. This fixes parameter names in function headers and variable description
                  comments so that the leading letter is not capitalized (the capitalizer may have
                  capitalized it since its the first letter in a line). An example would be a line following
                  a @param line that starts with the parameter name of "PStr", which should be "pStr".
                  ------------------------------------------------------------------------------------------ */
                  if (ln.length() > 1)
                     {
                     /*.
                     ==========================================================================================
                     If the trimmed line begins with two characters and the second one is capitalized then we
                     have a potential variable name with a leading lowercase letter (which may have been
                     capitalized by the capitalizer).
                     ------------------------------------------------------------------------------------------ */
                     char  char1 = ln.charAt(0);
                     char  char2 = ln.charAt(1);
                     if (Character.isLetter(char1) && Character.isLetter(char2) && Character.isUpperCase(char2))
                        {
                        /*.
                        ==========================================================================================
                        Get the first word from the trimmed line
                        ------------------------------------------------------------------------------------------ */
                        ListOfLists<String>  wordsAndDelimiters = getWordsAndDelimiters(ln, " .<>()=;\t\n!+-*/:\r");
                        ArrayList<String>    words              = wordsAndDelimiters.get(0);
                        String               firstWord          = words.get(0);
                        /*.
                        ==========================================================================================
                        If the first word is all upper case, then it's a constant and we should not lower case the
                        first letter. But if it's not all upper case, we will go ahead and lower case the first
                        letter..
                        ------------------------------------------------------------------------------------------ */
                        if ( ! UString.isAllUpperCase(firstWord))
                           {
                           String  str1 = Character.toString(char1);
                           ln = ln.replaceFirst("[" + str1 + "]", str1.toLowerCase());
                           }
                        }
                     }
                  }
               /*.
               ==========================================================================================
               Attach the indent to the line and add it to the results
               ------------------------------------------------------------------------------------------ */
               if (isBullet)
                  {
                  ln = bulletLineIndent + bullet + ln;
                  isBullet = false;   // so only the first line of a bulleted unit gets the bullet put on it
                  results.add(ln);
                  }
               else
                  {
                  ln = indent + ln;
                  results.add(ln);
                  }
               }
            }
         }
      return results;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the length of the longest String representation of the elements of an array.

   <P><B>Implementation: </B><A HREF="UString.java.html#125">View source</A>

   @return
      The length of the longest String representation in the array.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int longestStringLength(Type1[] pArray)
      {
      int  max = 0;
      for (int i=0; i<pArray.length; i++)
         {
         String  str = UString.toString(pArray[i]);
         max = UMath.max(str.length(),max);
         }
      return max;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the length of the longest String representation of the elements of an ArrayList.

   <P><B>Implementation: </B><A HREF="UString.java.html#126">View source</A>

   @return
      The length of the longest String representation in the ArrayList.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int longestStringLength(ArrayList<Type1> pArray)
      {
      int  max  = 0;
      for (Type1  pT : pArray)
         {
         String  str = UString.toString(pT);
         max = UMath.max(str.length(),max);
         }
      return max;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method breaks a mixed case String representation of pStr up into tokens. The start of each word
   in the mixed case string is signaled by a capitalized letter. Each word wil be returned as a
   separate token.

   <P><B>Implementation: </B><A HREF="UString.java.html#127">View source</A>

   @return
      An arrayList containing the tokens.

   @param
      pStr is the object whose String representation is tokenized.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> ArrayList<String> tokenizedMixedCaseString(Type1 pStr)
      {
      String  str        = UString.toString(pStr);
      /*.
      ==========================================================================================
      Separate the words by spaces in a string buffer
      ------------------------------------------------------------------------------------------ */
      char[]        chars         = str.toCharArray();
      StringBuffer  buf           = new StringBuffer();
      boolean       thisCharLower = false;
      boolean       prevCharLower = false;
      for (int i=0; i<chars.length; i++)
         {
         thisCharLower = Character.isLowerCase(chars[i]);
         String  cAsStr = Character.toString(chars[i]);
         /*.
         ==========================================================================================
         If this is the first char in the string there is nothing to do, just put it in the buffer.
         ------------------------------------------------------------------------------------------ */
         if (i==0)
            {
            buf.append(cAsStr);
            }
         else
            {
            /*.
            ==========================================================================================
            If a lower case char is followed by an upper case char, put a space between the two
            characters in the buffer.
            ------------------------------------------------------------------------------------------ */
            if ((prevCharLower) && (!thisCharLower))
               {
               buf.append(" ");
               buf.append(cAsStr);
               }
            /*.
            ==========================================================================================
            If two adjacent upper case chars are followed by a lower case char, put a space between
            the two upper case chars in the buffer
            ------------------------------------------------------------------------------------------ */
            else if ((!prevCharLower) && (!thisCharLower) && i<chars.length-1)
               {
               boolean  nextCharLower = Character.isLowerCase(chars[i+1]);
               if (nextCharLower)
                  {
                  buf.append(" ");
                  buf.append(cAsStr);
                  }
               else
                  {
                  buf.append(cAsStr);
                  }
               }
            else
               {
               buf.append(cAsStr);
               }
            }
         prevCharLower = thisCharLower;
         }
      /*.
      ==========================================================================================
      Convert the buffer to a string
      ------------------------------------------------------------------------------------------ */
      str = new String(buf);
      /*.
      ==========================================================================================
      Tokenize it using the imbedded spaces as delimiters
      ------------------------------------------------------------------------------------------ */
      ArrayList<String>  tokens    = new ArrayList<String>();
      StringTokenizer    tokenizer = new StringTokenizer(str," ");
      while (tokenizer.hasMoreTokens())
         {
         tokens.add(tokenizer.nextToken());
         }
      /*.
      ==========================================================================================
      Return the tokens array
      ------------------------------------------------------------------------------------------ */
      return tokens;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method breaks a the String representation of pStr up into tokens. The tokens in the String are
   delimited by the specified delimiters (all the characters in the delimiters argument are treated as
   delimiters for separating tokens).

   <P><B>Implementation: </B><A HREF="UString.java.html#128">View source</A>

   @return
      An arrayList containing the tokens.

   @param
      pStr is the object whose String representation is tokenized.
   @param
      pDelimiters is the set of delimiters (the characters that separate tokens). Delimiter characters
      themselves will not be treated as tokens.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> ArrayList<String> tokenizedString
      (
      Type1  pStr,
      Type2  pDelimiters
      )
      {
      String  str        = UString.toString(pStr);
      String  delimiters = UString.toString(pDelimiters);

      ArrayList<String>  tokens    = new ArrayList<String>();
      StringTokenizer    tokenizer = new StringTokenizer(str,delimiters);

      while (tokenizer.hasMoreTokens())
         {
         tokens.add(tokenizer.nextToken());
         }
      return tokens;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method breaks the String representation of pStr up into tokens. The tokens in the String are
   delimited by the specified delimiters (all the characters in the delimiters argument are treated as
   delimiters for separating tokens).

   <P><B>Implementation: </B><A HREF="UString.java.html#129">View source</A>

   @return
      An arrayList containing the tokens.

   @param
      pStr is the object whose String representation is tokenized.
   @param
      pDelimiters is the set of delimiters (the characters that separate tokens). Delimiter characters
      themselves will not be treated as tokens.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> ArrayList<String> tokenizedStringIgnoreCase
      (
      Type1  pStr,
      Type2  pDelimiters
      )
      {
      String  str        = UString.toString(pStr);
      String  delimiters = UString.toString(pDelimiters);

      delimiters = UString.charSet
         (
         delimiters.toUpperCase() + delimiters.toLowerCase()
         );

      ArrayList<String>  tokens    = new ArrayList<String>();
      StringTokenizer    tokenizer = new StringTokenizer(str,delimiters);

      while (tokenizer.hasMoreTokens())
         {
         tokens.add(tokenizer.nextToken());
         }
      return tokens;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   Create a String by catenating all the Strings in an ArrayList and separating them from each other
   with the specified delimiter.

   <P><B>Implementation: </B><A HREF="UString.java.html#130">View source</A>

   @return
      A String constructed by catenating all the Strings in an ArrayList together and separating them
      with the specified delimiter.

   @param
      pArrayList is the ArrayList to untokenize.
   @param
      pDelimiter is the delimiter that separates tokens in the string.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String untokenizedArrayList
      (
      ArrayList<Type1>  pArrayList,
      Type2             pDelimiter
      )
      {
      String  delimiter = UString.toString(pDelimiter);

      String  result    = new String();
      int     counter   = 0;

      for (Type1  pT : pArrayList)
         {
         String  str = UString.toString(pT);
         if (counter++ > 0)
            {
            result += delimiter;
            }
         result += str;
         }
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method generates a hex string representation of a byte

   <P><B>Implementation: </B><A HREF="UString.java.html#131">View source</A>

   @return
      A String representation of the byte in hexidecimal format

   @param
      pByte is the byte for which the string is generated.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String toHexString(byte pByte)
      {
      int    value = (pByte & 0x7F) + (pByte < 0 ? 128 : 0);
      String ret   = (value < 16 ? "0" : "");
      ret += Integer.toHexString(value);
      return ret;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method generates a hex string representation of a byte array

   <P><B>Implementation: </B><A HREF="UString.java.html#132">View source</A>

   @return
      A String representation of the bytes in hexidecimal format

   @param
      pByte is the byte array for which the string is generated.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static String toHexString(byte[] pByte)
      {
      StringBuffer  result = new StringBuffer(136);
      for (int i = 0; i < pByte.length; ++i)
         {
         result.append(UString.toHexString(pByte[i]));
         }
      return result.toString();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method removes the leading zeros from a String. It accepts decimal numbers, numbers given by
   the following grammar:
      <BLOCKQUOTE>
         <PRE id="unindent">
            DecodableString := [Sign][leading zeros]IntegerDigits[.]IntegerDigits
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#133">View source</A>

   @return
      A new String that is equivalent to the String argument but with the leading zeros removed.

   @param
      pStr is the String representation of a decimal number to remove the leading zeros from.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String removeLeadingZeros(Type1 pStr)
      {
      String  str = UString.toString(pStr);

      StringBuffer  c = new StringBuffer();
      int           i = 0;
      /*.
      ==========================================================================================
      If there's a sign character ('+' or '-'), copy it to the result string. Note that if the
      input string is malformed in that it has multiple sign characters at its beginning, this
      code will simply copy all of them to the result string, leaving the result string
      malformed as well.
      ------------------------------------------------------------------------------------------ */
      while (i<str.length())
         {
         if ((str.charAt(i) != '+') && (str.charAt(i) != '-')) break;
         c.append(str.charAt(i));
         i++;
         }
      /*.
      ==========================================================================================
      Skip past the leading zeros. We dont go all the way to the end of the string because we
      want to keep the last digit of the string even if it is zero.
      ------------------------------------------------------------------------------------------ */
      while (i<str.length()-1)
         {
         if (str.charAt(i) != '0') break;
         i++;
         }
      /*.
      ==========================================================================================
      Copy what's left of the string Note that if the input string is malformed in that it
      contains invalid characters, this code will simply copy all of them to the result string,
      leaving the result string malformed as well.
      ------------------------------------------------------------------------------------------ */
      while (i<str.length())
         {
         c.append(str.charAt(i));
         i++;
         }
      /*.
      ==========================================================================================
      Return it as a String
      ------------------------------------------------------------------------------------------ */
      return c.toString();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) and counts all the instances of a substring (pOther) that it
   contains.

   <P><B>Implementation: </B><A HREF="UString.java.html#134">View source</A>

   @return
      A count of the number of times the substring pOther is found in the string pStr.

   @param
      pStr is the String to search for instances of pOther.
   @param
      pOther is the substring to count the instances of.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int containsCount(Type1 pStr, Type2 pOther)
      {
      int count        = 0;
      int startingFrom = 0;
      while (true)
         {
         startingFrom = indexOf(pStr,pOther,startingFrom);
         if (startingFrom == (-1)) break;
         count        += 1;
         startingFrom += 1;
         }
      return count;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) and counts all the instances of a substring (pOther) that it
   contains. The search is case-insensitive.

   <P><B>Implementation: </B><A HREF="UString.java.html#135">View source</A>

   @return
      A count of the number of times the substring pOther is found in the string pStr.

   @param
      pStr is the String to search for instances of pOther.
   @param
      pOther is the substring to count the instances of.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int containsCountIgnoreCase(Type1 pStr, Type2 pOther)
      {
      int count        = 0;
      int startingFrom = 0;
      while (true)
         {
         startingFrom = indexOfIgnoreCase(pStr,pOther,startingFrom);
         if (startingFrom == (-1)) break;
         count        += 1;
         startingFrom += 1;
         }
      return count;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains the character in pChar

   <P><B>Implementation: </B><A HREF="UString.java.html#136">View source</A>

   @return
      True if any of the pStr contains pChar

   @param
      pStr is the String to search for the presence of pChar.
   @param
      pChar is the character to search for.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean containsChar(Type1 pStr, char pChar)
      {
      String  str = UString.toString(pStr);

      for (int i=0; i<str.length(); i++)
         {
         if (str.charAt(i) == pChar) return true;
         }
      return false;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains the character in pChar

   <P><B>Implementation: </B><A HREF="UString.java.html#137">View source</A>

   @return
      True if any of the pStr contains pChar

   @param
      pStr is the String to search for the presence of pChar.
   @param
      pChar is the character to search for.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean containsCharIgnoreCase(Type1 pStr, char pChar)
      {
      String  str = UString.noCase(UString.toString(pStr));
      char    chr = UString.noCase(pChar);

      for (int i=0; i<str.length(); i++)
         {
         if (str.charAt(i) == chr) return true;
         }
      return false;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains any of the characters in another String
   (pChars)

   <P><B>Implementation: </B><A HREF="UString.java.html#138">View source</A>

   @return
      True if any of the chars in pChars is in the String pStr

   @param
      pStr is the String to search for the presence of any of the chars in pChars.
   @param
      pChars is the String containing all the characters to search for in pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean containsAnyCharsInString(Type1 pStr, Type2 pChars)
      {
      String  str = UString.toString(pStr);
      String  chr = UString.toString(pChars);

      for (int i=0; i<chr.length(); i++)
         {
         if (str.indexOf(chr.charAt(i)) >= 0) return true;
         }
      return false;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains any of the characters in another String
   (pChars)

   <P><B>Implementation: </B><A HREF="UString.java.html#139">View source</A>

   @return
      True if any of the chars in pChars is in the String pStr

   @param
      pStr is the String to search for the presence of any of the chars in pChars.
   @param
      pChars is the String containing all the characters to search for in pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean containsAnyCharsInStringIgnoreCase
      (
      Type1  pStr,
      Type2  pChars
      )
      {
      String  str = UString.noCase(UString.toString(pStr));
      String  chr = UString.noCase(UString.toString(pChars));

      for (int i=0; i<chr.length(); i++)
         {
         if (str.indexOf(chr.charAt(i)) >= 0) return true;
         }
      return false;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains only characters in another String
   (pChars)

   <P><B>Implementation: </B><A HREF="UString.java.html#140">View source</A>

   @return
      True if all of the chars in pStr are also in the String pChars. If pStr is empty or if any of the
      chars in pStr are NOT also in the String pChars, this method returns false.

   @param
      pStr is the String to search for the presence only of chars in pChars.
   @param
      pChars is the String containing all the characters to search for in pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean containsOnlyCharsInString
      (
      Type1  pStr,
      Type2  pChars
      )
      {
      String  str = UString.toString(pStr);
      String  chr = UString.toString(pChars);

      if (str.length() == 0) return false;
      for (int i=0; i<str.length(); i++)
         {
         if (chr.indexOf(str.charAt(i)) < 0) return false;
         }
      return true;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains only characters in another String
   (pChars)

   <P><B>Implementation: </B><A HREF="UString.java.html#141">View source</A>

   @return
      True if all of the chars in pStr are also in the String pChars. If pStr is empty or if any of the
      chars in pStr are NOT also in the String pChars, this method returns false.

   @param
      pStr is the String to search for the presence only of chars in pChars.
   @param
      pChars is the String containing all the characters to search for in pStr.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean containsOnlyCharsInStringIgnoreCase
      (
      Type1  pStr,
      Type2  pChars
      )
      {
      String  str = UString.noCase(UString.toString(pStr));
      String  chr = UString.noCase(UString.toString(pChars));

      if (str.length() == 0) return false;
      for (int i=0; i<str.length(); i++)
         {
         if (chr.indexOf(str.charAt(i)) < 0) return false;
         }
      return true;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains only characters representing digits - '0'
   '1' '2' '3' '4' '5' '6' '7' '8' '9'

   <P><B>Implementation: </B><A HREF="UString.java.html#142">View source</A>

   @return
      True if all of the chars in pStr are digits. If pStr is empty or if any of the chars in pStr are
      NOT digits, this method returns false.

   @param
      pStr is the String to search for the presence only of digits
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isAllDigits(Type1 pStr)
      {
      String  str = UString.toString(pStr);

      if (str.length() == 0) return false;
      for (int i=0; i<str.length(); i++)
         {
         if ( ! Character.isDigit(str.charAt(i))) return false;
         }
      return true;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method searches a String (pStr) to see if it contains only characters representing letters -
   'A'..'Z' 'a'..'z'

   <P><B>Implementation: </B><A HREF="UString.java.html#143">View source</A>

   @return
      True if all of the chars in pStr are letters. If pStr is empty or if any of the chars in pStr are
      NOT letters, this method returns false.

   @param
      pStr is the String to search for the presence only of letters
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean isAllLetters(Type1 pStr)
      {
      String  str = UString.toString(pStr);

      if (str.length() == 0) return false;
      for (int i=0; i<str.length(); i++)
         {
         if ( ! Character.isLetter(str.charAt(i))) return false;
         }
      return true;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method truncates a string to a specified length

   <P><B>Implementation: </B><A HREF="UString.java.html#144">View source</A>

   @return
      A new string that is a truncated version of the input string

   @param
      pStr is the String to truncate
   @param
      pSize is the size that the string is truncated to.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String truncString(Type1 pStr, int pSize)
      {
      String  str = UString.toString(pStr);

      if (str.equals(""))  return "";
      if (pSize < 1)       return "";

      int  end = UMath.min(pSize,str.length());
      return str.substring(0,end);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method parses a string into words and delimiters.<P>

   For example, assume that 'myString' is a string containing words separated by delimiters. Further,
   assume that the following characters are considered to be the delimiters that separate the words
   from each other in the string: parentheses, spaces, commas, and periods. Then this method could be
   called like this:
      <BLOCKQUOTE>
         <PRE id="unindent">
            ArrayList  wordsAndDelims = Util.getWordsAndDelimiters(myStr, "() ,.")
         </PRE>
      </BLOCKQUOTE>

   Then when getWordsAndDelimiters() returns, the ArrayList wordsAndDelims Would contain two objects,
   one being an ArrayList of the words in myString and the other being an ArrayList of the delimiters
   between the words.<P>

   If 'myString' is this string:
      <BLOCKQUOTE>
         <PRE id="unindent">
            "listen, this is a test... Believe it."
         </PRE>
      </BLOCKQUOTE>


   Then calling this method as described above would return the following:
      <BLOCKQUOTE>
         <PRE id="unindent">
            WordsAndDelims is an ArrayList containing 2 ArrayList objects.

            The first ArrayList contains 7 String objects; each String is one word from myString.

            The second ArrayList contains 7 String objects; each String is one series of consecutive
            delimiters from myString.

            ArrayList words  = (ArrayList)wordsAndDelims.get(0);
            ArrayList delims = (ArrayList)wordsAndDelims.get(1);

            Words would contain these Strings:

               "listen" "this" "is" "a" "test" "believe" "it"

            Delims would contain these Strings:

               ", " " " " " " " "... " " " "."
         </PRE>
      </BLOCKQUOTE>

   If the first characters in 'myString' are delimiters instead of a word, Such as in this String:
      <BLOCKQUOTE>
         <PRE id="unindent">
            "(((listen, this is a test... Believe it.)))"
         </PRE>
      </BLOCKQUOTE>

   Then the first word in the words ArrayList would be the empty String Because the empty String is the
   first token in myString:
      <BLOCKQUOTE>
         <PRE id="unindent">
            Words would contain these Strings:

               "" "listen" "this" "is" "a" "test" "believe" "it"

            Delims would contain these Strings:

               "(((" ", " " " " " " " "... " " " ".)))"
         </PRE>
      </BLOCKQUOTE>

   In other words, the first String in words is the first token in myString, the first String in delims
   is the second token in myString, the second String in words is the third token in myString, the
   second String in delims is the fourth token in myString, etc.<P>

   This approach makes it possible to know the relative order of the word tokens and delimiter tokens.
   To reassemble the original String, the following algorithm will always work because reassembly
   always begins with the first word token and then alternates between successive delimiter and word
   tokens.
      <BLOCKQUOTE>
         <PRE id="unindent">
            MyString = "";
            for (int i=0; I < wordssize(); i++)
               {
               myString += (String)wordsget(i) + (String)delimsget(i);
               }
         </PRE>
      </BLOCKQUOTE>

   Here is a complete segment of code that illustrates how to use GetWordsAndDelimeters():
      <BLOCKQUOTE>
         <PRE id="unindent">
            String myStr = "listen, this is a test Believe it)))";
            ArrayList wordsAndDelims = UtilgetWordsAndDelimiters(myStr, "() ,");
            ArrayList words = (ArrayList)wordsAndDelimsget(0);
            ArrayList delims = (ArrayList)wordsAndDelimsget(1);
            myStr = "";
            for (int i=0; i&#60wordssize(); i++)
               {
               myStr += (String)wordsget(i) + (String)delimsget(i);
               Systemoutprintln((String)wordsget(i) + " " + (String)delimsget(i));
               }
            Systemoutprintln(myStr);
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#145">View source</A>

   @return
      An ArrayList containing two ArrayList objects. The 1st ArrayList object contains the words. The
      2nd ArrayList object contains the delimiters.

   @param
      pStr is the String to parse into words and delimiters.
   @param
      pDelimChars is a string containing all the characters that are to be considered delimiters when
      searching the string.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> ListOfLists<String> getWordsAndDelimiters
      (
      Type1  pStr,
      Type2  pDelimChars
      )
      {
      String  str        = UString.toString(pStr);
      String  delimChars = UString.toString(pDelimChars);

      ListOfLists<String>  result = new ListOfLists<String>();
      ArrayList<String>             delims = new ArrayList<String>();
      ArrayList<String>             words  = new ArrayList<String>();
      StringBuffer                  buf    = null;
      int                           i      = 0;
      /*.
      ==========================================================================================
      Sequence through the string, putting each word into an array of words and each group of
      consecutive delimiter characters into strings and each of those strings into an array of
      delimiters.
      ------------------------------------------------------------------------------------------ */
      while (i<str.length())
         {
         /*.
         ==========================================================================================
         Find the next group of concecutive non-delimiter characters, put them into a single string
         and add the string to the array of word strings.
         ------------------------------------------------------------------------------------------ */
         buf = new StringBuffer();
         while ((i<str.length()) && (delimChars.indexOf(str.charAt(i)) < 0))
            {
            buf.append(str.charAt(i));
            i++;
            }
         words.add(buf.toString());
         /*.
         ==========================================================================================
         Find the next group of concecutive delimiter characters, put them into a single string and
         add the string to the array of delimiter strings.
         ------------------------------------------------------------------------------------------ */
         buf = new StringBuffer();
         while ((i<str.length()) && (delimChars.indexOf(str.charAt(i)) >= 0))
            {
            buf.append(str.charAt(i));
            i++;
            }
         delims.add(buf.toString());
         }
      /*.
      ==========================================================================================
      Put the object containing the array of words and the object containing the array of
      delimiters into an array of objects and pass it back to the calling method
      ------------------------------------------------------------------------------------------ */
      result.add(words);
      result.add(delims);
      return result;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method parses a string into words and delimiters.

   <P><B>Implementation: </B><A HREF="UString.java.html#146">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> ListOfLists<String> getWordsAndDelimitersIgnoreCase
      (
      Type1  pStr,
      Type2  pDelimChars
      )
      {
      String  delimChars = UString.toString(pDelimChars);

      delimChars = UString.charSet
         (
         delimChars.toLowerCase() + delimChars.toUpperCase()
         );

      return UString.getWordsAndDelimiters(pStr,delimChars);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#147">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean contentEqualsIgnoreCase
      (
      Type1          pStr,
      StringBuffer  sb
      )
      {
      return UString.noCase(pStr).contentEquals(UString.noCase(sb.toString()));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#148">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean contentEqualsIgnoreCase
      (
      Type1          pStr,
      CharSequence  cs
      )
      {
      return UString.noCase(pStr).contentEquals(UString.noCase(cs));
      }
   public static <Type1, Type2> boolean contentEqualsIgnoreCase
      (
      Type1  pStr,
      Type2  cs
      )
      {
      return UString.noCase(pStr).contentEquals(UString.noCase(cs));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#149">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean regionMatchesIgnoreCase
      (
      Type1  pStr,
      int    toffset,
      Type2  other,
      int    ooffset,
      int    len
      )
      {
      String  str = UString.toString(pStr);
      String  oth = UString.toString(other);

      return str.regionMatches(true,toffset,oth,ooffset,len);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#150">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean startsWithIgnoreCase
      (
      Type1  pStr,
      Type2  prefix,
      int    toffset
      )
      {
      return UString.noCase(pStr).startsWith(UString.noCase(prefix),toffset);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#151">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean startsWithIgnoreCase(Type1 pStr, Type2 pPrefix)
      {
      return UString.startsWithIgnoreCase(pStr,pPrefix,0);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#152">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean endsWithIgnoreCase(Type1 pStr, Type2 suffix)
      {
      return UString.noCase(pStr).endsWith(UString.noCase(suffix));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#153">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int hashCodeIgnoreCase(Type1 pStr)
      {
      return UString.noCase(pStr).hashCode();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#154">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int indexOfIgnoreCase(Type1 pStr, int ch)
      {
      return UString.noCase(pStr).indexOf(UString.noCase(ch));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#155">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int indexOfIgnoreCase(Type1 pStr, int ch, int fromIndex)
      {
      return UString.noCase(pStr).indexOf(UString.noCase(ch),fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#156">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int lastIndexOfIgnoreCase(Type1 pStr, int ch)
      {
      return UString.noCase(pStr).lastIndexOf(UString.noCase(ch));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#157">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int lastIndexOfIgnoreCase
      (
      Type1  pStr,
      int   ch,
      int   fromIndex
      )
      {
      return UString.noCase(pStr).lastIndexOf(UString.noCase(ch),fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#158">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int indexOfIgnoreCase(Type1 pStr, Type2 other)
      {
      return UString.noCase(pStr).indexOf(UString.noCase(other));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#159">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int indexOfIgnoreCase
      (
      Type1  pStr,
      Type2  other,
      int    fromIndex
      )
      {
      return UString.noCase(pStr).indexOf(UString.noCase(other),fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#160">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int lastIndexOfIgnoreCase(Type1 pStr, Type2 other)
      {
      return UString.noCase(pStr).lastIndexOf(UString.noCase(other));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#161">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int lastIndexOfIgnoreCase
      (
      Type1  pStr,
      Type2  other,
      int    fromIndex
      )
      {
      return UString.noCase(pStr).lastIndexOf(UString.noCase(other),fromIndex);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#162">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String replaceIgnoreCase
      (
      Type1  pStr,
      char  oldChar,
      char  newChar
      )
      {
      String  str = UString.toString(pStr);

      if (oldChar != newChar)
         {
         int     len = str.length();
         int     i   = -1;
         char[]  val = str.toCharArray();
         int     off = 0;

         while (++i < len)
            {
            if (UString.noCase(val[off + i]) == UString.noCase(oldChar))
               {
               break;
               }
            }
         if (i < len)
            {
            char  buf[] = new char[len];
            for (int j = 0 ; j < i ; j++)
               {
               buf[j] = val[off+j];
               }
            while (i < len)
               {
               char  c = val[off + i];
               buf[i] = (UString.noCase(c) == UString.noCase(oldChar)) ? newChar : c;
               i++;
               }
            return new String(buf);
            }
         }
      return str;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#163">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> boolean matchesIgnoreCase(Type1 pStr, Type2 regex)
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);

      Pattern p = Pattern.compile(rgx,Pattern.CASE_INSENSITIVE);
      Matcher m = p.matcher(str);
      return m.matches();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#164">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> boolean containsIgnoreCase(Type1 pStr, CharSequence s)
      {
      return UString.indexOfIgnoreCase(pStr,s) > -1;
      }
   public static <Type1, Type2> boolean containsIgnoreCase(Type1 pStr, Type2 pS)
      {
      return UString.indexOfIgnoreCase(pStr,pS) > -1;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces instances of substrings matching the regular expression in regex with a string
   generated from the regular expression in replacement.<P>

   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#165">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> String replaceFirstIgnoreCase
      (
      Type1  pStr,
      Type2  regex,
      Type3  replacement
      )
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);
      String  rpl = UString.toString(replacement);

      returnb>
         (
         Pattern.
            compile(rgx,Pattern.CASE_INSENSITIVE).
               matcher(str).
                  replaceFirst(rpl)
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces instances of substrings matching the regular expression in regex with a string
   generated from the regular expression in replacement.<P>

   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#166">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> String replaceAllIgnoreCase
      (
      Type1  pStr,
      Type2  regex,
      Type3  replacement
      )
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);
      String  rpl = UString.toString(replacement);

      returnb>
         (
         Pattern.
            compile(rgx,Pattern.CASE_INSENSITIVE).
               matcher(str).
                  replaceAll(rpl)
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#167">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String replaceIgnoreCase
      (
      Type1          pStr,
      CharSequence  target,
      CharSequence  replacement
      )
      {
      String  str = UString.toString(pStr);

      returnb>
         (
         Pattern.
            compile(target.toString(), Pattern.LITERAL | Pattern.CASE_INSENSITIVE).
               matcher(str).
                  replaceAll(Matcher.quoteReplacement(replacement.toString()))
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#168">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> String replaceIgnoreCase
      (
      Type1  pStr,
      Type2  target,
      Type3  replacement
      )
      {
      String  str = UString.toString(pStr);

      returnb>
         (
         Pattern.
            compile(UString.toString(target), Pattern.LITERAL | Pattern.CASE_INSENSITIVE).
               matcher(str).
                  replaceAll(Matcher.quoteReplacement(UString.toString(replacement)))
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P>
      <B>
         Implementation:
      </B>
   <A HREF="UString.java.html#159">View source</A>

   <P><B>Implementation: </B><A HREF="UString.java.html#169">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String[] splitIgnoreCase
      (
      Type1  pStr,
      Type2  regex,
      int    limit
      )
      {
      String  str = UString.toString(pStr);
      String  rgx = UString.toString(regex);

      returnb>
         (
         Pattern.compile(rgx,Pattern.CASE_INSENSITIVE).split(str,limit)
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name (minus
   "IgnoreCase') in the JDK SE API String Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">
         View JDK SE API String Class
      </A>

   <P><B>Implementation: </B><A HREF="UString.java.html#170">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> String[] splitIgnoreCase(Type1 pStr, Type2 regex)
      {
      return UString.splitIgnoreCase(pStr,regex,0);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method reverses the characters in a string

   <P><B>Implementation: </B><A HREF="UString.java.html#171">View source</A>

   @return
      A new string that is a reversed version of the input string

   @param
      pStr is the String to reverse
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String reverse(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      StringBuilder  bldr = new StringBuilder(str);
      return bldr.reverse().toString();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method finds the end of a delimited span of characters within a string. A comment is an example
   of a delimited span but a delimited span may be any sequence of characters that has a defined begin
   delimiter and a defined end delimiter.<P>

   Assumption: This method assumes that the start delimiter has already been located and the pStart
               Parameter is the next index after the end of the start delimiter. IOW, it assumes that
               pStart is inside the span of characters<P>

   For Example, if you want to delete a multiline comment in a language that delimits multiline
   comments with a ## ## pair and this is the string
      <BLOCKQUOTE>
         <PRE id="unindent">
            String:  " int j = 0;\\n## skip past the\\n##blooming##whitespace ##\\nfor (i=str.length(); i>0; i--)"
            Index:    01234567890 123456789012345678 901234567890123456789012345 678901234567890123456
                                      ^__pStart is passed this                   ^__this method returns this
                                         index                                      index
         </PRE>
      </BLOCKQUOTE>

   Then this is the code for using this method:
      <BLOCKQUOTE>
         <PRE id="unindent">
            //.
            =========================================================================================
            these are the regular expressions for the delimiters we will be searching for
            ----------------------------------------------------------------------------------------- //
            String  startDelimiterPattern = Pattern.quote("##");
            String  endDelimiterPattern   = Pattern.quote("##");
            //.
            =========================================================================================
            this is the string we will be searching for them in
            ----------------------------------------------------------------------------------------- //
            String  theString = " int j = 0; \\n## skip past the\\n##blooming##whitespace ##\\nfor (i=str.length(); i>0; i--)";
            //.
            =========================================================================================
            Starting from the beginning of the string (starting index 0) find the first instance of a
            start delimiter (if there is one)
            ----------------------------------------------------------------------------------------- //
            int[]  searchResults        = UString.indexOfRegexIgnoreCase(theString, startDelimiterPattern, 0);
            int    startDelimiterIdx    = searchResults[0];
            int   startDelimiterLength = searchResults[2];
            //.
            =========================================================================================
            if we found one...
            ----------------------------------------------------------------------------------------- //
            if (startDelimiterIdx != (-1))
               {
               //.
               =========================================================================================
               go find its matching end delimiter and if found, get the index of the first character in
               string after the end of the end delimiter.
               ----------------------------------------------------------------------------------------- //
               int  idxAfterComment = UString.indexAfterDelimitedSpanRegex(theString, startDelimiterPattern, endDelimiterPattern, startDelimiterIdx + startDelimiterLength);
               //.
               =========================================================================================
               if we found the end delimiter...
               ----------------------------------------------------------------------------------------- //
               if (idxAfterComment != (-1))
               {
                  //.
                  =========================================================================================
                  remembering our objective of removing the start and end delimiter and everything
                  inbetween from the String, convert the String to a StringBuffer so we can do the delete,
                  then convert it back to a String for printing.
                  ----------------------------------------------------------------------------------------- //
                  StringBuffer  workArea = new StringBuffer(theString);
                  workArea = workArea.delete(startDelimiterIdx, idxAfterComment);
                  System.out.println(workArea.toString());
                  }
               }
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#172">View source</A>

   @return
      If this method finds the end delimiter, it returns the index of the next character AFTER the end
      of the end delimiter. If it doesn't find an end delimiter, it returns -1

   @param
      pStr is the String to search within for the end delimiter.
   @param
      pStartDelimiterPattern is a string containing a regular expression that marks the beginning of
      the span of characters to find the end of.
   @param
      pEndDelimiterPattern is a string containing a regular expression that marks the end of the span
      of characters to find the end of.
   @param
      pStart is the index of the character in pStr from which to start looking for the end of the span
      of characters.
   @param
      pRecurse tells this method whether or not to recognize nested delimited substrings. If this is
      set to true, then nested substrings are recursively processes and therefor require their own
      endDelimiter. This parameter is also usually needed for source code file comment processing. A
      "to end of line" comment type such as the double forward slash in c-type languages or the single
      quote in basic-type languages uses the newline as a comment terminator (endDelimiter). If a
      double forward slash or single quote is embedded in the string before the terminating newline of
      the the first startDelimiter, then there is not a matching newline for both startDelimiters. So
      recursively processing the second startDelimiter would lead to bizzar results as second
      startDelimiter would "eat" the first startDelimiter's corresponding endDelimiter. This in turn
      would cause this method to continue eating characters (inappropriately) on behalf of the first
      startDelimiter until another newline was encountered. So setting pRecurse to false will
      short-circuit the processing of nested "to-end-of-line" comments if desired.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static int indexAfterDelimitedSpanRegex(String pStr, String pStartDelimiterPattern, String pEndDelimiterPattern, int pStart, boolean pRecurse)
      {
      int  start = pStart;
      /*.
      ==========================================================================================
      Every time we come in here, we increment the recurse counter and every time we return out
      of here we decrement it.
      ------------------------------------------------------------------------------------------ */
      cRecurseCounter++;
      /*.
      ==========================================================================================
      This should not happen, but if it does...
      ------------------------------------------------------------------------------------------ */
      if (pStart >= pStr.length())
         {
         cRecurseCounter--;
         return (-1);   // malformed string
         }
      /*.
      ==========================================================================================
      This brings infinite recursion to a screeching halt. I just arbitrarily decided that the
      delimited sections of the string are not going to be nested 10 or more deep and so if the
      recursion count reaches that magic number, we halt and throw an exception.
      ------------------------------------------------------------------------------------------ */
      if (cRecurseCounter == 10)
         {
         System.out.println("!! RECURSE PROBLEM !!  " + pStr.substring(Math.max(0,pStart-250), Math.min(pStr.length()-1,pStart+250)));
         try {throw new Exception();}
         catch (Exception e)
            {
            for (StackTraceElement el : e.getStackTrace())
               {
               System.out.println(el.toString());
               }
            }
         System.exit(-1);
         }
      /*.
      ==========================================================================================
      Search for the end delimiter that corresponds to the start delimiter that was already
      located prior to the call to this method
      ------------------------------------------------------------------------------------------ */
      while (true)
         {
         /*.
         ==========================================================================================
         Find the next start delimiter - the first one after the one that was already located prior
         to the call to this method. Why are we looking for a start delimiter when we already
         assume one was found prior to this method being called (see ASSUMPTIONS)? Because of
         nesting. If we find another start delimiter and it comes before the first end delimiter we
         find, then we know it is nested and the end delimiter is not the matching end delimiter
         we're looking for. So, when that happens, assuming the string is not malformed, we're
         going to be doing some recursion
         ------------------------------------------------------------------------------------------ */
         int[]  searchResults        = UString.indexOfRegexIgnoreCase(pStr, pStartDelimiterPattern, start);
         int    startDelimiterIdx    = searchResults[0];
         int   startDelimiterLength = searchResults[2];
         /*.
         ==========================================================================================
         Find the first end delimiter.
         ------------------------------------------------------------------------------------------ */
         searchResults            = UString.indexOfRegexIgnoreCase(pStr, pEndDelimiterPattern, start);
         int   endDelimiterIdx    = searchResults[0];
         int  endDelimiterLength = searchResults[2];
         /*.
         ==========================================================================================
         This does not happen in a properly formed string because we already know there is a start
         delimiter (that's why this method was called) and so there is supposed to be a
         corresponding end delimiter. But if there is no end delimiter, return a code indicating as
         much.
         ------------------------------------------------------------------------------------------ */
         if (endDelimiterIdx == (-1))
            {
            cRecurseCounter = 0;
            return (-1);   // malformed string
            }
         /*.
         ==========================================================================================
         Otherwise, an end delimiter was found so ...
         ------------------------------------------------------------------------------------------ */
         ifb>
            (
            /*.
            ==========================================================================================
            If no additional start delimiter was found OR
            ------------------------------------------------------------------------------------------ */
            (startDelimiterIdx == (-1))           ||
            /*.
            ==========================================================================================
            Another start delimiter was found but it is beyond the end delimiter OR
            ------------------------------------------------------------------------------------------ */
            (startDelimiterIdx > endDelimiterIdx) ||
            /*.
            ==========================================================================================
            Another start delimiter was found and it comes before the end delimiter but recursion is
            turned off
            ------------------------------------------------------------------------------------------ */
            (! pRecurse)
            )
            /*.
            ==========================================================================================
            Then this is the end delimiter we're looking for. Return the index of the next character
            after it.
               This is the only "non-error" way out of this method.
            ------------------------------------------------------------------------------------------ */
            {
            cRecurseCounter--;
            return (endDelimiterIdx + endDelimiterLength);
            }
         /*.
         ==========================================================================================
         Otherwise,
            An additional start delimiter was found AND it comes before the end delimiter AND
            recursion is turned on
               So, recurse and find its corresponding end delimiter
         And then skip past the nested start-end delimiter pair and go back up to the top of the
         loop and continue searching for the original start delimiter's corresponding end delimiter
         ------------------------------------------------------------------------------------------ */
         else
            {
            if (pRecurse)
               {
               start = UString.indexAfterDelimitedSpanRegex(pStr, pStartDelimiterPattern, pEndDelimiterPattern, startDelimiterIdx + startDelimiterLength, pRecurse);
               }
            }
         }
      }


   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method signature allows the user (by way of setting the pRecurse argument to false) to prevent
   the preceeding method from recursing.

   <P><B>Implementation: </B><A HREF="UString.java.html#173">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> int indexAfterDelimitedSpanRegex(Type1 pStr, Type2 pStartDelimiterPattern, Type3 pEndDelimiterPattern, int pStart, boolean pRecurse)
      {
      String  str                   = UString.toString(pStr);
      String  startDelimiterPattern = UString.toString(pStartDelimiterPattern);
      String  endDelimiterPattern   = UString.toString(pEndDelimiterPattern);
      return UString.indexAfterDelimitedSpanRegex(str, startDelimiterPattern, endDelimiterPattern, pStart, pRecurse);
      }


   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method signature effectively makes the pRecurse parameter of the preceeding method an optional
   parameter with a default value of true.

   <P><B>Implementation: </B><A HREF="UString.java.html#174">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> int indexAfterDelimitedSpanRegex(Type1 pStr, Type2 pStartDelimiterPattern, Type3 pEndDelimiterPattern, int pStart)
      {
      return UString.indexAfterDelimitedSpanRegex(pStr, pStartDelimiterPattern, pEndDelimiterPattern, pStart, true);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method finds the end of a delimited span of characters within a String. A comment is an example
   of a delimited span but a delimited span may be any sequence of characters that has a defined begin
   delimiter and a defined end delimiter.<P>

   Assumption: This method assumes that the start delimiter has already been located and the pStart
               Parameter is the next index after the end of the start delimiter. IOW, it assumes that
               pStart is inside the span of characters<P>

   For Example, if you want to delete a multiline comment in a language that delimits multiline
   comments with a <* *> pair and this is the XString

      <BLOCKQUOTE>
         <PRE id="unindent">
            String:   " int j = 0;\\n<* skip past the\\n<*blooming*>whitespace *>\\nfor (i=str.length(); i>0; i--)"
            Index:     01234567890 123456789012345678 901234567890123456789012345 678901234567890123456
                                       ^__pStart is passed this                   ^__this method returns this
                                          index                                      index
         </PRE>
      </BLOCKQUOTE>

   Then this is the code for using this method:

      <BLOCKQUOTE>
         <PRE id="unindent">
            String theString      = " int j = 0; \\n<* skip past the\\n<*blooming*>whitespace *>\\nfor (i=str.length(); i>0; i--)";
            String startDelimiter = "<*";
            String endDelimiter   = "*>";

            int startDelimiterIdx   = theString.indexOf(startDelimiter);
            int idxAfterComment     = UString.indexAfterDelimitedSpan(theString, startDelimiter, endDelimiter, startDelimiterIdx + startDelimiter.length());
            String commentlessString = theString.substring(0, startDelimiterIdx) + theString.substring(idxAfterComment, theString.length());

            System.out.println(commentlessString);
         </PRE>
      </BLOCKQUOTE>

   <P><B>Implementation: </B><A HREF="UString.java.html#175">View source</A>

   @return
      If this method finds the end delimiter, it returns the index of the next character AFTER the end
      of the end delimiter. If it doesn't find an end delimiter, it returns -1

   @param
      pStr is the String to search within for the end delimiter.
   @param
      pStartDelimiter is a String that marks the beginning of the span of characters to find the end of
   @param
      pEndDelimiter is a String that marks the end of the span of characters to find the end of
   @param
      pStart is the index of the character in pStr from which to start looking for the end of the span
      of characters.
   @param
      pRecurse tells this method whether or not to recognize nested delimited substrings. If this is
      set to true, then nested substrings are recursively processes and therefor require their own
      endDelimiter. This parameter is also usually needed for source code file comment processing. A
      "to end of line" comment type such as the double forward slash in c-type languages or the single
      quote in basic-type languages uses the newline as a comment terminator (endDelimiter). If a
      double forward slash or single quote is embedded in the string befor the terminating newline of
      the the first startDelimiter, then there is not a matching newline for both startDelimiters. So
      recursively processing the second startDelimiter would lead to bizzar results as second
      startDelimiter would "eat" the first startDelimiter's corresponding endDelimiter. This in turn
      would cause this method to continue eating characters (inappropriately) on behalf of the first
      startDelimiter until another newline was encountered. So pRecurse is provided to short-circuit
      the processing of nested "to-end-of-line" comments if desired.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static int indexAfterDelimitedSpan(String pStr, String pStartDelimiter, String pEndDelimiter, int pStart, boolean pRecurse)
      {
      String  startDelimiterPattern = Pattern.quote(pStartDelimiter);
      String  endDelimiterPattern   = Pattern.quote(pEndDelimiter);
      return UString.indexAfterDelimitedSpanRegex(pStr, startDelimiterPattern, endDelimiterPattern, pStart, pRecurse);
      }


   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method signature allows the user (by way of setting the pRecurse argument to false) to prevent
   the preceeding method from recursing.

   <P><B>Implementation: </B><A HREF="UString.java.html#176">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> int indexAfterDelimitedSpan(Type1 pStr, Type2 pStartDelimiter, Type3 pEndDelimiter, int pStart, boolean pRecurse)
      {
      String  str            = UString.toString(pStr);
      String  startDelimiter = UString.toString(pStartDelimiter);
      String  endDelimiter   = UString.toString(pEndDelimiter);
      return UString.indexAfterDelimitedSpan(str, startDelimiter, endDelimiter, pStart, pRecurse);
      }


   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method signature effectively makes the pRecurse parameter of the preceeding method an optional
   parameter with a default value of true.

   <P><B>Implementation: </B><A HREF="UString.java.html#177">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> int indexAfterDelimitedSpan(Type1 pStr, Type2 pStartDelimiter, Type3 pEndDelimiter, int pStart)
      {
      return UString.indexAfterDelimitedSpan(pStr, pStartDelimiter, pEndDelimiter, pStart, true);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns the indexs within a string of the start and end of the first occurrence of a
   substring that matches a specified regular expression, found by a search starting at the specified
   index. If no match is found, -1s are returned.

   <P><B>Implementation: </B><A HREF="UString.java.html#178">View source</A>

   @return
      This method returns an array of integers containg three elements:
         <BLOCKQUOTE>
            => Element 0 (i.e. Result[0]): contains the start index, i.e. The index OF the first
               Character In the first occurrence of the regex-specified substring, found by a search
               starting at the specified index, or -1 if there is no such occurrence.<BR>
            => Element 1 (i.e. Result[1]): contains the end index, i.e. The index AFTER the last
               Character In the first occurrence of the regex-specified substring, found by a search
               starting at the specified index, or -1 if there is no such occurrence.<BR>
            => Element 2 (i.e. Result[2]): contains the length of the first occurrence of the
               Regex-specified substring, found by a search starting at the specified index, i.e.
               Result[1] - result[0], or -1 if there is no such occurrence.<BR>
         </BLOCKQUOTE>

      Note that if a matching substring is not found, all three elements of the returned array of
      integers will contain a -1.

   @param
      pStr is an Object whose String representation is searched for a substring that matches a regular
      expression.
   @param
      pPattern is an Object whose String representation is used as the regular expression. For the
      specification of valid regular expression constructs, see:
         <BLOCKQUOTE>
            <A href="http://docs.oracle.com/javase/8/docs/api/index.html">
               Valid Regular Expression Constructs
            </A>
         </BLOCKQUOTE>
   @param
      pFromIdx is the index of the character in pStr from which to start the search.
   @param
      pIgnoreCase tells this method whether or not to apply the Pattern.CASE_INSENSITIVE flag to the
      regular expression. This works as an alternative to including the (?i) construct within the
      regular expression - pPattern - that is passed into this method. If (?i) is included in pPattern,
      setting pIgnoreCase to false will not have the [likely] intended effect; it will not disable the
      (?i) that is included in pPattern. Setting pIgnoreCase to true is effectively the same as placing
      (?i) at the beginning of pPattern - it causes the matching process to be case-insensitive.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int[] indexOfRegex(Type1 pStr, Type2 pPattern, int pFromIdx, boolean pIgnoreCase)
      {
      /*.
      ==========================================================================================
      This is where the results of the search go; this is the variable that will be returned.
      ------------------------------------------------------------------------------------------ */
      int[]  result = new int[3];
      /*.
      ==========================================================================================
      Convert the generic types to Strings.
      ------------------------------------------------------------------------------------------ */
      String   str        = UString.toString(pStr);
      String   patternStr = UString.toString(pPattern);
      /*.
      ==========================================================================================
      Don't do anything stupid; if the search-from index is beyond the end of the String, don't
      try to search.
      ------------------------------------------------------------------------------------------ */
      if (pFromIdx >= str.length())
               {
               result[0] = -1;
               result[1] = -1;
               result[2] = -1;
               return result;
               }
      /*.
      ==========================================================================================
      This is a fix for legacy code. Some legacy code looks for PRE and CODE tags without but
      ignores the case where either tag has attributes. Change things so if the tag has
      attributes, it can still be found.
      ------------------------------------------------------------------------------------------ */
      if (patternStr.equals("\\Q<PRE>\\E"))  patternStr = Const.REGEX_PRE_START_TAG;
      if (patternStr.equals("\\Q<CODE>\\E")) patternStr = Const.REGEX_CODE_START_TAG;
      /*.
      ==========================================================================================
      Prepare for a regex search
      ------------------------------------------------------------------------------------------ */
      Pattern  pattern;
      if (pIgnoreCase) pattern = Pattern.compile(patternStr, Pattern.CASE_INSENSITIVE);
      else             pattern = Pattern.compile(patternStr);
      Matcher  matcher = pattern.matcher(str.substring(pFromIdx, str.length()));
      /*.
      ==========================================================================================
      Search and if a match is found, return the start and end indexes as well as the length of
      the matching substring.
      ------------------------------------------------------------------------------------------ */
      if (matcher.find())
         {
         result[0] = pFromIdx + matcher.start();
         result[1] = pFromIdx + matcher.end();
         result[2] = result[1] - result[0];
         }
      /*.
      ==========================================================================================
      If no match was found, return -1
      ------------------------------------------------------------------------------------------ */
      else
         {
         result[0] = -1;
         result[1] = -1;
         result[2] = -1;
         }
      /*.
      ==========================================================================================
      Return the results
      ------------------------------------------------------------------------------------------ */
      return result;
      }


   public static <Type1, Type2> int[] indexOfRegex(Type1 pStr, Type2 pPattern, int pFromIdx)
      {
      return indexOfRegex(pStr, pPattern, pFromIdx, false);
      }


   public static <Type1, Type2> int[] indexOfRegexIgnoreCase(Type1 pStr, Type2 pPattern, int pFromIdx)
      {
      return indexOfRegex(pStr, pPattern, pFromIdx, true);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method counts the newlines ('\n') between two indexes in a string.

   <P><B>Implementation: </B><A HREF="UString.java.html#179">View source</A>

   @return
      This method returns the number of newlines ('\n') between the two indexes in a string.

   @param
      pStr is an Object whose String representation is searched for newlines
   @param
      pStart is the index of the character in pStr from which to start the search.
   @param
      pEnd is the index of the character in pStr at which to stop the search.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> int lineCount(Type1 pStr, int pStart, int pEnd)
      {
      String  str       = UString.toString(pStr);
      int     start     = UMath.max(0, pStart);
      int     end       = UMath.min(str.length()-1, pEnd);
      int     lines     = 1;
      for (int idx = start; idx <= end; idx++)
         {
         if (str.charAt(idx) == '\n') lines++;
         }
      return lines;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns an ArrayList of the MatchResults for all the matches of a regular expression
   within a String.

   <P><B>Implementation: </B><A HREF="UString.java.html#180">View source</A>

   @return
      This method returns an ArrayList<MatchResult> where each element of the ArrayList is a
      MatchResult for one match of a regular expression to a String. All the matches of the regular
      expression within the String are returned as MatchResults in the ArrayList.

   @param
      pStr is the Object whose String representation is searched for matches to a regular expression.
   @param
      pRegex is the Object whose String representation is used as the regular expression.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> ArrayList<MatchResult> matchResults(Type1 pStr, Type2 pRegex)
      {
      ArrayList<MatchResult>  results = new ArrayList<MatchResult>();
      String                  str     = UString.toString(pStr);
      String                  regex   = UString.toString(pRegex);
      Pattern                 p       = Pattern.compile(regex);
      Matcher                 m       = p.matcher(str);
      while (m.find())
         {
         results.add(m.toMatchResult());
         }
      return results;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns an ListOfLists<String>, with each inner ArrayList<String> containing all the
   groups (Strings) returned from a regular expression match on a String. All the regular expression
   matches on the String are represented as separate ArrayList<String> in the outer ArrayList.<P>
      <BLOCKQUOTE>
         => There is a one-to-one correspondence between each match and the outer ArrayList elements.
         => There is a one-to-one correspondence between the groups in a match and the inner
            ArrayList<String> elements for that match.
      </BLOCKQUOTE>

   Note: To ensure the one-to-one correspondence between the groups in a match and the inner
         ArrayList<String> elements for that match, it is possible for an element to have a null value
         instead of a String. This can happen if a particular match does not have any data for one f
         the groups that the regular expression specifies

   <P><B>Implementation: </B><A HREF="UString.java.html#181">View source</A>

   @return
      This method returns an ListOfLists<String>, with each inner ArrayList<String> containing all the
      groups (Strings) returned from a regular expression match on a String. All the regular expression
      matches on the String are represented as separate ArrayList<String> in the outer ArrayList.

   @param
      pStr is the Object whose String representation is searched for matches to a regular expression.
   @param
      pRegex is the Object whose String representation is used as the regular expression.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> ListOfLists<String> matchResultsGroups(Type1 pStr, Type2 pRegex)
      {
      ListOfLists<String>     groupListList = new ListOfLists<String>();
      ArrayList<MatchResult>  matchResults  = UString.matchResults(pStr, pRegex);
      for (MatchResult m : matchResults)
         {
         ArrayList<String>  groupList = new ArrayList<String>();
         for (int groupNumber = 0; groupNumber < m.groupCount(); groupNumber++)
            {
            String  thisGroup = m.group(groupNumber);
            groupList.add(thisGroup);
            }
         groupListList.add(groupList);
         }
      return groupListList;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns an ArrayList of HashMaps. For every match of a regular expression to a String,
   if a matching substring was found for any of an ArrayList of group names within the larger match,
   then the group name and its matched substring are put into a HashMap which is in turn put into an
   ArrayList. So the ArrayList ends up having one HashMap for each match that includes a matching
   substring for one or more of the group names.

   <P><B>Implementation: </B><A HREF="UString.java.html#182">View source</A>

   @return
      This method returns an ArrayList of HashMaps. For every match of a regular expression to a
      String, if a matching substring was found for any of an ArrayList of group names within the
      larger match, then the group name and its matched substring are put into a HashMap which is in
      turn put into an ArrayList. So the ArrayList ends up having one HashMap for each match that
      includes a matching substring for one or more of the group names.

   @param
      pStr is the Object whose String representation is searched for matches to a regular expression.
   @param
      pRegex is the Object whose String representation is used as the regular expression.
   @param
      pGroupNames is an ArrayList of Objects whose String representations are used as the group names
      to find matches for.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2, Type3> ListOfMaps<String, String> matchNamedGroupResults(Type1 pStr, Type2 pRegex, ArrayList<Type3> pGroupNames)
      {
      ListOfMaps<String,String>  results = new ListOfMaps<String,String>();
      String                     str     = UString.toString(pStr);
      String                     regex   = UString.toString(pRegex);
      Pattern                    p       = Pattern.compile(regex);
      Matcher                    m       = p.matcher(str);
      while (m.find())
         {
         HashMap<String,String>  hashMap = new HashMap<String,String>();
         for (Type3 groupName : pGroupNames)
            {
            String  groupNameStr = UString.toString(groupName);
            String  groupString  = m.group(groupNameStr);
            if (groupString != null)
               {
               hashMap.put(groupNameStr, groupString);
               }
            }
         if (! hashMap.isEmpty())
            {
            results.add(hashMap);
            }
         }
      return results;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns a count of the number of times a substring occurs in a String.

   <P><B>Implementation: </B><A HREF="UString.java.html#183">View source</A>

   @return
      This method returns a count of the number of times a substring occurs in a String.

   @param
      pStr is the Object whose String representation is searched for occurrences of a substring.
   @param
      pSubStr is the Object whose String representation is the substring that is searched for in a
      String.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int substringCount(Type1 pStr, Type2 pSubStr)
      {
      String  str    = UString.toString(pStr);
      String  subStr = UString.toString(pSubStr);
      int     count  = 0;
      int     idx    = 0;
      while ((idx = str.indexOf(subStr, idx)) != (-1))
         {
         idx++;
         count++;
         }
      return count;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method returns a count of the number of times a substring occurs in a String. It ignores case
   in making comparisons of the substring against the String.

   <P><B>Implementation: </B><A HREF="UString.java.html#184">View source</A>

   @return
      This method returns a count of the number of times a substring occurs in a String.

   @param
      pStr is the Object whose String representation is searched for occurrences of a substring.
   @param
      pSubStr is the Object whose String representation is the substring that is searched for in a
      String.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1, Type2> int substringCountIgnoreCase(Type1 pStr, Type2 pSubStr)
      {
      String  str    = UString.toString(pStr).toUpperCase();
      String  subStr = UString.toString(pSubStr).toUpperCase();
      return substringCountIgnoreCase(str, subStr);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method uses a regular expression in the replaceAll method to remove all whitespace chars from a
   string.

   <P><B>Implementation: </B><A HREF="UString.java.html#185">View source</A>

   @return
      A new string that is a copy of the input string but with all the whitespace removed.

   @param
      pStr is the Object from whose String representation all whitespace is removed.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1> String removeWhitespace(Type1 pStr)
      {
      String  str = UString.toString(pStr);
      return str.replaceAll("\\s", "");
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This boilerplate method is used for testing this class and may include any code the developer
   chooses.

   <P><B>Implementation: </B><A HREF="UString.java.html#186">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static void test() throws Exception
      {
      System.out.println
         (
         "\"HELLO WORLD!\"  I'm the  UString  class, and I approved this message."
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method allows this class file to be unit tested as a standalone application. It's the method
   that's called when the class is invoked from the command line by using the java application launcher
   - "java". Main() is not a required method, but the practice of putting one in each class and
   wrapping class test code within it allows easy unit testing of the class; and main does not need to
   be removed when testing is complete.

   <P>
      <DL>
         <DT>
            <B>
               Command line usage:
            </B>
            <DD>
               Java cosmicabyss.com.utl.UString
            </DD>
         </DT>
      </DL>

   <P><B>Implementation: </B><A HREF="UString.java.html#187">View source</A>

   @param
      pArgs contains the command line arguments with which this class was invoked as an application.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static void main(String[] pArgs) throws Exception
      {
      /*.
      ==========================================================================================
      Test code
      ------------------------------------------------------------------------------------------ */
      UString.test();

      int lineNo = 0;
      XStringsIterator xi = new XStringsIterator("UString.java");
      while (xi.hasNext())
         {
         lineNo++;

         XString line = xi.next();
         XString lineNoStr = new XString(lineNo);

         lineNoStr = lineNoStr.alignRight(6, '0');
         lineNoStr = lineNoStr.alignLeft(10, ' ');

         if (line.toUpperCase().contains("PRE>"))
            {
            System.out.println(lineNoStr.string() + line.string());
            }
         }

      lineNo = 0;
      xi = new XStringsIterator("UString.java");
      while (xi.hasNext())
         {
         lineNo++;

         XString line = xi.next();
         XString lineNoStr = new XString(lineNo);

         lineNoStr = lineNoStr.alignRight(6, '0');
         lineNoStr = lineNoStr.alignLeft(10, ' ');

         if (line.toUpperCase().contains("CODE>"))
            {
            System.out.println(lineNoStr.string() + line.string());
            }
         }


      lineNo = 0;
      xi = new XStringsIterator("UString.java");
      while (xi.hasNext())
         {
         lineNo++;

         XString line = xi.next();
         XString lineNoStr = new XString(lineNo);

         lineNoStr = lineNoStr.alignRight(6, '0');
         lineNoStr = lineNoStr.alignLeft(10, ' ');

         if (line.toUpperCase().contains("//") && (line.toUpperCase().contains("PRE>") || line.toUpperCase().contains("CODE>")))
            {
            System.out.println(lineNoStr.string() + line.string());
            }
         }


      String original = "a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 ! @ # $ % ^ & * ( ) _ + = - ` ~ < > ? \" : { } | [ ] \\ ; ' , . /";
      String pattern = Pattern.quote(original);
      System.out.println("Original is :   " + original);
      System.out.println("Pattern is  : " + pattern);

      System.out.println();
      System.out.println();
      System.out.println();
      String  theString = "rNrl6S5GmQBHqpCTj4y8DUkwxR3AwF60jo7ZgBUHlU62Yf7F3nLo6Qtzyw0RDbEMox3Qj4YxskAzOKHFr52fPkFnkS2asFOcjc6Co1Ig4s5GxDCMaXmSxB9rqRm0Dxgv";
      for (int i=0; i<20; i++)
         {
         System.out.println(theString);
         theString = asciiHash(theString);
         }


      System.out.println();
      System.out.println();
      System.out.println();
      String  xxhamxx = "XXham sandwichxx";
      String  ham     = trim(xxhamxx, "XX");
      System.out.println("          trim(\"XXham sandwichxx\", \"XX\")=|" + ham + "|");

      ham = trimIgnoreCase(xxhamxx, "XX");
      System.out.println("trimIgnoreCase(\"XXham sandwichxx\", \"XX\")=|" + ham + "|");


      System.out.println();
      System.out.println();
      System.out.println();
      }



   }  // class UString



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Notes  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */