apache common Lang包StringUtils系列(一)

本文介绍的是lang包中StringUtils类的方法，是根据apache common lang包系列官网（http://commons.apache.org/proper/commons-lang/）上翻译过来的，留在此处仅供学习参考使用。

import org.apache.commons.lang3.StringUtils;

1 public static String abbreviate(String str,int maxWidth)
说明：
（1）如果字符串的字符数少于或等于maxWidth，则返回str；
（2）否则返回（substring(str,0,max-3) + "..."）;
（3）如果maxWidth小于4，抛出IllegalArgumentException异常；
（4）任何情况下都不会返回一个长度大于maxWidth的字符串。
实例：

 StringUtils.abbreviate(null, *)      = null
 StringUtils.abbreviate("", 4)        = ""
 StringUtils.abbreviate("abcdefg", 6) = "abc..."
 StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
 StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
 StringUtils.abbreviate("abcdefg", 4) = "a..."
 StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
 参数：
 str-需要转换的字符串，可以为null
 maxWidth-转换后字符串的长度，必须大于3(当str不为null时)
 返回值：
 处理后的字符串，如果str为null，则返回null
 异常：
 IllegalArgumentException-如果maxWidth值太小（小于4）

2 public static String abbreviate(String str,int offset,int maxWidth)
参数：
  str-需要转换的字符串，可以为null
  offset-左边需要省略显示的字符个数
  maxWidth-转换后字符串的总长度。
返回值：
  转换后的字符串，str是null则输出null。
练习：
 StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno"
 StringUtils.abbreviate("abcdefghij", 5, 6)= IllegalArgumentException

实例：
 StringUtils.abbreviate(null, *, *)                = null
 StringUtils.abbreviate("", 0, 4)                  = ""
 StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 0, 10)  = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 1, 10)  = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 4, 10)  = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 5, 10)  = "...fghi..."
 StringUtils.abbreviate("abcdefghijklmno", 6, 10)  = "...ghij..."
 StringUtils.abbreviate("abcdefghijklmno", 8, 10)  = "...ijklmno"
 StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno"
 StringUtils.abbreviate("abcdefghij", 0, 3)        = IllegalArgumentException

3 public static String abbreviateMiddle(String str, String middle, int length)
功能：将字符串缩短到指定长度（length），字符串的中间部分用替换字符串（middle）显示。

要点：
  源字符串和替换字符串都不能为空或null;
  length必须小于原字符串长度且必须大于0。
参数：
  str-源字符串，需要缩短的字符串；
  middle-用于替换中间部分字符串的字符串；
  length-缩短后的字符串长度。
返回值：
  如果上面要求都满足返回缩短后的字符串，否则返回原字符串。
实例：
  StringUtils.abbreviateMiddle("abc", null, 0)      = "abc"
  StringUtils.abbreviateMiddle("abc", ".", 3)      = "abc"
  StringUtils.abbreviateMiddle("abcdef", ".", 4)     = "ab.f"
练习：
  StringUtils.abbreviateMiddle("abcdefghij",".",5)  = "ab.ij"
  
4 public static String difference(String str1,String str2)
功能：
  比较两个字符串，从第二个字符串与第一个字符串不同开始，返回第二个字符串的剩余部分。
参数：
  str1-第一个字符串，可以为null
  str2-第二个字符串，可以为null
返回值：
  输出第二个字符串与第一个字符串不同的部分，如果两个字符串相同，输出空。
实例：
  StringUtils.difference(null, null) = null
  StringUtils.difference("", "abc") = "abc"
  StringUtils.difference("ab", "abxyz") = "xyz"
  StringUtils.difference("abcde", "abxyz") = "xyz"
练习：
  StringUtils.difference("abc", "ab") = ""

5 public static int indexOfDifference(CharSequence cs1,CharSequence cs2)
功能：
  比较两个字符串(CharSequence类型)，返回两个字符串开始不同的字符索引号。
注：
  CharSequence接口，实现了这个接口的类有：CharBuffer、String、StringBuffer、StringBuilder这个四个类
参数：
  cs1-CharSequence1，可以为null
  cs2-CharSequence2，可以为null
返回值：
  返回两个字符串开始不同的索引号，如果两个字符串相同，返回-1.
实例
  StringUtils.indexOfDifference("", "") = -1
  StringUtils.indexOfDifference("", "abc") = 0
  StringUtils.indexOfDifference("abc", "") = 0
  StringUtils.indexOfDifference("abc", "abc") = -1
  StringUtils.indexOfDifference("abcde", "abxyz") = 2
练习：
  StringUtils.indexOfDifference("abcde", "xyz") = 0

