/home/wpollock1/public_html/AJava/TextKit/TextKit.java

/* TextKit.java - a utility class for text methods.  This class is part
 * of the package "utils".  Currently it contains a method called
 * "lineOfStars" which returns a line of asterisks as a String,
 * and a method "pad" which formats number by adding leading space.
 * ("pad" is no longer useful, since Java5 Formatter class and
 * String.printf methods!)
 *
 * It may contain additional methods someday.  Also, a "main" method
 * has been added to test this class.  As it is part of a package,
 * you must run it from the parent directory:  java utils/TextKit
 * (Note the forward slash, even on a Windows computer!)
 *
 * To generate the Javadocs, create utils\doc directory, then run
 * the following command (using a single line!):
 * javadoc -d utils\docs -author -version -noqualifier java.* -link
 *    http://java.sun.com/j2se/1.5/docs/api utils\TextKit.java
 *
 * (C) 2004 Wayne Pollock, Tampa FL USA.  All Rights Reserved.
 */

package utils;

/** TextKit is a collection of utility text methods.
 *
 * @author Wayne Pollock, Tampa Florida USA
 * @version 1.0
 */

public class TextKit
{
   /**
    * Creates a line of asterisks of a given length.
    *
    * @param numOfStars  The number of asterisks to be drawn
    * @return A <tt>String</tt> of asterisks
    * @throws IllegalArgumentException if <tt>num</tt> &lt; 0
    */

   public static String lineOfStars ( int numOfStars )
                        throws IllegalArgumentException
   {
      if ( numOfStars < 0 )
         throw new IllegalArgumentException( "Number of stars to draw is "
            + numOfStars + ", and should be greater than zero." );

      StringBuilder stars = new StringBuilder( numOfStars );
      for ( int i = 0; i < numOfStars; ++i )
         stars.append( "*" );
      return stars.toString();
   }


   /**
    * Formats an integer <tt>num</tt> with leading space,
    * so the resulting <tt>String</tt> has at least <tt>minWidth</tt>
    * length.
    *
    * @param num  The number to be formatted with leading spaces
    * @param minWidth  The minimum length of the resulting <tt>String</tt>
    * @return The formatted <tt>num</tt> with leading spaces
    * @throws IllegalArgumentException if <tt>minWidth</tt> &lt; 1
    */

   public static String pad ( int num, int minWidth )
                        throws IllegalArgumentException
   {
      if ( minWidth < 0 )
         throw new IllegalArgumentException( "Minimum width is "
            + minWidth + ", and should be greater than zero." );

      StringBuilder result = new StringBuilder();
      result.append( num );
      while ( result.length() < minWidth )
         result.insert( 0, ' ' );
      return result.toString();
   }

   /** This prevents one from creating objects of this class.
    */
   private TextKit () {}


   /** Main is only used to test the methods.  This is an "ad-hoc"
    *  method of testing.  A production quality class would use
    *  assertions and/or JUnit testing.
    */

   public static void main ( String [] args )
   {
      System.out.println( lineOfStars(5) );
      System.out.println( "Five stars should be showing above" );

      System.out.println( "\n*" + pad(17, 4) + "*" );
      System.out.println( "*  17* (two leading spaces) should be showing above" );
   }
}