freemarker.template.utility

Class StringUtil

java.lang.Object

freemarker.template.utility.StringUtil

public class StringUtil
extends java.lang.Object

Some text related utilities.

Constructor Summary

Constructors

Constructor and Description
StringUtil()

Method Summary

Methods

Modifier and Type	Method and Description
static java.lang.String	capitalize(java.lang.String s)
static java.lang.String	chomp(java.lang.String s) Removes the line-break from the end of the string.
static java.util.Locale	deduceLocale(java.lang.String input)
static java.lang.String	emptyToNull(java.lang.String s) Converts a 0-length string to null, leaves the string as is otherwise.
static java.lang.String	FTLStringLiteralDec(java.lang.String s) FTL string literal decoding. \\, \", \', \n, \t, \r, \b and \f will be replaced according to Java rules.
static java.lang.String	FTLStringLiteralEnc(java.lang.String s)
static boolean	getYesNo(java.lang.String s)
static java.lang.String	HTMLEnc(java.lang.String s) Deprecated. Use XHTMLEnc(String) instead, because it escapes apostrophe-quote too.
static boolean	isXMLID(java.lang.String name)
static java.lang.String	javaScriptStringEnc(java.lang.String s) Escapes a String to be safely insertable into a JavaScript string literal; for more see jsStringEnc(s, false).
static java.lang.String	javaStringEnc(java.lang.String s) Escapes the String with the escaping rules of Java language string literals, so it's safe to insert the value into a string literal.
static java.lang.String	jQuote(java.lang.Object obj) Converts the parameter with toString (if not null)and passes it to jQuote(String).
static java.lang.String	jQuote(java.lang.String s) Quotes string as Java Language string literal.
static java.lang.String	jQuoteNoXSS(java.lang.Object obj) Converts the parameter with toString (if not null)and passes it to jQuoteNoXSS(String).
static java.lang.String	jQuoteNoXSS(java.lang.String s) Same as jQuoteNoXSS(String) but also escapes '<' as <.
static java.lang.String	jsonStringEnc(java.lang.String s) Escapes a String to be safely insertable into a JSON string literal; for more see jsStringEnc(s, true).
static java.lang.String	jsStringEnc(java.lang.String s, boolean json) Escapes a String to be safely insertable into a JavaScript or a JSON string literal.
static java.lang.String	leftPad(java.lang.String s, int minLength) Pads the string at the left with spaces until it reaches the desired length.
static java.lang.String	leftPad(java.lang.String s, int minLength, char filling) Pads the string at the left with the specified character until it reaches the desired length.
static java.lang.String	leftPad(java.lang.String s, int minLength, java.lang.String filling) Pads the string at the left with a filling pattern until it reaches the desired length.
static boolean	matchesName(java.lang.String qname, java.lang.String nodeName, java.lang.String nsURI, Environment env)
static java.util.Map	parseNameValuePairList(java.lang.String s, java.lang.String defaultValue) Parses a name-value pair list, where the pairs are separated with comma, and the name and value is separated with colon.
static java.lang.String	replace(java.lang.String text, java.lang.String oldSub, java.lang.String newSub) Same as replace(String, String, String, boolean, boolean) with two false parameters.
static java.lang.String	replace(java.lang.String text, java.lang.String oldsub, java.lang.String newsub, boolean caseInsensitive, boolean firstOnly) Replaces all occurrences of a sub-string in a string.
static java.lang.String	rightPad(java.lang.String s, int minLength) Pads the string at the right with spaces until it reaches the desired length.
static java.lang.String	rightPad(java.lang.String s, int minLength, char filling) Pads the string at the right with the specified character until it reaches the desired length.
static java.lang.String	rightPad(java.lang.String s, int minLength, java.lang.String filling) Pads the string at the right with a filling pattern until it reaches the desired length.
static java.lang.String	RTFEnc(java.lang.String s) Rich Text Format encoding (does not replace line breaks).
static java.lang.String[]	split(java.lang.String s, char c) Splits a string at the specified character.
static java.lang.String[]	split(java.lang.String s, java.lang.String sep, boolean caseInsensitive) Splits a string at the specified string.
static java.lang.String	tryToString(java.lang.Object object) Tries to run toString(), but if that fails, returns a "[toString failed: " + e + "]" instead.
static java.lang.String	URLEnc(java.lang.String s, java.lang.String charset) URL encoding (like%20this).
static int	versionStringToInt(java.lang.String version) Converts a version number string to an integer for easy comparison.
static java.lang.String	XHTMLEnc(java.lang.String s) XHTML Encoding.
static java.lang.String	XMLEnc(java.lang.String s) XML Encoding.
static java.lang.String	XMLEncNA(java.lang.String s) XML encoding without replacing apostrophes.
static java.lang.String	XMLEncNQG(java.lang.String s) XML encoding without replacing apostrophes and quotation marks and greater-thans (except in ]]>).
static java.lang.String	XMLEncQAttr(java.lang.String s) XML encoding for attributes valies quoted with " (not with '!).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StringUtil