6 public static String getCommonPrefix(String... strs)
功能：
  比较数组中所有字符串，返回他们最初相同的部分。
参数：
  strs-字符串对象数组，可以为null
实例：
  StringUtils.getCommonPrefix(null) = ""
  StringUtils.getCommonPrefix(new String[] {}) = ""
  StringUtils.getCommonPrefix(new String[] {"abc"}) = "abc"
  StringUtils.getCommonPrefix(new String[] {"abc", "abc"}) = "abc"
  StringUtils.getCommonPrefix(new String[] {"abc", "a"}) = "a"
练习：
  StringUtils.getCommonPrefix(new String[] {"abddefg", "abcdefg"}) = "ab"
  
7 public static int getLevenshteinDistance(CharSequence s,CharSequence t)
功能：
  查找两个字符串的编辑距离。编辑距离是指一个字符串变成另一个字符串需要的改变次数，这里的一次改变包括对单个字符的删除、插入或替换。
参数：
  s-第一个字符串，不能为null
  t-第二个字符串，不能为null
返回值：
  编辑距离。
实例：
  StringUtils.getLevenshteinDistance(null, *)             = IllegalArgumentException
  StringUtils.getLevenshteinDistance(*, null)             = IllegalArgumentException
  StringUtils.getLevenshteinDistance("","")               = 0
  StringUtils.getLevenshteinDistance("frog", "fog")       = 1
  StringUtils.getLevenshteinDistance("fly", "ant")        = 3
  StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8
练习：
  StringUtils.getLevenshteinDistance("elephant", "hippo") = 7

8 public static int getLevenshteinDistance(CharSequence s, CharSequence t, int threshold)
功能：
  查找两个字符串的编辑距离，如果该距离小于或等于给定的阈值threshold。
参数：
  s-第一个字符串，不能为空；
  t-第二个字符串，不能为空；
  threshold-目标阈值，不能为负数
返回值：
   编辑距离，如果该值大于阈值，则返回-1.
实例：
 StringUtils.getLevenshteinDistance(null, *, *)             = IllegalArgumentException、
 StringUtils.getLevenshteinDistance(*, *, -1)               = IllegalArgumentException
 StringUtils.getLevenshteinDistance("","", 0)               = 0
 StringUtils.getLevenshteinDistance("aaapppp", "", 8)       = 7
 StringUtils.getLevenshteinDistance("aaapppp", "", 7)       = 7
 StringUtils.getLevenshteinDistance("aaapppp", "", 6))      = -1
  
9 public static boolean startsWith(CharSequence str,CharSequence prefix)
功能：
  检查一个字符串是否以prefix开头的。如果两者都为null被认为是相同的。这个比较是区分大小写的。
参数：
  str-被检查字符串，可以为null
  prefix-用于检查的prefix，可以为null
返回值：
  如果str是以prefix开始的，返回true；
  如果str和prefix均为null，返回true；
  否则返回false。
实例：
  StringUtils.startsWith(null, null)      = true
  StringUtils.startsWith("abcdef", "abc") = true
  StringUtils.startsWith("ABCDEF", "abc") = false
练习：
  StringUtils.startsWith("", "")      = true

10 public static boolean startsWithIgnoreCase(CharSequence str,CharSequence prefix)
同上，此函数不区分大小写的比较。
StringUtils.startsWith("ABCDEF", "abc") = true

11 public static boolean startsWithAny(CharSequence string, CharSequence... searchStrings)
功能：检查字符串是否开始于数组中任何一个字符串。该比较区分大小写。
  StringUtils.startsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
  StringUtils.startsWithAny("abcxyz", new String[] {null, "xyz", "ABC"}) = false
  
12 public static boolean endsWith(CharSequence str, CharSequence suffix)
功能：
  检查字符串str是否以suffix字符串结尾。区分大小写。
参数：
  str-被检查字符串，可以为null
  suffix-用于检查的字符串，可以为null
返回值：
  如果str以suffix结尾，则返回true；
  如果str和suffix均为null，则返回true；
  否者返回false。
实例：
  StringUtils.endsWith(null, null)      = true
  StringUtils.endsWith("abcdef", "def") = true
  StringUtils.endsWith("ABCDEF", "def") = false
  StringUtils.endsWith("ABCDEF", "cde") = false

13 public static boolean endsWithIgnoreCase(CharSequence str,CharSequence suffix)
同上，不区分大小写。
StringUtils.endsWithIgnoreCase("ABCDEF", "def") = true

