jimm.util
Class StringUtils

java.lang.Object
  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