public StringUtil()

Method Detail

HTMLEnc

public static java.lang.String HTMLEnc(java.lang.String s)

Deprecated. Use XHTMLEnc(String) instead, because it escapes apostrophe-quote too.

HTML encoding (does not convert line breaks and apostrophe-quote). Replaces all '>' '<' '&' and '"' with entity reference, but not "'" (apostrophe-quote). The last is not escaped as back then when this was written some user agents didn't understood "&apos;" nor "&#39;".

XMLEnc

public static java.lang.String XMLEnc(java.lang.String s)

XML Encoding. Replaces all '>' '<' '&', "'" and '"' with entity reference

XHTMLEnc

public static java.lang.String XHTMLEnc(java.lang.String s)

XHTML Encoding. Replaces all '>' '<' '&', "'" and '"' with entity reference suitable for XHTML decoding in common user agents (including legacy user agents, which do not decode "&apos;" to "'", so "&#39;" is used instead [see http://www.w3.org/TR/xhtml1/#C_16])

XMLEncNA

public static java.lang.String XMLEncNA(java.lang.String s)

XML encoding without replacing apostrophes.

See Also:

XMLEnc(String)

XMLEncQAttr

public static java.lang.String XMLEncQAttr(java.lang.String s)

XML encoding for attributes valies quoted with " (not with '!). Also can be used for HTML attributes that are quoted with ".

See Also:

XMLEnc(String)

XMLEncNQG

public static java.lang.String XMLEncNQG(java.lang.String s)

XML encoding without replacing apostrophes and quotation marks and greater-thans (except in ]]>).

See Also:

XMLEnc(String)

RTFEnc

public static java.lang.String RTFEnc(java.lang.String s)

Rich Text Format encoding (does not replace line breaks). Escapes all '\' '{' '}' and '"'

URLEnc

public static java.lang.String URLEnc(java.lang.String s,
                      java.lang.String charset)
                               throws java.io.UnsupportedEncodingException

URL encoding (like%20this).

Throws:

java.io.UnsupportedEncodingException

FTLStringLiteralEnc

public static java.lang.String FTLStringLiteralEnc(java.lang.String s)

FTLStringLiteralDec

public static java.lang.String FTLStringLiteralDec(java.lang.String s)
                                            throws ParseException

FTL string literal decoding. \\, \", \', \n, \t, \r, \b and \f will be replaced according to Java rules. In additional, it knows \g, \l, \a and \{ which are replaced with <, >, & and { respectively. \x works as hexadecimal character code escape. The character codes are interpreted according to UCS basic plane (Unicode). "f\x006Fo", "f\x06Fo" and "f\x6Fo" will be "foo". "f\x006F123" will be "foo123" as the maximum number of digits is 4. All other \X (where X is any character not mentioned above or End-of-string) will cause a ParseException.

Parameters:

s - String literal without the surrounding quotation marks

Returns:

String with all escape sequences resolved

Throws:

ParseException - if there string contains illegal escapes

deduceLocale

public static java.util.Locale deduceLocale(java.lang.String input)

capitalize

public static java.lang.String capitalize(java.lang.String s)

getYesNo

public static boolean getYesNo(java.lang.String s)

split

public static java.lang.String[] split(java.lang.String s,
                       char c)

Splits a string at the specified character.

split

public static java.lang.String[] split(java.lang.String s,
                       java.lang.String sep,
                       boolean caseInsensitive)

Splits a string at the specified string.

replace

public static java.lang.String replace(java.lang.String text,
                       java.lang.String oldSub,
                       java.lang.String newSub)

Same as replace(String, String, String, boolean, boolean) with two false parameters.

Since:

2.3.20

replace

public static java.lang.String replace(java.lang.String text,
                       java.lang.String oldsub,
                       java.lang.String newsub,
                       boolean caseInsensitive,
                       boolean firstOnly)

Replaces all occurrences of a sub-string in a string.

Parameters:

text - The string where it will replace oldsub with newsub.

Returns:

String The string after the replacements.

chomp

public static java.lang.String chomp(java.lang.String s)

Removes the line-break from the end of the string.

emptyToNull

public static java.lang.String emptyToNull(java.lang.String s)

Converts a 0-length string to null, leaves the string as is otherwise.

Parameters:

s - maybe null.

jQuote

public static java.lang.String jQuote(java.lang.Object obj)

Converts the parameter with toString (if not null)and passes it to jQuote(String).

jQuote

public static java.lang.String jQuote(java.lang.String s)

Quotes string as Java Language string literal. Returns string "null" if s is null.

jQuoteNoXSS

public static java.lang.String jQuoteNoXSS(java.lang.Object obj)

Converts the parameter with toString (if not null)and passes it to jQuoteNoXSS(String).

jQuoteNoXSS

public static java.lang.String jQuoteNoXSS(java.lang.String s)

Same as jQuoteNoXSS(String) but also escapes '<' as <. This is used for log messages to prevent XSS on poorly written Web-based log viewers.

javaStringEnc

public static java.lang.String javaStringEnc(java.lang.String s)

Escapes the String with the escaping rules of Java language string literals, so it's safe to insert the value into a string literal. The resulting string will not be quoted.

All characters under UCS code point 0x20 will be escaped. Where they have no dedicated escape sequence in Java, they will be replaced with hexadecimal escape (\uXXXX).

See Also:

jQuote(String)

javaScriptStringEnc

public static java.lang.String javaScriptStringEnc(java.lang.String s)

Escapes a String to be safely insertable into a JavaScript string literal; for more see jsStringEnc(s, false).

jsonStringEnc

public static java.lang.String jsonStringEnc(java.lang.String s)

Escapes a String to be safely insertable into a JSON string literal; for more see jsStringEnc(s, true).

jsStringEnc

public static java.lang.String jsStringEnc(java.lang.String s,
                           boolean json)

Escapes a String to be safely insertable into a JavaScript or a JSON string literal. The resulting string will not be quoted; the caller must ensure that they are there in the final output. Note that for JSON, the quotation marks must be ", not ', because JSON doesn't escape '.

The escaping rules guarantee that if the inside of the literal is from one or more touching sections of strings escaped with this, no character sequence will occur that closes the string literal or has special meaning in HTML/XML that can terminate the script section. (If, however, the escaped section is preceded by or followed by strings from other sources, this can't be guaranteed in some rare cases. Like x = "</${a?js_string}" might closes the "script" element if a is is "script>".) The escaped characters are:

Input	Output
"	\"
' if not in JSON-mode	\'
\	\\
/ if the method can't know that it won't be directly after <	\/
> if the method can't know that it won't be directly after ]] or --	JavaScript: \>; JSON: \u003E
< if the method can't know that it won't be directly followed by ! or ?	\u003C
u0000-u001f (UNICODE control characters - disallowed by JSON) u007f-u009f (UNICODE control characters - disallowed by JSON)	\n, \r and such, or if there's no such dedicated escape: JavaScript: \xXX, JSON: \uXXXX
u2028 (Line separator - source code line-break in ECMAScript) u2029 (Paragraph separator - source code line-break in ECMAScript)	\uXXXX

