[LANG-1124] Add split by length methods in StringUtils

• Type: New Feature
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Component/s: lang.*
• Assignee: Unassigned
• Reporter: Loic Guibert
• Created: 30/Apr/15 08:30
• Updated: 27/Oct/17 12:58

Description

Add methods to split a String by fixed lengths :

public static String[] splitByLength(String str, int ... lengths);
public static String[] splitByLengthRepeatedly(String str, int ... lengths);

Detail :

/**
 * <p>Split a String into an array, using an array of fixed string lengths.</p>
 *
 * <p>If not null String input, the returned array size is same as the input lengths array.</p>
 *
 * <p>A null input String returns {@code null}.
 * A {@code null} or empty input lengths array returns an empty array.
 * A {@code 0} in the input lengths array results in en empty string.</p>
 *
 * <p>Extra characters are ignored (ie String length greater than sum of split lengths).
 * All empty substrings other than zero length requested, are returned {@code null}.</p>
 *
 * <pre>
 * StringUtils.splitByLength(null, *)      = null
 * StringUtils.splitByLength("abc")        = []
 * StringUtils.splitByLength("abc", null)  = []
 * StringUtils.splitByLength("abc", [])    = []
 * StringUtils.splitByLength("", 2, 4, 1)  = [null, null, null]
 *
 * StringUtils.splitByLength("abcdefg", 2, 4, 1)     = ["ab", "cdef", "g"]
 * StringUtils.splitByLength("abcdefghij", 2, 4, 1)  = ["ab", "cdef", "g"]
 * StringUtils.splitByLength("abcdefg", 2, 4, 5)     = ["ab", "cdef", "g"]
 * StringUtils.splitByLength("abcdef", 2, 4, 1)      = ["ab", "cdef", null]
 *
 * StringUtils.splitByLength(" abcdef", 2, 4, 1)     = [" a", "bcde", "f"]
 * StringUtils.splitByLength("abcdef ", 2, 4, 1)     = ["ab", "cdef", " "]
 * StringUtils.splitByLength("abcdefg", 2, 4, 0, 1)  = ["ab", "cdef", "", "g"]
 * StringUtils.splitByLength("abcdefg", -1)          = {@link IllegalArgumentException}
 * </pre>
 *
 * @param str  the String to parse, may be null
 * @param lengths  the string lengths where to cut, may be null, must not be negative
 * @return an array of splitted Strings, {@code null} if null String input
 * @throws IllegalArgumentException
 *             if one of the lengths is negative
 */
public static String[] splitByLength(String str, int ... lengths);


/**
 * <p>Split a String into an array, using an array of fixed string lengths repeated as
 * many times as necessary to reach the String end.</p>
 *
 * <p>If not null String input, the returned array size is a multiple of the input lengths array.</p>
 *
 * <p>A null input String returns {@code null}.
 * A {@code null} or empty input lengths array returns an empty array.
 * A {@code 0} in the input lengths array results in en empty string.</p>
 *
 * <p>All empty substrings other than zero length requested and following substrings,
 * are returned {@code null}.</p>
 *
 * <pre>
 * StringUtils.splitByLengthRepeated(null, *)      = null
 * StringUtils.splitByLengthRepeated("abc")        = []
 * StringUtils.splitByLengthRepeated("abc", null)  = []
 * StringUtils.splitByLengthRepeated("abc", [])    = []
 * StringUtils.splitByLengthRepeated("", 2, 4, 1)  = [null, null, null]
 *
 * StringUtils.splitByLengthRepeated("abcdefghij", 2, 3)     = ["ab", "cde", "fg", "hij"]
 * StringUtils.splitByLengthRepeated("abcdefgh", 2, 3)       = ["ab", "cde", "fg", "h"]
 * StringUtils.splitByLengthRepeated("abcdefg", 2, 3)        = ["ab", "cde", "fg", null]
 *
 * StringUtils.splitByLengthRepeated(" abcdef", 2, 3)        = [" a", "bcd", "ef", null]
 * StringUtils.splitByLengthRepeated("abcdef ", 2, 3)        = ["ab", "cde", "f ", null]
 * StringUtils.splitByLengthRepeated("abcdef", 2, 3, 0, 1)   = ["ab", "cde", "", "f"]
 * StringUtils.splitByLengthRepeated("abcdefg", 2, 3, 0, 1)  = ["ab", "cde", "", "f",
 *                                                              "g", null, null, null]
 * StringUtils.splitByLengthRepeated("abcdefgh", 2, 0, 1, 0) = ["ab", "", "c", "",
 *                                                              "de", "", "f", "",
 *                                                              "gh", "", null, null]
 * StringUtils.splitByLengthRepeated("abcdefg", 2, 0, 1, 0) = ["ab", "", "c", "",
 *                                                              "de", "", "f", "",
 *                                                              "g", null, null, null]
 * StringUtils.splitByLengthRepeated("abcdefg", -1)          = {@link IllegalArgumentException}
 * StringUtils.splitByLengthRepeated("abcdefg", 0, 0)        = {@link IllegalArgumentException}
 * </pre>
 *
 * @param str  the String to parse, may be null
 * @param lengths  the string lengths where to cut, may be null, must not be negative
 * @return an array of splitted Strings, {@code null} if null String input
 * @throws IllegalArgumentException
 *             if one of the lengths is negative or if lengths sum is less than 1
 */
public static String[] splitByLengthRepeatedly(String str, int... lengths);

See PR #75 : https://github.com/apache/commons-lang/pull/75

Issue Links

• is related to: LANG-1237 String Split For Fixed-Length Strings
• relates to: LANG-1237 String Split For Fixed-Length Strings
• links to: GitHub Pull Request #75