14 public static boolean endsWithAny(CharSequence string, CharSequence... searchStrings)
功能：检查字符串是否结束于数组中任何一个字符串。该比较区分大小写。
StringUtils.endsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
StringUtils.endsWithAny("abcxyz", new String[] {null, "XYZ", "abc"}) = false
练习：
StringUtils.endsWithAny("abcxyz", new String[] {""}) = true

15 public static String appendIfMissing(String str, CharSequence suffix, CharSequence... suffixes)
功能：
  如果str不是以任何suffixes结尾，将字符串suffix拼接到字符串str后面。
参数：
  str-源字符串；
  suffix-拼接到源字符串末尾的字符串；
  suffixes-附加的用于判断str末尾字符串的有效后缀。
返回：
  如果拼接了suffix则生成一个新的字符串，否者返回源字符串。
实例：
  StringUtils.appendIfMissing("abc", null) = "abc"
  StringUtils.appendIfMissing("", "xyz") = "xyz"
  StringUtils.appendIfMissing("abc", "xyz") = "abcxyz"
  StringUtils.appendIfMissing("abcxyz", "xyz") = "abcxyz"
  StringUtils.appendIfMissing("abc", "xyz", "mno") = "abcxyz" 
  StringUtils.appendIfMissing("abcmno", "xyz", "mno") = "abcmno"
  StringUtils.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZxyz"
  StringUtils.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNOxyz"
练习：
  StringUtils.appendIfMissing("abcxyz", "xyz", "mno") = "abcxyz"

16 public static String appendIfMissingIgnoreCase(String str, CharSequence suffix, CharSequence... suffixes)
同上，不区分大小写。
  StringUtils.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZ"
  StringUtils.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNO"
  StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz") = "abcXYZ"
 
17 public static String prependIfMissing(String str, CharSequence prefix, CharSequence... prefixes)
功能：
  如果str不是以任何prefixes结尾，将字符串prefix拼接到字符串str前面。
参数：
  str-源字符串
  prefix-添加到源字符串前面的前缀字符串
  prefixes-有效的附加前缀判断字符串。
返回值：
  如果prefix添加到了源字符串中，则生成一个新的字符串；否者返回源字符串。
实例：
  StringUtils.prependIfMissing("", "xyz") = "xyz"
  StringUtils.prependIfMissing("abc", "xyz") = "xyzabc"
  StringUtils.prependIfMissing("xyzabc", "xyz") = "xyzabc"
  StringUtils.prependIfMissing("xyzabc", "xyz", "mno") = "xyzabc"
  StringUtils.prependIfMissing("mnoabc", "xyz", "mno") = "mnoabc"
  StringUtils.prependIfMissing("XYZabc", "xyz", "mno") = "xyzXYZabc"

18 public static String prependIfMissingIgnoreCase(String str, CharSequence prefix, CharSequence... prefixes)
同上，不区分大小写。
  StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz") = "XYZabc"
  StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz", "mno") = "XYZabc"
  StringUtils.prependIfMissingIgnoreCase("MNOabc", "xyz", "mno") = "MNOabc"

19 public static String wrap(String str, char wrapWith)
功能：
  用字符包裹字符串。
参数：
  str-需要被包裹的字符串，可以为null
  wrapWith-用于包裹字符串的字符。
返回值：
  包括完成后额字符创。如果str为null，则返回null。
实例： 
  StringUtils.wrap(null, *)        = null
  StringUtils.wrap("", *)          = ""
  StringUtils.wrap("ab", '\0')     = "ab"
  StringUtils.wrap("ab", 'x')      = "xabx"
  StringUtils.wrap("ab", '\'')     = "'ab'"
  StringUtils.wrap("\"ab\"", '\"') = "\"\"ab\"\""
 
20 public static String wrap(String str, String wrapWith)
功能：
  用字符串包裹字符串。
参数：
  str-需要被包裹的字符串，可以为null
  wrapWith-用于包裹字符串的字符串。
返回值：
  包裹后的字符串；如果str为null，则返回null。
实例：
  StringUtils.wrap(null, *)         = null
  StringUtils.wrap("", *)           = ""
  StringUtils.wrap("ab", null)      = "ab"
  StringUtils.wrap("ab", "x")       = "xabx"
  StringUtils.wrap("ab", "\"")      = "\"ab\""
  StringUtils.wrap("\"ab\"", "\"")  = "\"\"ab\"\""
  StringUtils.wrap("ab", "'")       = "'ab'"
  StringUtils.wrap("'abcd'", "'")   = "''abcd''"
  StringUtils.wrap("\"abcd\"", "'") = "'\"abcd\"'"
  StringUtils.wrap("'abcd'", "\"")  = "\"'abcd'\""