Since:

2.3.20

parseNameValuePairList

public static java.util.Map parseNameValuePairList(java.lang.String s,
                                   java.lang.String defaultValue)
                                            throws java.text.ParseException

Parses a name-value pair list, where the pairs are separated with comma, and the name and value is separated with colon. The keys and values can contain only letters, digits and _. They can't be quoted. White-space around the keys and values are ignored. The value can be omitted if defaultValue is not null. When a value is omitted, then the colon after the key must be omitted as well. The same key can't be used for multiple times.

Parameters:

s - the string to parse. For example: "strong:100, soft:900".

defaultValue - the value used when the value is omitted in a key-value pair.

Returns:

the map that contains the name-value pairs.

Throws:

java.text.ParseException - if the string is not a valid name-value pair list.

isXMLID

public static boolean isXMLID(java.lang.String name)

Returns:

whether the name is a valid XML tagname. (This routine might only be 99% accurate. Should maybe REVISIT)

matchesName

public static boolean matchesName(java.lang.String qname,
                  java.lang.String nodeName,
                  java.lang.String nsURI,
                  Environment env)

Returns:

whether the qname matches the combination of nodeName, nsURI, and environment prefix settings.

leftPad

public static java.lang.String leftPad(java.lang.String s,
                       int minLength)

Pads the string at the left with spaces until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.

Parameters:

s - the string that will be padded.

minLength - the length to reach.

leftPad

public static java.lang.String leftPad(java.lang.String s,
                       int minLength,
                       char filling)

Pads the string at the left with the specified character until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.

Parameters:

s - the string that will be padded.

minLength - the length to reach.

filling - the filling pattern.

leftPad

public static java.lang.String leftPad(java.lang.String s,
                       int minLength,
                       java.lang.String filling)

Pads the string at the left with a filling pattern until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string. For example: leftPad('ABC', 9, '1234') returns "123412ABC".

Parameters:

s - the string that will be padded.

minLength - the length to reach.

filling - the filling pattern. Must be at least 1 characters long. Can't be null.

rightPad

public static java.lang.String rightPad(java.lang.String s,
                        int minLength)

Pads the string at the right with spaces until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.

Parameters:

s - the string that will be padded.

minLength - the length to reach.

rightPad

public static java.lang.String rightPad(java.lang.String s,
                        int minLength,
                        char filling)

Pads the string at the right with the specified character until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.

Parameters:

s - the string that will be padded.

minLength - the length to reach.

filling - the filling pattern.

rightPad

public static java.lang.String rightPad(java.lang.String s,
                        int minLength,
                        java.lang.String filling)

Pads the string at the right with a filling pattern until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string. For example: rightPad('ABC', 9, '1234') returns "ABC412341". Note that the filling pattern is started as if you overlay "123412341" with the left-aligned "ABC", so it starts with "4".

Parameters:

s - the string that will be padded.

minLength - the length to reach.

filling - the filling pattern. Must be at least 1 characters long. Can't be null.

versionStringToInt

public static int versionStringToInt(java.lang.String version)

Converts a version number string to an integer for easy comparison. The version number must start with numbers separated with dots. There can be any number of such dot-separated numbers, but only the first three will be considered. After the numbers arbitrary text can follow, and will be ignored. The string will be trimmed before interpretation.

Returns:

major * 1000000 + minor * 1000 + micro

tryToString

public static java.lang.String tryToString(java.lang.Object object)

Tries to run toString(), but if that fails, returns a "[toString failed: " + e + "]" instead. Also, it return null for null parameter.

Since:

2.3.20