jimm.util
Class StringUtils

java.lang.Object
  extended by jimm.util.StringUtils

public class StringUtils
extends java.lang.Object

Globally available utility classes, mostly for string manipulation.

Author:
Jim Menard, jimm@io.com

Field Summary
protected static int DEFAULT_MAX_MESSAGE_WIDTH
           
 
Constructor Summary
StringUtils()
           
 
Method Summary
static java.lang.String escapeHTML(java.lang.String str)
          Returns a string with HTML special characters replaced by their entity equivalents.
static java.lang.String escapeXML(java.lang.String str)
          Returns a string with XML special characters replaced by their entity equivalents.
static int findBreakAfter(java.lang.String line, int start)
          Returns the index of the first whitespace character or '-' in line that is at or after start.
static int findBreakBefore(java.lang.String line, int start)
          Returns the index of the first whitespace character or '-' in line that is at or before start.
static java.lang.String join(java.util.Collection c, java.lang.String joinWith)
          Returns a string consisting of all members of a collection separated by the specified string.
static java.lang.String newlinesToXHTMLBreaks(java.lang.String str)
          Returns a new string where all newlines ("\n", "\r", or "\r\n") have been replaced by "\n" plus XHTML break tags ("\n<br />").
static java.lang.String nullOrTrimmed(java.lang.String str)
          Returns str with leading and trailing spaces trimmed or, if str is null, returns null.
static java.lang.String replaceDelimited(java.lang.String start, java.lang.String end, Replacer r, java.lang.String s)
          Returns a new string with all strings delimited by start and end replaced by whatever is generated by the Replacer r.
static java.lang.String replaceDelimited(java.lang.String exceptAfter, java.lang.String start, java.lang.String end, Replacer r, java.lang.String s)
          Returns a new string with all strings delimited by start and end (but not immediately preceeded by exceptAfter) replaced by whatever is generated by the Replacer r.
static java.util.List split(java.lang.String str, java.lang.String delim)
          Returns a list of substrings created by splitting the given string at the given delimiter.
static java.util.List splitIntoLines(java.lang.String str)
          Returns an array of strings, one for each line in the string.
static void splitUp(java.lang.StringBuffer buf, java.lang.String str)
          Appends a string to a string buffer, adding extra newlines so the message is not too wide.
static void splitUp(java.lang.StringBuffer buf, java.lang.String str, int maxWidth)
          Appends a string to a string buffer, adding extra newlines so the message is not too wide.
static java.lang.String unescapeXML(java.lang.String str)
          Returns a string with XML entities replaced by their normal characters.
static java.util.List wrap(java.lang.String str, java.awt.FontMetrics fm, int maxWidth)
          Returns an array of strings, one for each line in the string after it has been wrapped to fit lines of maxWidth.
static void wrapLineInto(java.lang.String line, java.util.List list, java.awt.FontMetrics fm, int maxWidth)
          Given a line of text and font metrics information, wrap the line and add the new line(s) to list.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_MAX_MESSAGE_WIDTH

protected static final int DEFAULT_MAX_MESSAGE_WIDTH
See Also:
Constant Field Values
Constructor Detail

StringUtils

public StringUtils()
Method Detail

split

public static java.util.List split(java.lang.String str,
                                   java.lang.String delim)
Returns a list of substrings created by splitting the given string at the given delimiter. The return value will be null if the string is null, else it will be a non-empty list of strings. If delim is null or is not found in the string, the list will contain one element: the original string.

This isn't the same thing as using a tokenizer. delim is a literal string, not a set of characters any of which may be a delimiter.

Parameters:
str - the string we're splitting
delim - the delimter string

join

public static java.lang.String join(java.util.Collection c,
                                    java.lang.String joinWith)
Returns a string consisting of all members of a collection separated by the specified string. The toString method of each collection member is called to convert it to a string.

Parameters:
c - a collection of objects
joinWith - the string that will separate each member of the collection

splitIntoLines

public static java.util.List splitIntoLines(java.lang.String str)
Returns an array of strings, one for each line in the string. Lines end with any of cr, lf, or cr lf. A line ending at the end of the string will not output a further, empty string.

This code assumes str is not null.

Parameters:
str - the string to split
Returns:
a non-empty list of strings

splitUp

public static void splitUp(java.lang.StringBuffer buf,
                           java.lang.String str)
Appends a string to a string buffer, adding extra newlines so the message is not too wide. Max width is not guaranteed; if there is no space in a line before DEFAULT_MAX_MESSAGE_WIDTH then the next one after it will be used insetead. Each line will be trimmed before and after it's added, so some whitespace may be goofed up. This is used for error message wrapping, so it's not critical that whitespace be preserved.

