java.util
public
final
class
java.util.Scanner
A parser that parses a text string to primitive types with the help of
regular expression. It supports localized number and various radixes.
The input is broken into tokens by the delimiter pattern, which is whitespace
by default. The primitive types can be got via corresponding next methods. If
the token is not in valid format, an InputMissmatchException is thrown.
For example: Scanner s = new Scanner("1A true");
System.out.println(s.nextInt(16)); System.out.println(s.nextBoolean()); The
result: 26 true
A scanner can find or skip specific pattern with no regard to the delimiter.
All these methods and the various next and hasNext methods may block.
Scanner is not thread-safe without external synchronization
Summary
Public Constructors
Public Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Public Constructors
public
Scanner(File src)
Constructs a scanner that uses File as its input. The default charset is
applied when reading the file.
Parameters
src
| the file to be scanned |
public
Scanner(File src, String charsetName)
Constructs a scanner that uses File as its input. The specified charset
is applied when reading the file.
Parameters
src
| the file to be scanned |
charsetName
| the name of the encoding type of the file |
public
Scanner(String src)
Constructs a scanner that uses String as its input.
Parameters
src
| the string to be scanned
|
Constructs a scanner that uses InputStream as its input. The default
charset is applied when decoding the input.
Parameters
src
| the input stream to be scanned
|
Constructs a scanner that uses InputStream as its input. The specified
charset is applied when decoding the input.
Parameters
src
| the input stream to be scanned |
charsetName
| the encoding type of the input stream |
public
Scanner(Readable src)
Constructs a scanner that uses Readable as its input.
Parameters
src
| the Readable to be scanned
|
Constructs a scanner that uses ReadableByteChannel as its input. The
default charset is applied when decoding the input.
Parameters
src
| the ReadableByteChannel to be scanned
|
Constructs a scanner that uses ReadableByteChannel as its input. The
specified charset is applied when decoding the input.
Parameters
src
| the ReadableByteChannel to be scanned |
charsetName
| the encoding type of the content in the ReadableByteChannel |
Public Methods
public
void
close()
Closes the underlying input if the input implements Closeable. If the
scanner has been closed, this method will take no effect. The scanning
operation after calling this method will throw IllegalStateException
public
Pattern
delimiter()
Returns the
Pattern
in use by this scanner.
Returns
- the
Pattern
presently in use by this scanner
public
String
findInLine(Pattern pattern)
Tries to find the pattern in input. Delimiters are ignored. If the
pattern is found before line terminator, the matched string will be
returned, and the scanner will advance to the end of the matched string.
Otherwise, null will be returned and the scanner will not advance the
input. When waiting for input, the scanner may be blocked.
All the input may be cached if no line terminator exists in the buffer.
Parameters
pattern
| the pattern used to match input |
public
String
findInLine(String pattern)
Tries to find the pattern compiled from the specified string. The
delimiter will be ignored. It is the same as invoke
findInLine(Pattern.compile(pattern))
Parameters
pattern
| a string used to construct a pattern which in turn used to
match input |
public
String
findWithinHorizon(Pattern pattern, int horizon)
Tries to find the pattern in input from current position to the specified
horizon. Delimiters are ignored. If the pattern is found, the matched
string will be returned, and the scanner will advance to the end of the
matched string. Otherwise, null will be returned and scanner will not
advance the input. When waiting for input, the scanner may be blocked.
Scanner will never search exceed horizon code points from current
position. The position of horizon does have effects on the result of
match. For example, when input is "123", and current position is at zero,
findWithinHorizon(Pattern.compile("\\p{Digit}{3}"), 2) will return null.
While findWithinHorizon(Pattern.compile("\\p{Digit}{3}"), 3) will return
"123". Horizon is treated as a transparent, non-anchoring bound. (refer
to
useTransparentBounds(boolean) and
useAnchoringBounds(boolean))
Horizon whose value is zero will be ignored and the whole input will be
used for search. Under this situation, all the input may be cached.
An IllegalArgumentException will be thrown out if horizon is less than
zero.
Parameters
pattern
| the pattern used to scan |
horizon
| the search limit |
public
String
findWithinHorizon(String pattern, int horizon)
Tries to find the pattern in input from current position to the specified
horizon. Delimiters are ignored.
It is the same as invoke findWithinHorizon(Pattern.compile(pattern)).
Parameters
pattern
| the pattern used to scan |
horizon
| the search limit |
public
boolean
hasNext(Pattern pattern)
Returns true if this scanner's next token matches the specified pattern.
This method may be blocked when it is waiting for input to scan. This
scanner does not advance past the input that matched the pattern.
Parameters
pattern
| the specified pattern to scan |
Returns
- true iff this scanner's next token matches the specified pattern
public
boolean
hasNext(String pattern)
Returns true if this scanner's next token matches the pattern constructed
from the specified string. This method may be blocked when it is waiting
for input to scan. This scanner does not advance past the input that
matched the pattern.
The invocation of this method in the form hasNext(pattern) behaves in the
same way as the invocation of hasNext(Pattern.compile(pattern)).
Parameters
pattern
| the string specifying the pattern to scan for |
Returns
- true
iff this scanner's next token matches the specified pattern
public
boolean
hasNext()
Returns true if this scanner has next token. This method may be blocked
when it is waiting for input to scan. This scanner does not advance past
the input.
Returns
- true
iff this scanner has next token
public
boolean
hasNextBigDecimal()
Returns true if this scanner's next token can be translated into a valid
BigDecimal. The scanner does not advance past the input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid BigDecimal
public
boolean
hasNextBigInteger()
Returns true if this scanner's next token can be translated into a valid
BigInteger in the default radix. The scanner does not advance past the
input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid BigInteger
public
boolean
hasNextBigInteger(int radix)
Returns true if this scanner's next token can be translated into a valid
BigInteger in the specified radix. The scanner does not advance past the
input.
Parameters
radix
| the radix used to translate the token into a BigInteger |
Returns
- true iff the next token in this scanner's input can be translated
into a valid BigInteger
public
boolean
hasNextBoolean()
Returns true if this scanner's next token can be translated into a valid
boolean value. The scanner does not advance past the input that matched.
Returns
- true
iff the next token in this scanner's input can be translated
into a valid boolean value
public
boolean
hasNextByte(int radix)
Returns true if this scanner's next token can be translated into a valid
byte value in the specified radix. The scanner does not advance past the
input.
Parameters
radix
| the radix used to translate the token into a byte value |
Returns
- true iff the next token in this scanner's input can be translated
into a valid byte value
public
boolean
hasNextByte()
Returns true if this scanner's next token can be translated into a valid
byte value in the default radix. The scanner does not advance past the
input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid byte value
public
boolean
hasNextDouble()
Returns true if this scanner's next token can be translated into a valid
double value. The scanner does not advance past the input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid double value
public
boolean
hasNextFloat()
Returns true if this scanner's next token can be translated into a valid
float value. The scanner does not advance past the input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid float value
public
boolean
hasNextInt()
Returns true if this scanner's next token can be translated into a valid
int value in the default radix. The scanner does not advance past the
input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid int value
public
boolean
hasNextInt(int radix)
Returns true if this scanner's next token can be translated into a valid
int value in the specified radix. The scanner does not advance past the
input.
Parameters
radix
| the radix used to translate the token into an int value |
Returns
- true iff the next token in this scanner's input can be translated
into a valid int value
public
boolean
hasNextLine()
Returns true if there is another line in the input. Otherwise, returns
false. When waiting for input, the scanner may be blocked. No matter true
or false, the scanner will not advance any input.
Returns
- true if there is another line in the input. Otherwise, false will
be returned.
public
boolean
hasNextLong()
Returns true if this scanner's next token can be translated into a valid
long value in the default radix. The scanner does not advance past the
input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid long value
public
boolean
hasNextLong(int radix)
Returns true if this scanner's next token can be translated into a valid
long value in the specified radix. The scanner does not advance past the
input.
Parameters
radix
| the radix used to translate the token into a long value |
Returns
- true iff the next token in this scanner's input can be translated
into a valid long value
public
boolean
hasNextShort(int radix)
Returns true if this scanner's next token can be translated into a valid
short value in the specified radix. The scanner does not advance past the
input.
Parameters
radix
| the radix used to translate the token into a short value |
Returns
- true iff the next token in this scanner's input can be translated
into a valid short value
public
boolean
hasNextShort()
Returns true if this scanner's next token can be translated into a valid
short value in the default radix. The scanner does not advance past the
input.
Returns
- true iff the next token in this scanner's input can be translated
into a valid short value
Returns the last IOException thrown when reading the underlying input. If
no exception is thrown, return null.
Returns
- the last IOException thrown
public
Locale
locale()
Return the locale of this scanner.
Returns
- the locale of this scanner
Returns the match result of this scanner's last match operation.This
method throws IllegalStateException if no match operation has been
performed, or if the last match was unsuccessful.
The various nextXXX methods of Scanner provide a match result if they do
not complete with throwing an exception. For example, after an invocation
of the nextBoolean() method which returned a boolean value, this method
returns a match result for the search of the Boolean regular expression
defined above. In the same way,the findInLine(java.lang.String),
findWithinHorizon(java.lang.String, int), and
skip(java.util.regex.Pattern) methods will provide a match result if they
are successful.
Returns
- the match result of the last match operation
Returns the next token which is prefixed and postfixed by input that
matches the delimiter pattern if this token matches the pattern
constructed from the sepcified string. This method may be blocked when it
is waiting for input to scan. If this match successes, the scanner
advances past the next token that matched the pattern.
The invocation of this method in the form next(pattern) behaves in the
same way as the invocation of next(Pattern.compile(pattern)).
Parameters
pattern
| the string specifying the pattern to scan for |
Returns the next token which is prefixed and postfixed by input that
matches the delimiter pattern if this token matches the specified
pattern. This method may be blocked when it is waiting for input to scan,
even if a previous invocation of hasNext(Pattern) returned true. If this
match successes, the scanner advances past the next token that matched
the pattern.
Parameters
pattern
| the specified pattern to scan |
public
String
next()
Finds and Returns the next complete token which is prefixed and postfixed
by input that matches the delimiter pattern. This method may be blocked
when it is waiting for input to scan, even if a previous invocation of
hasNext() returned true. If this match successes, the scanner advances
past the next complete token.
public
BigDecimal
nextBigDecimal()
Translates the next token in this scanner's input into a BigDecimal and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextBigDecimal()
returned true. If this match succeeds, the scanner advances past the
input that matched.
If the next token matches the Float regular expression successfully, the
token is translated into a BigDecimal as following steps. At first all
locale specific prefixes ,group separators, and locale specific suffixes
are removed. Then non-ASCII digits are mapped into ASCII digits via
digit(char, int)}, a negative sign (-) is added if the
locale specific negative prefixes and suffixes were present. At last the
resulting String is passed to
BigDecimal(String)}.
Returns
- the BigDecimal scanned from the input
public
BigInteger
nextBigInteger()
Translates the next token in this scanner's input into a BigInteger and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextBigInteger()
returned true. If this match succeeds, the scanner advances past the
input that matched.
The invocation of this method in the form nextBigInteger() behaves in the
same way as the invocation of nextBigInteger(radix), the radix is the
default radix of this scanner.
Returns
- the BigInteger scanned from the input
public
BigInteger
nextBigInteger(int radix)
Translates the next token in this scanner's input into a BigInteger and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextBigInteger(radix)
returned true. If this match succeeds, the scanner advances past the
input that matched.
If the next token matches the Integer regular expression successfully,
the token is translated into a BigInteger as following steps. At first
all locale specific prefixes ,group separators, and locale specific
suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
via
digit(char, int)}, a negative sign (-) is added if
the locale specific negative prefixes and suffixes were present. At last
the resulting String is passed to
BigInteger(String, int)} with the specified radix.
Parameters
radix
| the radix used to translate the token into a BigInteger |
Returns
- the int value scanned from the input
public
boolean
nextBoolean()
Translates the next token in this scanner's input into a boolean value and
returns this value. This method will throw InputMismatchException if the
next token can not be interpreted as a boolean value with a case
insensitive pattern created from the string "true|false". If this match
succeeds, the scanner advances past the input that matched.
Returns
- the boolean value scanned from the input
public
byte
nextByte()
Translates the next token in this scanner's input into a byte value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextByte() returned
true. If this match succeeds, the scanner advances past the input that
matched.
The invocation of this method in the form nextByte() behaves in the same
way as the invocation of nextByte(radix), the radix is the default radix
of this scanner.
Returns
- the byte value scanned from the input
public
byte
nextByte(int radix)
Translates the next token in this scanner's input into a byte value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextByte(radix)
returned true. If this match succeeds, the scanner advances past the
input that matched.
If the next token matches the Integer regular expression successfully,
the token is translated into a byte value as following steps. At first
all locale specific prefixes ,group separators, and locale specific
suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
via
digit(char, int)}, a negative sign (-) is added if
the locale specific negative prefixes and suffixes were present. At last
the resulting String is passed to
parseByte(String, int)}
with the specified radix.
Parameters
radix
| the radix used to translate the token into byte value |
Returns
- the byte value scanned from the input
public
double
nextDouble()
Translates the next token in this scanner's input into a double value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextDouble() returned
true. If this match succeeds, the scanner advances past the input that
matched.
If the next token matches the Float regular expression successfully, the
token is translated into a double value as following steps. At first all
locale specific prefixes ,group separators, and locale specific suffixes
are removed. Then non-ASCII digits are mapped into ASCII digits via
digit(char, int)}, a negative sign (-) is added if the
locale specific negative prefixes and suffixes were present. At last the
resulting String is passed to
parseDouble(String)}.If the
token matches the localized NaN or infinity strings, it is also passed to
parseDouble(String)}.
Returns
- the double value scanned from the input
public
float
nextFloat()
Translates the next token in this scanner's input into a float value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextFloat() returned
true. If this match succeeds, the scanner advances past the input that
matched.
If the next token matches the Float regular expression successfully, the
token is translated into a float value as following steps. At first all
locale specific prefixes ,group separators, and locale specific suffixes
are removed. Then non-ASCII digits are mapped into ASCII digits via
digit(char, int)}, a negative sign (-) is added if the
locale specific negative prefixes and suffixes were present. At last the
resulting String is passed to
parseFloat(String)}.If the
token matches the localized NaN or infinity strings, it is also passed to
parseFloat(String)}.
Returns
- the float value scanned from the input
public
int
nextInt()
Translates the next token in this scanner's input into an int value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextInt() returned
true. If this match succeeds, the scanner advances past the input that
matched.
The invocation of this method in the form nextInt() behaves in the same
way as the invocation of nextInt(radix), the radix is the default radix
of this scanner.
Returns
- the int value scanned from the input
public
int
nextInt(int radix)
Translates the next token in this scanner's input into an int value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextInt(radix)
returned true. If this match succeeds, the scanner advances past the
input that matched.
If the next token matches the Integer regular expression successfully,
the token is translated into an int value as following steps. At first
all locale specific prefixes ,group separators, and locale specific
suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
via Character.digit, a negative sign (-) is added if the locale specific
negative prefixes and suffixes were present. At last the resulting String
is passed to Integer.parseInt with the specified radix.
Parameters
radix
| the radix used to translate the token into an int value |
Returns
- the int value scanned from the input
public
String
nextLine()
Returns the skipped input and advances the scanner to the beginning of
the next line. The returned result will exclude any line terminator.
When searching, if no line terminator is found, then a large amount of
input will be cached. If no line at all can be found, a
NoSuchElementException will be thrown out.
public
long
nextLong(int radix)
Translates the next token in this scanner's input into a long value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextLong(radix)
returned true. If this match succeeds, the scanner advances past the
input that matched.
If the next token matches the Integer regular expression successfully,
the token is translated into a long value as following steps. At first
all locale specific prefixes, group separators, and locale specific
suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
via
digit(char, int)}, a negative sign (-) is added if
the locale specific negative prefixes and suffixes were present. At last
the resulting String is passed to
parseLong(String, int)}
with the specified radix.
Parameters
radix
| the radix used to translate the token into a long value |
Returns
- the long value scanned from the input
public
long
nextLong()
Translates the next token in this scanner's input into a long value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextLong() returned
true. If this match succeeds, the scanner advances past the input that
matched.
The invocation of this method in the form nextLong() behaves in the same
way as the invocation of nextLong(radix), the radix is the default radix
of this scanner.
Returns
- the long value scanned from the input
public
short
nextShort()
Translates the next token in this scanner's input into a short value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextShort() returned
true. If this match succeeds, the scanner advances past the input that
matched.
The invocation of this method in the form nextShort() behaves in the same
way as the invocation of nextShort(radix), the radix is the default radix
of this scanner.
Returns
- the short value scanned from the input
public
short
nextShort(int radix)
Translates the next token in this scanner's input into a short value and
returns this value. This method may be blocked when it is waiting for
input to scan, even if a previous invocation of hasNextShort(radix)
returned true. If this match succeeds, the scanner advances past the
input that matched.
If the next token matches the Integer regular expression successfully,
the token is translated into a short value as following steps. At first
all locale specific prefixes, group separators, and locale specific
suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
via
digit(char, int)}, a negative sign (-) is added if
the locale specific negative prefixes and suffixes were present. At last
the resulting String is passed to
parseShort(String, int)}
with the specified radix.
Parameters
radix
| the radix used to translate the token into short value |
Returns
- the short value scanned from the input
public
int
radix()
Return the radix of this scanner.
Returns
- the radix of this scanner
public
void
remove()
The operation of remove is not supported by this implementation of
Iterator.
Tries to use specified pattern to match input from the current position.
The delimiter will be ignored. If matches, the matched input will be
skipped. If an anchored match of the specified pattern succeeds, input
will also be skipped. Otherwise, a NoSuchElementException will be thrown
out.
Patterns that can match a lot of input may cause the scanner to read in a
large amount of input.
Uses a pattern that matches nothing( sc.skip(Pattern.compile("[ \t]*")) )
will suppress NoSuchElementException.
Parameters
pattern
| used to skip over input |
Tries to use the specified string to construct a pattern. And then uses
the constructed pattern to match input from the current position. The
delimiter will be ignored.
It is the same as invoke skip(Pattern.compile(pattern))
Parameters
pattern
| the string used to construct a pattern which in turn used to
match input |
public
String
toString()
Returns a string. The string is used to represent this scanner. Contained
information may be helpful for debugging. The format of the string is
unspecified.
Returns
- a string to represent this scanner
public
Scanner
useDelimiter(Pattern pattern)
Set the delimiting pattern of this scanner
Parameters
pattern
| the delimiting pattern to use |
public
Scanner
useDelimiter(String pattern)
Set the delimiting pattern of this scanner with a pattern compiled from
the supplied string value
Parameters
pattern
| a string from which a Pattern can be compiled |
Set the locale of this scanner to a specified locale.
Parameters
l
| the specified locale to use |
public
Scanner
useRadix(int radix)
Set the radix of this scanner to a specified radix.
Parameters
radix
| the specified radix to use |