ptolemy.util
Class StringUtilities

java.lang.Object
  |
  +--ptolemy.util.StringUtilities

public class StringUtilities
extends java.lang.Object

A collection of utilities for manipulating strings. These utilities do not depend on any other ptolemy.* packages.

Since:
Ptolemy II 2.1
Version:
$Id: StringUtilities.html,v 1.1 2004/02/17 15:37:01 mnwaltz Exp $
Author:
Christopher Hylands

Field Summary
static int ELLIPSIS_LENGTH_LONG
          Maximum length in characters of a long string before #ellipse(String, int) truncates and add a trailing . . .
static int ELLIPSIS_LENGTH_SHORT
          Maximum length in characters of a short string before #ellipse(String, int) truncates and add a trailing . . .
static java.lang.String PREFERENCES_DIRECTORY
          Location of Application preferences such as the user library.
 
Method Summary
static java.lang.String abbreviate(java.lang.String longName)
          Abbreviate a string.
static java.lang.String ellipsis(java.lang.String string, int length)
          Return a string with a maximum line length of length characters, limited to the given number of characters.
static java.lang.String escapeForXML(java.lang.String string)
          Given a string, replace all the instances of XML special characters with their corresponding XML entities.
static java.lang.String getIndentPrefix(int level)
          Return a number of spaces that is proportional to the argument.
static java.lang.String getProperty(java.lang.String propertyName)
          Get the specified property from the environment.
static java.lang.String preferencesDirectory()
          Return the preferences directory, creating it if necessary.
static java.lang.String sanitizeName(java.lang.String name)
          Sanitize a String so that it can be used as a Java identifier.
static java.lang.String split(java.lang.String longName)
          If the string is longer than 79 characters, split it up by displaying adding newlines in all newline delimited substrings that are longer than 79 characters.
static java.lang.String substitute(java.lang.String string, java.lang.String pattern, java.lang.String replacement)
          Replace all occurrences of pattern in the specified string with replacement.
static java.lang.String[] tokenizeForExec(java.lang.String inputString)
          Tokenize a String to an array of Strings for use with Runtime.exec(String []).
static java.lang.String usageString(java.lang.String commandTemplate, java.lang.String[][] commandOptions, java.lang.String[] commandFlags)
          Return a string that contains a description of how to use this class.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ELLIPSIS_LENGTH_LONG

public static final int ELLIPSIS_LENGTH_LONG
Maximum length in characters of a long string before #ellipse(String, int) truncates and add a trailing . . .

See Also:
Constant Field Values

ELLIPSIS_LENGTH_SHORT

public static final int ELLIPSIS_LENGTH_SHORT
Maximum length in characters of a short string before #ellipse(String, int) truncates and add a trailing . . .

See Also:
Constant Field Values

PREFERENCES_DIRECTORY

public static java.lang.String PREFERENCES_DIRECTORY
Location of Application preferences such as the user library.

See Also:
preferencesDirectory()
Method Detail

abbreviate

public static java.lang.String abbreviate(java.lang.String longName)
Abbreviate a string. If the string is longer than 80 characters, truncate it by displaying the first 37 chars, then ". . .", then the last 38 characters. If the longName argument is null, then the string "" is returned.

Returns:
The name.
See Also:
split(String longName)

ellipsis

public static java.lang.String ellipsis(java.lang.String string,
                                        int length)
Return a string with a maximum line length of length characters, limited to the given number of characters. If there are more than 10 newlines, then the string is truncated after 10 lines. If the string is truncated, an ellipsis will be appended to the end of the string.

Parameters:
string - The string to truncate.
length - The length to which to truncate the string.

escapeForXML

public static java.lang.String escapeForXML(java.lang.String string)
Given a string, replace all the instances of XML special characters with their corresponding XML entities. This is necessary to allow arbitrary strings to be encoded within XML. This method
  & becomes &
  " becomes "
  < becomes &lt;
  > becomes &gt;
  newline becomes &#10;
  

Parameters:
string - The string to escape.
Returns:
A new string with special characters replaced.

getIndentPrefix