TODO Looks for space, not all whitespace. This should probably change.

Parameters:
buf - the string buffer
str - the string

splitUp

public static void splitUp(java.lang.StringBuffer buf,
                           java.lang.String str,
                           int maxWidth)
Appends a string to a string buffer, adding extra newlines so the message is not too wide. Max width is not guaranteed; if there is no space in a line before maxWidth then the next one after it will be used instead. Each line will be trimmed before and after it's added, so some whitespace may be goofed up. This is used for error message wrapping, so it's not critical that whitespace be preserved.

TODO Looks for space, not all whitespace. This should probably change.

Parameters:
buf - the string buffer
str - the string
maxWidth - maximum number of chars in each line

wrap

public static java.util.List wrap(java.lang.String str,
                                  java.awt.FontMetrics fm,
                                  int maxWidth)
Returns an array of strings, one for each line in the string after it has been wrapped to fit lines of maxWidth. Lines end with any of cr, lf, or cr lf. A line ending at the end of the string will not output a further, empty string.

This code assumes str is not null.

Parameters:
str - the string to split
fm - needed for string width calculations
maxWidth - the max line width, in points
Returns:
a non-empty list of strings

wrapLineInto

public static void wrapLineInto(java.lang.String line,
                                java.util.List list,
                                java.awt.FontMetrics fm,
                                int maxWidth)
Given a line of text and font metrics information, wrap the line and add the new line(s) to list.

Parameters:
line - a line of text
list - an output list of strings
fm - font metrics
maxWidth - maximum width of the line(s)

findBreakBefore

public static int findBreakBefore(java.lang.String line,
                                  int start)
Returns the index of the first whitespace character or '-' in line that is at or before start. Returns -1 if no such character is found.

Parameters:
line - a string
start - where to star looking

findBreakAfter

public static int findBreakAfter(java.lang.String line,
                                 int start)
Returns the index of the first whitespace character or '-' in line that is at or after start. Returns -1 if no such character is found.

Parameters:
line - a string
start - where to star looking

escapeHTML

public static java.lang.String escapeHTML(java.lang.String str)
Returns a string with HTML special characters replaced by their entity equivalents.

Parameters:
str - the string to escape
Returns:
a new string without HTML special characters

newlinesToXHTMLBreaks

public static java.lang.String newlinesToXHTMLBreaks(java.lang.String str)
Returns a new string where all newlines ("\n", "\r", or "\r\n") have been replaced by "\n" plus XHTML break tags ("\n<br />").

We don't call splitIntoLines because that method does not tell us if the string ended with a newline or not.

Parameters:
str - any string
Returns:
a new string with all newlines replaced by "\n<br />"

escapeXML

public static java.lang.String escapeXML(java.lang.String str)
Returns a string with XML special characters replaced by their entity equivalents.

Parameters:
str - the string to escape
Returns:
a new string without XML special characters

unescapeXML

public static java.lang.String unescapeXML(java.lang.String str)
Returns a string with XML entities replaced by their normal characters.

Parameters:
str - the string to un-escape
Returns:
a new normal string

replaceDelimited

public static java.lang.String replaceDelimited(java.lang.String start,
                                                java.lang.String end,
                                                Replacer r,
                                                java.lang.String s)
Returns a new string with all strings delimited by start and end replaced by whatever is generated by the Replacer r. The delimiters themselves are not part of the returned string.

If the Replacer ever returns null, we return null.

Parameters:
start - the delimiter start (for example, "{@")
end - the delimiter end (for example, "}")
r - the replacer; takes the text between start and end and returns the replacement text
s - the string we're munging
Returns:
a new string munged by the replacer, or null if the replacer ever returns null

replaceDelimited

public static java.lang.String replaceDelimited(java.lang.String exceptAfter,
                                                java.lang.String start,
                                                java.lang.String end,
                                                Replacer r,
                                                java.lang.String s)
Returns a new string with all strings delimited by start and end (but not immediately preceeded by exceptAfter) replaced by whatever is generated by the Replacer r. The delimiters themselves are not part of the returned string.

If the Replacer ever returns null, we return null.

Parameters:
exceptAfter - ignore start if it appears immediately after this string; may be null
start - the delimiter start (for example, "{@")
end - the delimiter end (for example, "}")
r - the replacer; takes the text between start and end and returns the replacement text
s - the string we're munging
Returns:
a new string munged by the replacer, or null if the replacer ever returns null

nullOrTrimmed

public static java.lang.String nullOrTrimmed(java.lang.String str)
Returns str with leading and trailing spaces trimmed or, if str is null, returns null.

Returns:
str trimmed or null