Class Util
A grep method is not included for two reasons:
- The details of reading a line at a time from an input stream differ in JDK 1.0.2 and JDK 1.1, making it difficult to retain compatibility across both Java releases.
- Grep style processing is trivial for the programmer to implement in a while loop. Rarely does anyone want to retrieve all occurences of a pattern and then process them. More often a programmer will retrieve pattern matches and process them as they are retrieved, which is more efficient than storing them all in a Vector and then accessing them.
- Since:
- 1.0
- Version:
- 2.0.8
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
A constant passed to thesplit()
methods indicating that all occurrences of a pattern should be used to split a string.static final int
A constant passed to thesubstitute()
methods indicating that all occurrences of a pattern should be substituted. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
split
(Collection results, PatternMatcher matcher, Pattern pattern, String input) Splits up aString
instance and stores results as aCollection
of all its substrings using a regular expression as the delimiter.static void
split
(Collection results, PatternMatcher matcher, Pattern pattern, String input, int limit) Splits up aString
instance and stores results as aList
of substrings numbering no more than a specified limit.static Vector
split
(PatternMatcher matcher, Pattern pattern, String input) Deprecated.static Vector
split
(PatternMatcher matcher, Pattern pattern, String input, int limit) Deprecated.static int
substitute
(StringBuffer result, PatternMatcher matcher, Pattern pattern, Substitution sub, String input, int numSubs) Searches a string for a pattern and replaces the first occurrences of the pattern with a Substitution up to the number of substitutions specified by the numSubs parameter.static int
substitute
(StringBuffer result, PatternMatcher matcher, Pattern pattern, Substitution sub, PatternMatcherInput input, int numSubs) Searches a string for a pattern and replaces the first occurrences of the pattern with a Substitution up to the number of substitutions specified by the numSubs parameter.static String
substitute
(PatternMatcher matcher, Pattern pattern, Substitution sub, String input) Searches a string for a pattern and substitutes only the first occurence of the pattern.static String
substitute
(PatternMatcher matcher, Pattern pattern, Substitution sub, String input, int numSubs) Searches a string for a pattern and replaces the first occurrences of the pattern with a Substitution up to the number of substitutions specified by the numSubs parameter.
-
Field Details
-
SUBSTITUTE_ALL
public static final int SUBSTITUTE_ALLA constant passed to thesubstitute()
methods indicating that all occurrences of a pattern should be substituted.- See Also:
-
SPLIT_ALL
public static final int SPLIT_ALLA constant passed to thesplit()
methods indicating that all occurrences of a pattern should be used to split a string.- See Also:
-
-
Method Details
-
split
public static void split(Collection results, PatternMatcher matcher, Pattern pattern, String input, int limit) Splits up aString
instance and stores results as aList
of substrings numbering no more than a specified limit. The string is split with a regular expression as the delimiter. The limit parameter essentially says to split the string only on at most the first limit - 1 number of pattern occurences.This method is inspired by the Perl split() function and behaves identically to it when used in conjunction with the Perl5Matcher and Perl5Pattern classes except for the following difference:
In Perl, if the split expression contains parentheses, the split() method creates additional list elements from each of the matching subgroups in the pattern. In other words:
split(list, "/([,-])/", "8-12,15,18", Util.SPLIT_ALL)
produces the list containing:
{ "8", "-", "12", ",", "15", ",", "18" }
The OROMatcher split method does not follow this behavior. The following list would be produced by OROMatcher:
{ "8", "12", "15", "18" }
To obtain the Perl behavior, use
Perl5Util.split(java.util.Collection, java.lang.String, java.lang.String, int)
.- Parameters:
results
- A Collection to which the split results are appended. After the method returns, it contains the substrings of the input that occur between the regular expression delimiter occurences. The input will not be split into any more substrings than the specifiedlimit
. A way of thinking of this is that only the firstlimit - 1
matches of the delimiting regular expression will be used to split the input.matcher
- The regular expression matcher to execute the split.pattern
- The regular expression to use as a split delimiter.input
- TheString
to split.limit
- The limit on the number of resulting split elements. Values invalid input: '<'= 0 produce the same behavior as using the SPLIT_ALL constant which causes the limit to be ignored and splits to be performed on all occurrences of the pattern. You should use the SPLIT_ALL constant to achieve this behavior instead of relying on the default behavior associated with non-positive limit values.- Since:
- 2.0
-
split
Splits up aString
instance and stores results as aCollection
of all its substrings using a regular expression as the delimiter. This method is inspired by the Perl split() function and behaves identically to it when used in conjunction with the Perl5Matcher and Perl5Pattern classes except for the following difference:-
In Perl, if the split expression contains parentheses, the split()
method creates additional list elements from each of the matching
subgroups in the pattern. In other words:
split(list, "/([,-])/", "8-12,15,18")
produces the list containing:
{ "8", "-", "12", ",", "15", ",", "18" }
The OROMatcher split method does not follow this behavior. The following list would be produced by OROMatcher:
{ "8", "12", "15", "18" }
To obtain the Perl behavior, use
Perl5Util.split(java.util.Collection, java.lang.String, java.lang.String, int)
.This method is identical to calling:
split(matcher, pattern, input, Util.SPLIT_ALL);
- Parameters:
results
- ACollection
to which all the substrings of the input that occur between the regular expression delimiter occurences are appended.matcher
- The regular expression matcher to execute the split.pattern
- The regular expression to use as a split delimiter.input
- TheString
to split.- Since:
- 2.0
-
split
Deprecated.Splits up aString
instance into strings contained in aVector
of size not greater than a specified limit. The string is split with a regular expression as the delimiter. The limit parameter essentially says to split the string only on at most the first limit - 1 number of pattern occurences.This method is inspired by the Perl split() function and behaves identically to it when used in conjunction with the Perl5Matcher and Perl5Pattern classes except for the following difference:
In Perl, if the split expression contains parentheses, the split() method creates additional list elements from each of the matching subgroups in the pattern. In other words:
split("/([,-])/", "8-12,15,18")
produces the Vector containing:
{ "8", "-", "12", ",", "15", ",", "18" }
The OROMatcher split method does not follow this behavior. The following Vector would be produced by OROMatcher:
{ "8", "12", "15", "18" }
To obtain the Perl behavior, use
Perl5Util.split(java.util.Collection, java.lang.String, java.lang.String, int)
.- Parameters:
matcher
- The regular expression matcher to execute the split.pattern
- The regular expression to use as a split delimiter.input
- TheString
to split.limit
- The limit on the size of the returnedVector
. Values invalid input: '<'= 0 produce the same behavior as using the SPLIT_ALL constant which causes the limit to be ignored and splits to be performed on all occurrences of the pattern. You should use the SPLIT_ALL constant to achieve this behavior instead of relying on the default behavior associated with non-positive limit values.- Returns:
- A
Vector
containing the substrings of the input that occur between the regular expression delimiter occurences. The input will not be split into any more substrings than the specifiedlimit
. A way of thinking of this is that only the firstlimit - 1
matches of the delimiting regular expression will be used to split the input. - Since:
- 1.0
-
split
Deprecated.Usesplit(Collection, PatternMatcher, Pattern, String)
instead.Splits up aString
instance into aVector
of all its substrings using a regular expression as the delimiter. This method is inspired by the Perl split() function and behaves identically to it when used in conjunction with the Perl5Matcher and Perl5Pattern classes except for the following difference:-
In Perl, if the split expression contains parentheses, the split()
method creates additional list elements from each of the matching
subgroups in the pattern. In other words:
split("/([,-])/", "8-12,15,18")
produces the Vector containing:
{ "8", "-", "12", ",", "15", ",", "18" }
The OROMatcher split method does not follow this behavior. The following Vector would be produced by OROMatcher:
{ "8", "12", "15", "18" }
To obtain the Perl behavior, use
Perl5Util.split(java.util.Collection, java.lang.String, java.lang.String, int)
.This method is identical to calling:
split(matcher, pattern, input, Util.SPLIT_ALL);
- Parameters:
matcher
- The regular expression matcher to execute the split.pattern
- The regular expression to use as a split delimiter.input
- TheString
to split.- Returns:
- A
Vector
containing all the substrings of the input that occur between the regular expression delimiter occurences. - Since:
- 1.0
-
substitute
public static String substitute(PatternMatcher matcher, Pattern pattern, Substitution sub, String input, int numSubs) Searches a string for a pattern and replaces the first occurrences of the pattern with a Substitution up to the number of substitutions specified by the numSubs parameter. A numSubs value of SUBSTITUTE_ALL will cause all occurrences of the pattern to be replaced.- Parameters:
matcher
- The regular expression matcher to execute the pattern search.pattern
- The regular expression to search for and substitute occurrences of.sub
- The Substitution used to substitute pattern occurences.input
- TheString
on which to perform substitutions.numSubs
- The number of substitutions to perform. Only the first numSubs patterns encountered are substituted. If you want to substitute all occurences set this parameter to SUBSTITUTE_ALL .- Returns:
- A String comprising the input string with the substitutions, if any, made. If no substitutions are made, the returned String is the original input String.
- Since:
- 1.0
-
substitute
public static String substitute(PatternMatcher matcher, Pattern pattern, Substitution sub, String input) Searches a string for a pattern and substitutes only the first occurence of the pattern.This method is identical to calling:
substitute(matcher, pattern, sub, input, 1);
- Parameters:
matcher
- The regular expression matcher to execute the pattern search.pattern
- The regular expression to search for and substitute occurrences of.sub
- The Substitution used to substitute pattern occurences.input
- TheString
on which to perform substitutions.- Returns:
- A String comprising the input string with the substitutions, if any, made. If no substitutions are made, the returned String is the original input String.
- Since:
- 1.0
-
substitute
public static int substitute(StringBuffer result, PatternMatcher matcher, Pattern pattern, Substitution sub, String input, int numSubs) Searches a string for a pattern and replaces the first occurrences of the pattern with a Substitution up to the number of substitutions specified by the numSubs parameter. A numSubs value of SUBSTITUTE_ALL will cause all occurrences of the pattern to be replaced. The number of substitutions made is returned.- Parameters:
result
- The StringBuffer in which to store the result of the substitutions. The buffer is only appended to.matcher
- The regular expression matcher to execute the pattern search.pattern
- The regular expression to search for and substitute occurrences of.sub
- The Substitution used to substitute pattern occurences.input
- The input on which to perform substitutions.numSubs
- The number of substitutions to perform. Only the first numSubs patterns encountered are substituted. If you want to substitute all occurences set this parameter to SUBSTITUTE_ALL .- Returns:
- The number of substitutions made.
- Since:
- 2.0.6
-
substitute
public static int substitute(StringBuffer result, PatternMatcher matcher, Pattern pattern, Substitution sub, PatternMatcherInput input, int numSubs) Searches a string for a pattern and replaces the first occurrences of the pattern with a Substitution up to the number of substitutions specified by the numSubs parameter. A numSubs value of SUBSTITUTE_ALL will cause all occurrences of the pattern to be replaced. The number of substitutions made is returned.- Parameters:
result
- The StringBuffer in which to store the result of the substitutions. The buffer is only appended to.matcher
- The regular expression matcher to execute the pattern search.pattern
- The regular expression to search for and substitute occurrences of.sub
- The Substitution used to substitute pattern occurences.input
- The input on which to perform substitutions.numSubs
- The number of substitutions to perform. Only the first numSubs patterns encountered are substituted. If you want to substitute all occurences set this parameter to SUBSTITUTE_ALL .- Returns:
- The number of substitutions made.
- Since:
- 2.0.3
-
split(Collection, PatternMatcher, Pattern, String)
instead.