Class StringUtil
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classUsed as the argument ofjsStringEnc(String, JsStringEncCompatibility, JsStringEncQuotation).static classUsed as the argument ofjsStringEnc(String, JsStringEncCompatibility, JsStringEncQuotation). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic Stringcapitalize(String s)static StringRemoves a line-break from the end of the string (if there's any).static LocalededuceLocale(String input)static StringemptyToNull(String s)Converts a 0-length string to null, leaves the string as is otherwise.static StringCreates a quoted FTL string literal from a string, using escaping where necessary.static StringFTL string literal decoding.static StringEscapes a string according the FTL string literal escaping rules; it doesn't add the quotation marks.static StringFTLStringLiteralEnc(String s, char quotation)Escapes a string according the FTL string literal escaping rules, assuming the literal is quoted withquotation; it doesn't add the quotation marks itself.static booleanstatic PatternglobToRegularExpression(String glob)static PatternglobToRegularExpression(String glob, boolean caseInsensitive)Creates a regular expression from a glob.static StringDeprecated.static booleanTells if a character can occur in an FTL identifier if it's preceded with a backslash.static booleanisFTLIdentifierPart(char c)Tells if a character can occur in an FTL identifier expression (without escaping) as other than the first character.static booleanisFTLIdentifierStart(char c)Tells if a character can occur on the beginning of an FTL identifier expression (without escaping).static booleanisTrimmableToEmpty(char[] text)Tells ifString.trim()will return a 0-length string for theStringequivalent of the argument.static booleanisTrimmableToEmpty(char[] text, int start)LikeisTrimmableToEmpty(char[]), but acts on a sub-array that starts atstart(inclusive index).static booleanisTrimmableToEmpty(char[] text, int start, int end)LikeisTrimmableToEmpty(char[]), but acts on a sub-array that starts atstart(inclusive index) and ends atend(exclusive index).static booleanisWhitespaceOrNonBreakingWhitespace(char c)LikeCharacter.isWhitespace(char), but also considers non-breaking whitespace characters as whitespace.static booleanDeprecated.Don't use this outside FreeMarker; it's name if misleading, and it doesn't follow the XML specs.static StringEscapes aStringto be safely insertable into a JavaScript string literal; for more seejsStringEnc(s, JsStringEncCompatibility.JAVA_SCRIPT, null).static StringjavaStringEnc(String s)Escapes theStringwith the escaping rules of Java language string literals, so it's safe to insert the value into a string literal.static StringjavaStringEnc(String s, boolean quote)Escapes theStringwith the escaping rules of Java language string literals, and then ifquoteis true, it also adds quotation marks before and after it.static Stringstatic StringQuotes string as Java Language string literal.static StringjQuoteNoXSS(Object obj)static StringjQuoteNoXSS(String s)static StringjsonStringEnc(String s)Escapes aStringto be safely insertable into a JSON string literal; for more seejsStringEnc(s, JsStringEncCompatibility.JSON, null).static StringjsStringEnc(String s, boolean json)Deprecated.UsejsStringEnc(String, JsStringEncCompatibility)instead.static StringjsStringEnc(String s, StringUtil.JsStringEncCompatibility compatibility)Escapes aStringto be safely insertable into a JSON or JavaScript string literal; for more seejsStringEnc(s, compatibility, null).static StringjsStringEnc(String s, StringUtil.JsStringEncCompatibility compatibility, StringUtil.JsStringEncQuotation quotation)Escapes aStringto be safely insertable into a JavaScript or a JSON string literal, and if the 3rd argument istrue, also adds quotation marks around it.static StringPads the string at the left with spaces until it reaches the desired length.static StringPads the string at the left with the specified character until it reaches the desired length.static StringPads the string at the left with a filling pattern until it reaches the desired length.static booleanmatchesName(String qname, String nodeName, String nsURI, Environment env)static MapparseNameValuePairList(String s, 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 StringSame asreplace(String, String, String, boolean, boolean)with twofalseparameters.static StringReplaces all occurrences of a sub-string in a string.static StringPads the string at the right with spaces until it reaches the desired length.static StringPads the string at the right with the specified character until it reaches the desired length.static StringPads the string at the right with a filling pattern until it reaches the desired length.static StringRich Text Format encoding (does not replace line breaks).static voidLikeRTFEnc(String), but writes the result into aWriter.static String[]Splits a string at the specified character.static String[]Splits a string at the specified string.static StringtoLowerABC(int n)Same astoUpperABC(int), but produces lower case result, like"ab".static StringtoUpperABC(int n)Converts1,2,3and so forth to"A","B","C"and so fort.static char[]trim(char[] cs)Behaves exactly likeString.trim(), but works on arrays.static StringtryToString(Object object)Tries to runtoString(), but if that fails, returns a"[com.example.SomeClass.toString() failed: " + e + "]"instead.static StringURL encoding (like%20this) for query parameter values, path segments, fragments; this encodes all characters that are reserved anywhere.static StringURLPathEnc(String s, String charset)LikeURLEnc(String, String)but doesn't escape the slash character (/).static intversionStringToInt(String version)Converts a version number string to an integer for easy comparison.static StringXHTML Encoding.static voidLikeXHTMLEnc(String), but writes the result into aWriter.static StringXML Encoding.static voidLikeXMLEnc(String), but writes the result into aWriter.static StringXML encoding without replacing apostrophes.static StringXML encoding without replacing apostrophes and quotation marks and greater-thans (except in]]>).static StringXMLEncQAttr(String s)XML encoding for attribute values quoted with"(not with'!).
-
Constructor Details
-
StringUtil
public StringUtil()
-
-
Method Details
-
HTMLEnc
Deprecated.UseXHTMLEnc(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 "'" nor "'". -
XMLEnc
XML Encoding. Replaces all '>' '<' '&', "'" and '"' with entity reference -
XMLEnc
LikeXMLEnc(String), but writes the result into aWriter.- Throws:
IOException- Since:
- 2.3.24
-
XHTMLEnc
XHTML Encoding. Replaces all '>' '<' '&', "'" and '"' with entity reference suitable for XHTML decoding in common user agents (including legacy user agents, which do not decode "'" to "'", so "'" is used instead [see http://www.w3.org/TR/xhtml1/#C_16]) -
XHTMLEnc
LikeXHTMLEnc(String), but writes the result into aWriter.- Throws:
IOException- Since:
- 2.3.24
-
XMLEncNA
XML encoding without replacing apostrophes.- See Also:
XMLEnc(String)
-
XMLEncQAttr
XML encoding for attribute values quoted with"(not with'!). Also can be used for HTML attributes that are quoted with".- See Also:
XMLEnc(String)
-
XMLEncNQG
XML encoding without replacing apostrophes and quotation marks and greater-thans (except in]]>).- See Also:
XMLEnc(String)
-
RTFEnc
Rich Text Format encoding (does not replace line breaks). Escapes all '\' '{' '}'. -
RTFEnc
LikeRTFEnc(String), but writes the result into aWriter.- Throws:
IOException- Since:
- 2.3.24
-
URLEnc
URL encoding (like%20this) for query parameter values, path segments, fragments; this encodes all characters that are reserved anywhere.- Throws:
UnsupportedEncodingException
-
URLPathEnc
LikeURLEnc(String, String)but doesn't escape the slash character (/). This can be used to encode a path only if you know that no folder or file name will contain/character (not in the path, but in the name itself), which usually stands, as the commonly used OS-es don't allow that.- Throws:
UnsupportedEncodingException- Since:
- 2.3.21
-
FTLStringLiteralEnc
Escapes a string according the FTL string literal escaping rules, assuming the literal is quoted withquotation; it doesn't add the quotation marks itself.- Parameters:
quotation- Either'"'or'\''. It's assumed that the string literal whose part we calculate is enclosed within this kind of quotation mark. Thus, the other kind of quotation character will not be escaped in the result.- Since:
- 2.3.22
-
FTLStringLiteralEnc
Escapes a string according the FTL string literal escaping rules; it doesn't add the quotation marks. As this method doesn't know if the string literal is quoted with reuglar quotation marks or apostrophe quute, it will escape both.- See Also:
FTLStringLiteralEnc(String, char)
-
FTLStringLiteralDec
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
-
capitalize
-
getYesNo
-
split
Splits a string at the specified character. -
split
Splits a string at the specified string.- Parameters:
sep- The string that separates the items of the resulting array. Since 2.3.28, if this is 0 length, then each character will be a separate item in the array.
-
replace
Same asreplace(String, String, String, boolean, boolean)with twofalseparameters.- Since:
- 2.3.20
-
replace
public static String replace(String text, String oldsub, String newsub, boolean caseInsensitive, boolean firstOnly)Replaces all occurrences of a sub-string in a string.- Parameters:
text- The string where it will replaceoldsubwithnewsub.- Returns:
- String The string after the replacements.
-
chomp
Removes a line-break from the end of the string (if there's any). -
emptyToNull
Converts a 0-length string to null, leaves the string as is otherwise.- Parameters:
s- maybenull.
-
jQuote
-
jQuote
Quotes string as Java Language string literal. Returns string"null"ifsisnull. -
jQuoteNoXSS
-
jQuoteNoXSS
Same asjQuoteNoXSS(String)but also escapes'<'as\u003C. This is used for log messages to prevent XSS on poorly written Web-based log viewers. -
ftlQuote
Creates a quoted FTL string literal from a string, using escaping where necessary. The result either uses regular quotation marks (UCS 0x22) or apostrophe-quotes (UCS 0x27), depending on the string content. (Currently, apostrophe-quotes will be chosen exactly when the string contains regular quotation character and doesn't contain apostrophe-quote character.)- Parameters:
s- The value that should be converted to an FTL string literal whose evaluated value equals tos- Since:
- 2.3.22
-
isFTLIdentifierStart
public static boolean isFTLIdentifierStart(char c)Tells if a character can occur on the beginning of an FTL identifier expression (without escaping).- Since:
- 2.3.22
-
isFTLIdentifierPart
public static boolean isFTLIdentifierPart(char c)Tells if a character can occur in an FTL identifier expression (without escaping) as other than the first character.- Since:
- 2.3.22
-
isBackslashEscapedFTLIdentifierCharacter
public static boolean isBackslashEscapedFTLIdentifierCharacter(char c)Tells if a character can occur in an FTL identifier if it's preceded with a backslash. For example,"-"is a such character (as you can have an identifier likefoo\-barin FTL), but"f"is not, as it needn't be, and can't be escaped.- Since:
- 2.3.31
-
javaStringEnc
Escapes theStringwith 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. See more details atjavaStringEnc(String, boolean), as this just calls that withfalseas the 2nd argument. -
javaStringEnc
Escapes theStringwith the escaping rules of Java language string literals, and then ifquoteis true, it also adds quotation marks before and after it.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
Escapes aStringto be safely insertable into a JavaScript string literal; for more seejsStringEnc(s, JsStringEncCompatibility.JAVA_SCRIPT, null). -
jsonStringEnc
Escapes aStringto be safely insertable into a JSON string literal; for more seejsStringEnc(s, JsStringEncCompatibility.JSON, null). -
jsStringEnc
Deprecated.UsejsStringEnc(String, JsStringEncCompatibility)instead.Escapes aStringto be safely insertable into a JSON or JavaScript string literal; for more seejsStringEnc(s, json ? JsStringEncCompatibility.JSON : JsStringEncCompatibility.JAVA_SCRIPT, null).- Since:
- 2.3.20
-
jsStringEnc
Escapes aStringto be safely insertable into a JSON or JavaScript string literal; for more seejsStringEnc(s, compatibility, null).- Since:
- 2.3.32
-
jsStringEnc
public static String jsStringEnc(String s, StringUtil.JsStringEncCompatibility compatibility, StringUtil.JsStringEncQuotation quotation)Escapes aStringto be safely insertable into a JavaScript or a JSON string literal, and if the 3rd argument istrue, also adds quotation marks around it. If instead the caller ensures that the quotation marks are there, then in JSON mode (2nd argument), the quotation marks must be", not', because for JSON we won't escape'.The escaping rules guarantee that if the inside of the JavaScript/JSON string literal is from one or more touching pieces that were escaped with this, no character sequence can occur that closes the JavaScript/JSON string literal, or has a meaning in HTML/XML that causes the HTML script section to be closed. (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 ifais"script>".) The escaped characters are:Input Output "\"'if not in JSON-mode, nor is thequitedargumenttrue\'\\\/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?\u003Cu0000-u001f (UNICODE control characters - disallowed by JSON)
u007f-u009f (UNICODE control characters - disallowed by JSON)\n,\rand such, or if there's no such dedicated escape: JavaScript:\xXX, JSON:\uXXXXu2028 (Line separator - source code line-break in ECMAScript)
u2029 (Paragraph separator - source code line-break in ECMAScript)
\uXXXX- Parameters:
s- The string to escapecompatibility- If escaping should restrict itself to rules that are valid in JSON, in JavaScript, or in both.quotation- In notnull, quotation marks of this type are added around the value.- Since:
- 2.3.32
-
parseNameValuePairList
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 ifdefaultValueis 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:
ParseException- if the string is not a valid name-value pair list.
-
isXMLID
Deprecated.Don't use this outside FreeMarker; it's name if misleading, and it doesn't follow the XML specs.Used internally by the XML DOM wrapper to check if the subvariable name is just an element name, or a more complex XPath expression.- Returns:
- whether the name is a valid XML element name. (This routine might only be 99% accurate. REVISIT)
-
matchesName
- Returns:
- whether the qname matches the combination of nodeName, nsURI, and environment prefix settings.
-
leftPad
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
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
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 benull.
-
rightPad
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
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
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 benull.
-
versionStringToInt
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
Tries to runtoString(), but if that fails, returns a"[com.example.SomeClass.toString() failed: " + e + "]"instead. Also, it returnsnullfornullparameter.- Since:
- 2.3.20
-
toUpperABC
Converts1,2,3and so forth to"A","B","C"and so fort. When reaching"Z", it continues like"AA","AB", etc. The lowest supported number is 1, but there's no upper limit.- Throws:
IllegalArgumentException- If the argument is 0 or less.- Since:
- 2.3.22
-
toLowerABC
Same astoUpperABC(int), but produces lower case result, like"ab".- Since:
- 2.3.22
-
trim
public static char[] trim(char[] cs)Behaves exactly likeString.trim(), but works on arrays. If the resulting array would have the same content after trimming, it returns the original array instance. Otherwise it returns a new array instance (orCollectionUtils.EMPTY_CHAR_ARRAY).- Since:
- 2.3.22
-
isTrimmableToEmpty
public static boolean isTrimmableToEmpty(char[] text)Tells ifString.trim()will return a 0-length string for theStringequivalent of the argument.- Since:
- 2.3.22
-
isTrimmableToEmpty
public static boolean isTrimmableToEmpty(char[] text, int start)LikeisTrimmableToEmpty(char[]), but acts on a sub-array that starts atstart(inclusive index).- Since:
- 2.3.23
-
isTrimmableToEmpty
public static boolean isTrimmableToEmpty(char[] text, int start, int end)LikeisTrimmableToEmpty(char[]), but acts on a sub-array that starts atstart(inclusive index) and ends atend(exclusive index).- Since:
- 2.3.23
-
isWhitespaceOrNonBreakingWhitespace
public static boolean isWhitespaceOrNonBreakingWhitespace(char c)LikeCharacter.isWhitespace(char), but also considers non-breaking whitespace characters as whitespace.- Since:
- 2.3.34
-
globToRegularExpression
- Since:
- 2.3.24
-
globToRegularExpression
Creates a regular expression from a glob. The glob must use/for as file separator, not\(backslash), and is always case sensitive.This glob implementation recognizes these special characters:
?: Wildcard that matches exactly one character, other than/*: Wildcard that matches zero, one or multiple characters, other than/**: Wildcard that matches zero, one or multiple directories. For example,**/head.ftlmatchesfoo/bar/head.ftl,foo/head.ftlandhead.ftltoo.**must be either preceded by/or be at the beginning of the glob.**must be either followed by/or be at the end of the glob. When**is at the end of the glob, it also matches file names, likea/**matchesa/b/c.ftl. If the glob only consist of a**, it will be a match for everything.\(backslash): Makes the next character non-special (a literal). For exampleHow\?.ftlwill matchHow?.ftl, but notHowX.ftl. Naturally, two backslashes produce one literal backslash.[: Reserved for future purposes; can't be used{: Reserved for future purposes; can't be used
- Since:
- 2.3.24
-
XHTMLEnc(String)instead, because it escapes apostrophe-quote too.