Summary
-------
Provide overload methods that take `Locale` argument in `java.io.Console` class
Problem
-------
`java.io.Console` class offers methods to interact with the terminal. Both input and output methods have `formatted` strings for its prompt or output respectively. However, the current methods rely only on the default locale to produce localized formatted strings. Thus users would have to set the default locale in order to interact with the terminal in their preferred locale-sensitive format, such as date/time.
Solution
--------
Introduce new overloaded methods to the existing methods that perform formatting operations. For example, add the following overloaded method to the existing `printf()` method.
```
public Console printf(Locale locale, String format, Object... args);
```
Specification
-------------
Insert the following sentence in `java.io.Console` class description:
* on the objects returned by {@link #reader()} and {@link #writer()} may
* block in multithreaded scenarios.
* <p>
+ * Operations that format strings are locale sensitive, using either the
+ * specified {@code Locale}, or the
+ * {@link Locale##default_locale default format Locale} to produce localized
+ * formatted strings.
+ * <p>
* Invoking {@code close()} on the objects returned by the {@link #reader()}
* and the {@link #writer()} will not close the underlying stream of those
* objects.
Add these new methods on `java.io.Console` class:
/**
* Writes a formatted string to this console's output stream using
* the specified format string and arguments with the specified
* {@code locale}.
*
* @param locale The {@linkplain Locale locale} to apply during
* formatting. If {@code locale} is {@code null} then no localization
* is applied.
*
* @param format
* A format string as described in {@link
* Formatter##syntax Format string syntax}.
*
* @param args
* Arguments referenced by the format specifiers in the format
* string. If there are more arguments than format specifiers, the
* extra arguments are ignored. The number of arguments is
* variable and may be zero. The maximum number of arguments is
* limited by the maximum dimension of a Java array as defined by
* <cite>The Java Virtual Machine Specification</cite>.
* The behavior on a
* {@code null} argument depends on the {@link
* Formatter##syntax conversion}.
*
* @throws IllegalFormatException
* If a format string contains an illegal syntax, a format
* specifier that is incompatible with the given arguments,
* insufficient arguments given the format string, or other
* illegal conditions. For specification of all possible
* formatting errors, see the {@link
* Formatter##detail Details} section
* of the formatter class specification.
*
* @return This console
* @since 23
*/
public Console format(Locale locale, String format, Object ... args)
/**
* A convenience method to write a formatted string to this console's
* output stream using the specified format string and arguments with
* the specified {@code locale}.
*
* @implSpec This is the same as calling
* {@code format(locale, format, args)}.
*
* @param locale The {@linkplain Locale locale} to apply during
* formatting. If {@code locale} is {@code null} then no localization
* is applied.
*
* @param format
* A format string as described in {@link
* Formatter##syntax Format string syntax}.
*
* @param args
* Arguments referenced by the format specifiers in the format
* string. If there are more arguments than format specifiers, the
* extra arguments are ignored. The number of arguments is
* variable and may be zero. The maximum number of arguments is
* limited by the maximum dimension of a Java array as defined by
* <cite>The Java Virtual Machine Specification</cite>.
* The behavior on a
* {@code null} argument depends on the {@link
* Formatter##syntax conversion}.
*
* @throws IllegalFormatException
* If a format string contains an illegal syntax, a format
* specifier that is incompatible with the given arguments,
* insufficient arguments given the format string, or other
* illegal conditions. For specification of all possible
* formatting errors, see the {@link
* Formatter##detail Details} section of the
* formatter class specification.
*
* @return This console
* @since 23
*/
public Console printf(Locale locale, String format, Object ... args)
/**
* Provides a formatted prompt using the specified {@code locale}, then
* reads a single line of text from the console.
*
* @param locale The {@linkplain Locale locale} to apply during
* formatting. If {@code locale} is {@code null} then no localization
* is applied.
*
* @param format
* A format string as described in {@link
* Formatter##syntax Format string syntax}.
*
* @param args
* Arguments referenced by the format specifiers in the format
* string. If there are more arguments than format specifiers, the
* extra arguments are ignored. The number of arguments is
* variable and may be zero. The maximum number of arguments is
* limited by the maximum dimension of a Java array as defined by
* <cite>The Java Virtual Machine Specification</cite>.
* The behavior on a
* {@code null} argument depends on the {@link
* Formatter##syntax conversion}.
*
* @throws IllegalFormatException
* If a format string contains an illegal syntax, a format
* specifier that is incompatible with the given arguments,
* insufficient arguments given the format string, or other
* illegal conditions. For specification of all possible
* formatting errors, see the {@link
* Formatter##detail Details} section of the
* of the formatter class specification.
*
* @throws IOError
* If an I/O error occurs.
*
* @return A string containing the line read from the console, not
* including any line-termination characters, or {@code null}
* if an end of stream has been reached.
* @since 23
*/
public String readLine(Locale locale, String format, Object ... args)
/**
* Provides a formatted prompt using the specified {@code locale}, then
* reads a password or passphrase from the console with echoing disabled.
*
* @param locale The {@linkplain Locale locale} to apply during
* formatting. If {@code locale} is {@code null} then no localization
* is applied.
*
* @param format
* A format string as described in {@link
* Formatter##syntax Format string syntax}
* for the prompt text.
*
* @param args
* Arguments referenced by the format specifiers in the format
* string. If there are more arguments than format specifiers, the
* extra arguments are ignored. The number of arguments is
* variable and may be zero. The maximum number of arguments is
* limited by the maximum dimension of a Java array as defined by
* <cite>The Java Virtual Machine Specification</cite>.
* The behavior on a
* {@code null} argument depends on the {@link
* Formatter##syntax conversion}.
*
* @throws IllegalFormatException
* If a format string contains an illegal syntax, a format
* specifier that is incompatible with the given arguments,
* insufficient arguments given the format string, or other
* illegal conditions. For specification of all possible
* formatting errors, see the {@link
* Formatter##detail Details} section of the
* section of the formatter class specification.
*
* @throws IOError
* If an I/O error occurs.
*
* @return A character array containing the password or passphrase read
* from the console, not including any line-termination characters,
* or {@code null} if an end of stream has been reached.
* @since 23
*/
public char[] readPassword(Locale locale, String format, Object ... args)
Modify the existing method descriptions as follows:
public Console format(String format, Object ... args):
/**
* Writes a formatted string to this console's output stream using
- * the specified format string and arguments.
+ * the specified format string and arguments with the
+ * {@link Locale##default_locale default format locale}.
+ *
public Console printf(String format, Object ... args):
/**
* A convenience method to write a formatted string to this console's
- * output stream using the specified format string and arguments.
+ * output stream using the specified format string and arguments with
+ * the {@link Locale##default_locale default format locale}.
*
- * <p> An invocation of this method of the form
- * {@code con.printf(format, args)} behaves in exactly the same way
- * as the invocation of
- * {@snippet lang=java :
- * con.format(format, args)
- * }
+ * @implSpec This is the same as calling {@code format(format, args)}.
*
public String readLine(String format, Object ... args):
/**
- * Provides a formatted prompt, then reads a single line of text from the
- * console.
+ * Provides a formatted prompt using the
+ * {@link Locale##default_locale default format locale}, then reads a
+ * single line of text from the console.
public char[] readPassword(String format, Object ... args):
/**
- * Provides a formatted prompt, then reads a password or passphrase from
- * the console with echoing disabled.
+ * Provides a formatted prompt using the
+ * {@link Locale##default_locale default format locale}, then reads a
+ * password or passphrase from the console with echoing disabled.
For those existing methods that take `args` argument, replace the `@param` description with:
* @param args
* Arguments referenced by the format specifiers in the format
* string. If there are more arguments than format specifiers, the
* extra arguments are ignored. The number of arguments is
* variable and may be zero. The maximum number of arguments is
* limited by the maximum dimension of a Java array as defined by
* <cite>The Java Virtual Machine Specification</cite>.
* The behavior on a
* {@code null} argument depends on the {@link
* Formatter##syntax conversion}.