public static java.lang.String getIndentPrefix(int level)
Return a number of spaces that is proportional to the argument. If the argument is negative or zero, return an empty string.

Parameters:
level - The level of indenting represented by the spaces.
Returns:
A string with zero or more spaces.

preferencesDirectory

public static java.lang.String preferencesDirectory()
                                             throws java.io.IOException
Return the preferences directory, creating it if necessary.

Returns:
A string naming the preferences directory. The last character of the string will have the file.separator character appended.
Throws:
java.io.IOException - If the directory could not be created.
See Also:
PREFERENCES_DIRECTORY

getProperty

public static java.lang.String getProperty(java.lang.String propertyName)
Get the specified property from the environment. An empty string is returned if the argument environment variable does not exist, though if certain properties are not defined, then we make various attempts to determine them and then set them. See the javadoc page for java.util.System.getProperties() for a list of system properties.

The following properties are handled specially

"ptolemy.ptII.dir"
vergil usually sets the ptolemy.ptII.dir property to the value of $PTII. However, if we are running under Web Start, then this property might not be set, in which case we look for "ptolemy/kernel/util/NamedObj.class" and set the property accordingly.
"ptolemy.ptII.dirAsURL"
Return $PTII as a URL. For example, if $PTII was c:\ptII, then return file:/c:/ptII/.
"user.dir"
Return the canonical path name to the current working directory. This is necessary because under JDK1.4.1 System.getProperty() returns c:/foo whereas most of the other methods that operate on path names return C:/foo.

Parameters:
propertyName - The name of property.
Returns:
A String containing the string value of the property.

sanitizeName

public static java.lang.String sanitizeName(java.lang.String name)
Sanitize a String so that it can be used as a Java identifier. Section 3.8 of the Java language spec says:
"An identifier is an unlimited-length sequence of Java letters and Java digits, the first of which must be a Java letter. An identifier cannot have the same spelling (Unicode character sequence) as a keyword (3.9), boolean literal (3.10.3), or the null literal (3.10.7). "
Java characters are A-Z, a-z, $ and _.

Characters that are not permitted in a Java identifier are changed to an underscores. This method does not check that the returned string is a keyword or literal. Note that two different strings can sanitize to the same string. This method is commonly used during code generation to map the name of a ptolemy object to a valid identifier name.

Parameters:
name - A string with spaces and other characters that cannot be in a Java name.
Returns:
A String that follows the Java identifier rules.

split

public static java.lang.String split(java.lang.String longName)
If the string is longer than 79 characters, split it up by displaying adding newlines in all newline delimited substrings that are longer than 79 characters. If the longName argument is null, then the string "" is returned.

Parameters:
longName - The string to optionally split up
Returns:
Either the original string, or the string with newlines inserted
See Also:
abbreviate(String longName)

substitute

public static java.lang.String substitute(java.lang.String string,
                                          java.lang.String pattern,
                                          java.lang.String replacement)
Replace all occurrences of pattern in the specified string with replacement. Note that the pattern is NOT a regular expression, and that relative to the String.replaceAll() method in jdk1.4, this method is extremely slow.

Parameters:
string - The string to edit.
replacement - The string to replace it with.
Returns:
A new string with the specified replacements.

tokenizeForExec

public static java.lang.String[] tokenizeForExec(java.lang.String inputString)
                                          throws java.io.IOException
Tokenize a String to an array of Strings for use with Runtime.exec(String []).

Lines that begin with an octothorpe '#' are ignored. Substrings that start and end with a double quote are considered to be a single token and are returned as a single array element.

Parameters:
inputString - The String to tokenize
Returns:
An array of substrings.
Throws:
java.io.IOException - Thrown if StreamTokenizer.nextToken() throws it.

usageString

public static java.lang.String usageString(java.lang.String commandTemplate,
                                           java.lang.String[][] commandOptions,
                                           java.lang.String[] commandFlags)
Return a string that contains a description of how to use this class.

Parameters:
commandOptions - A 2xN array of Strings that list command-line options that take arguments where the first element is a String naming the command line option, and the second element is the argument, for example {"-class", "")
commandFlags - An array of Strings that list command-line options that are either present or not.