PrintStream


1   /*
2    * @(#)PrintStream.java 1.32 04/07/16
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.io;
9   
10  import java.util.Formatter  ;
11  import java.util.Locale  ;
12  
13  
14  /**
15   * A <code>PrintStream</code> adds functionality to another output stream,
16   * namely the ability to print representations of various data values
17   * conveniently.  Two other features are provided as well.  Unlike other output
18   * streams, a <code>PrintStream</code> never throws an
19   * <code>IOException</code>; instead, exceptional situations merely set an
20   * internal flag that can be tested via the <code>checkError</code> method.
21   * Optionally, a <code>PrintStream</code> can be created so as to flush
22   * automatically; this means that the <code>flush</code> method is
23   * automatically invoked after a byte array is written, one of the
24   * <code>println</code> methods is invoked, or a newline character or byte
25   * (<code>'\n'</code>) is written.
26   *
27   * <p> All characters printed by a <code>PrintStream</code> are converted into
28   * bytes using the platform's default character encoding.  The <code>{@link
29   * PrintWriter}</code> class should be used in situations that require writing
30   * characters rather than bytes.
31   *
32   * @version    1.32, 04/07/16
33   * @author     Frank Yellin
34   * @author     Mark Reinhold
35   * @since      JDK1.0
36   */
37  
38  public class PrintStream extends FilterOutputStream  
39      implements Appendable  , Closeable  
40  {
41  
42      private boolean autoFlush = false;
43      private boolean trouble = false;
44      private Formatter   formatter;
45  
46      /**
47       * Track both the text- and character-output streams, so that their buffers
48       * can be flushed without flushing the entire stream.
49       */
50      private BufferedWriter   textOut;
51      private OutputStreamWriter   charOut;
52  
53      /**
54       * Create a new print stream.  This stream will not flush automatically.
55       *
56       * @param  out        The output stream to which values and objects will be
57       *                    printed
58       *
59       * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
60       */
61      public PrintStream(OutputStream   out) {
62      this(out, false);
63      }
64  
65      /* Initialization is factored into a private constructor (note the swapped
66       * parameters so that this one isn't confused with the public one) and a
67       * separate init method so that the following two public constructors can
68       * share code.  We use a separate init method so that the constructor that
69       * takes an encoding will throw an NPE for a null stream before it throws
70       * an UnsupportedEncodingException for an unsupported encoding.
71       */
72  
73      private PrintStream(boolean autoFlush, OutputStream   out)
74      {
75      super(out);
76      if (out == null)
77          throw new NullPointerException  ("Null output stream");
78      this.autoFlush = autoFlush;
79      }
80  
81      private void init(OutputStreamWriter   osw) {
82      this.charOut = osw;
83      this.textOut = new BufferedWriter  (osw);
84      }
85  
86      /**
87       * Create a new print stream.
88       *
89       * @param  out        The output stream to which values and objects will be
90       *                    printed
91       * @param  autoFlush  A boolean; if true, the output buffer will be flushed
92       *                    whenever a byte array is written, one of the
93       *                    <code>println</code> methods is invoked, or a newline
94       *                    character or byte (<code>'\n'</code>) is written
95       *
96       * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream, boolean)
97       */
98      public PrintStream(OutputStream   out, boolean autoFlush) {
99      this(autoFlush, out);
100     init(new OutputStreamWriter  (this));
101     }
102 
103     /**
104      * Create a new print stream.
105      *
106      * @param  out        The output stream to which values and objects will be
107      *                    printed
108      * @param  autoFlush  A boolean; if true, the output buffer will be flushed
109      *                    whenever a byte array is written, one of the
110      *                    <code>println</code> methods is invoked, or a newline
111      *                    character or byte (<code>'\n'</code>) is written
112      * @param  encoding   The name of a supported
113      *                    <a HREF="../lang/package-summary.html#charenc">
114      *                    character encoding</a>
115      *
116      * @exception  UnsupportedEncodingException
117      *             If the named encoding is not supported
118      */
119     public PrintStream(OutputStream   out, boolean autoFlush, String   encoding)
120         throws UnsupportedEncodingException  
121     {
122     this(autoFlush, out);
123     init(new OutputStreamWriter  (this, encoding));
124     }
125 
126     /**
127      * Creates a new print stream, without automatic line flushing, with the
128      * specified file name.  This convenience constructor creates
129      * the necessary intermediate {@link java.io.OutputStreamWriter
130      * OutputStreamWriter}, which will encode characters using the
131      * {@linkplain java.nio.charset.Charset#defaultCharset default charset}
132      * for this instance of the Java virtual machine.
133      *
134      * @param  fileName
135      *         The name of the file to use as the destination of this print
136      *         stream.  If the file exists, then it will be truncated to
137      *         zero size; otherwise, a new file will be created.  The output
138      *         will be written to the file and is buffered.
139      *
140      * @throws  FileNotFoundException
141      *          If the given file object does not denote an existing, writable
142      *          regular file and a new regular file of that name cannot be
143      *          created, or if some other error occurs while opening or
144      *          creating the file
145      *
146      * @throws  SecurityException
147      *          If a security manager is present and {@link
148      *          SecurityManager#checkWrite checkWrite(fileName)} denies write
149      *          access to the file
150      *
151      * @since  1.5
152      */
153     public PrintStream(String   fileName) throws FileNotFoundException   {
154     this(false, new FileOutputStream  (fileName));
155     init(new OutputStreamWriter  (this));
156     }
157 
158     /**
159      * Creates a new print stream, without automatic line flushing, with the
160      * specified file name and charset.  This convenience constructor creates
161      * the necessary intermediate {@link java.io.OutputStreamWriter
162      * OutputStreamWriter}, which will encode characters using the provided
163      * charset.
164      *
165      * @param  fileName
166      *         The name of the file to use as the destination of this print
167      *         stream.  If the file exists, then it will be truncated to
168      *         zero size; otherwise, a new file will be created.  The output
169      *         will be written to the file and is buffered.
170      *
171      * @param  csn
172      *         The name of a supported {@linkplain java.nio.charset.Charset
173      *         charset}
174      *
175      * @throws  FileNotFoundException
176      *          If the given file object does not denote an existing, writable
177      *          regular file and a new regular file of that name cannot be
178      *          created, or if some other error occurs while opening or
179      *          creating the file
180      *
181      * @throws  SecurityException
182      *          If a security manager is present and {@link
183      *          SecurityManager#checkWrite checkWrite(fileName)} denies write
184      *          access to the file
185      *
186      * @throws  UnsupportedEncodingException
187      *          If the named charset is not supported
188      *
189      * @since  1.5
190      */
191     public PrintStream(String   fileName, String   csn)
192     throws FileNotFoundException  , UnsupportedEncodingException  
193     {
194     this(false, new FileOutputStream  (fileName));
195     init(new OutputStreamWriter  (this, csn));
196     }
197 
198     /**
199      * Creates a new print stream, without automatic line flushing, with the
200      * specified file.  This convenience constructor creates the necessary
201      * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
202      * which will encode characters using the {@linkplain
203      * java.nio.charset.Charset#defaultCharset default charset} for this
204      * instance of the Java virtual machine.
205      *
206      * @param  file
207      *         The file to use as the destination of this print stream.  If the
208      *         file exists, then it will be truncated to zero size; otherwise,
209      *         a new file will be created.  The output will be written to the
210      *         file and is buffered.
211      *
212      * @throws  FileNotFoundException
213      *          If the given file object does not denote an existing, writable
214      *          regular file and a new regular file of that name cannot be
215      *          created, or if some other error occurs while opening or
216      *          creating the file
217      *
218      * @throws  SecurityException
219      *          If a security manager is present and {@link
220      *          SecurityManager#checkWrite checkWrite(file.getPath())}
221      *          denies write access to the file
222      *
223      * @since  1.5
224      */
225     public PrintStream(File   file) throws FileNotFoundException   {
226     this(false, new FileOutputStream  (file));
227     init(new OutputStreamWriter  (this));
228     }
229 
230     /**
231      * Creates a new print stream, without automatic line flushing, with the
232      * specified file and charset.  This convenience constructor creates
233      * the necessary intermediate {@link java.io.OutputStreamWriter
234      * OutputStreamWriter}, which will encode characters using the provided
235      * charset.
236      *
237      * @param  file
238      *         The file to use as the destination of this print stream.  If the
239      *         file exists, then it will be truncated to zero size; otherwise,
240      *         a new file will be created.  The output will be written to the
241      *         file and is buffered.
242      *
243      * @param  csn
244      *         The name of a supported {@linkplain java.nio.charset.Charset
245      *         charset}
246      *
247      * @throws  FileNotFoundException
248      *          If the given file object does not denote an existing, writable
249      *          regular file and a new regular file of that name cannot be
250      *          created, or if some other error occurs while opening or
251      *          creating the file
252      *
253      * @throws  SecurityException
254      *          If a security manager is presentand {@link
255      *          SecurityManager#checkWrite checkWrite(file.getPath())}
256      *          denies write access to the file
257      *
258      * @throws  UnsupportedEncodingException
259      *          If the named charset is not supported
260      *
261      * @since  1.5
262      */
263     public PrintStream(File   file, String   csn)
264     throws FileNotFoundException  , UnsupportedEncodingException  
265     {
266     this(false, new FileOutputStream  (file));
267     init(new OutputStreamWriter  (this, csn));
268     }
269 
270     /** Check to make sure that the stream has not been closed */
271     private void ensureOpen() throws IOException   {
272     if (out == null)
273         throw new IOException  ("Stream closed");
274     }
275 
276     /**
277      * Flush the stream.  This is done by writing any buffered output bytes to
278      * the underlying output stream and then flushing that stream.
279      *
280      * @see        java.io.OutputStream#flush()
281      */
282     public void flush() {
283     synchronized (this) {
284         try {
285         ensureOpen();
286         out.flush();
287         }
288         catch (IOException   x) {
289         trouble = true;
290         }
291     }
292     }
293 
294     private boolean closing = false; /* To avoid recursive closing */
295 
296     /**
297      * Close the stream.  This is done by flushing the stream and then closing
298      * the underlying output stream.
299      *
300      * @see        java.io.OutputStream#close()
301      */
302     public void close() {
303     synchronized (this) {
304         if (! closing) {
305         closing = true;
306         try {
307             textOut.close();
308             out.close();
309         }
310         catch (IOException   x) {
311             trouble = true;
312         }
313         textOut = null;
314         charOut = null;
315         out = null;
316         }
317     }
318     }
319 
320     /**
321      * Flush the stream and check its error state.  The internal error state
322      * is set to <code>true</code> when the underlying output stream throws an
323      * <code>IOException</code> other than <code>InterruptedIOException</code>,
324      * and when the <code>setError</code> method is invoked.  If an operation
325      * on the underlying output stream throws an
326      * <code>InterruptedIOException</code>, then the <code>PrintStream</code>
327      * converts the exception back into an interrupt by doing:
328      * <pre>
329      *     Thread.currentThread().interrupt();
330      * </pre>
331      * or the equivalent.
332      *
333      * @return True if and only if this stream has encountered an
334      *         <code>IOException</code> other than
335      *         <code>InterruptedIOException</code>, or the
336      *         <code>setError</code> method has been invoked
337      */
338     public boolean checkError() {
339     if (out != null)
340         flush();
341     return trouble;
342     }
343 
344     /**
345      * Set the error state of the stream to <code>true</code>.
346      *
347      * @since JDK1.1
348      */
349     protected void setError() {
350     trouble = true;
351     try {
352         throw new IOException  ();
353     } catch (IOException   x) {
354     }
355     }
356 
357 
358     /*
359      * Exception-catching, synchronized output operations,
360      * which also implement the write() methods of OutputStream
361      */
362 
363     /**
364      * Write the specified byte to this stream.  If the byte is a newline and
365      * automatic flushing is enabled then the <code>flush</code> method will be
366      * invoked.
367      *
368      * <p> Note that the byte is written as given; to write a character that
369      * will be translated according to the platform's default character
370      * encoding, use the <code>print(char)</code> or <code>println(char)</code>
371      * methods.
372      *
373      * @param  b  The byte to be written
374      * @see #print(char)
375      * @see #println(char)
376      */
377     public void write(int b) {
378     try {
379         synchronized (this) {
380         ensureOpen();
381         out.write(b);
382         if ((b == '\n') && autoFlush)
383             out.flush();
384         }
385     }
386     catch (InterruptedIOException   x) {
387         Thread.currentThread().interrupt();
388     }
389     catch (IOException   x) {
390         trouble = true;
391     }
392     }
393 
394     /**
395      * Write <code>len</code> bytes from the specified byte array starting at
396      * offset <code>off</code> to this stream.  If automatic flushing is
397      * enabled then the <code>flush</code> method will be invoked.
398      *
399      * <p> Note that the bytes will be written as given; to write characters
400      * that will be translated according to the platform's default character
401      * encoding, use the <code>print(char)</code> or <code>println(char)</code>
402      * methods.
403      *
404      * @param  buf   A byte array
405      * @param  off   Offset from which to start taking bytes
406      * @param  len   Number of bytes to write
407      */
408     public void write(byte buf[], int off, int len) {
409     try {
410         synchronized (this) {
411         ensureOpen();
412         out.write(buf, off, len);
413         if (autoFlush)
414             out.flush();
415         }
416     }
417     catch (InterruptedIOException   x) {
418         Thread.currentThread().interrupt();
419     }
420     catch (IOException   x) {
421         trouble = true;
422     }
423     }
424 
425     /*
426      * The following private methods on the text- and character-output streams
427      * always flush the stream buffers, so that writes to the underlying byte
428      * stream occur as promptly as with the original PrintStream.
429      */
430 
431     private void write(char buf[]) {
432     try {
433         synchronized (this) {
434         ensureOpen();
435         textOut.write(buf);
436         textOut.flushBuffer();
437         charOut.flushBuffer();
438         if (autoFlush) {
439             for (int i = 0; i < buf.length; i++)
440             if (buf[i] == '\n')
441                 out.flush();
442         }
443         }
444     }
445     catch (InterruptedIOException   x) {
446         Thread.currentThread().interrupt();
447     }
448     catch (IOException   x) {
449         trouble = true;
450     }
451     }
452 
453     private void write(String   s) {
454     try {
455         synchronized (this) {
456         ensureOpen();
457         textOut.write(s);
458         textOut.flushBuffer();
459         charOut.flushBuffer();
460         if (autoFlush && (s.indexOf('\n') >= 0))
461             out.flush();
462         }
463     }
464     catch (InterruptedIOException   x) {
465         Thread.currentThread().interrupt();
466     }
467     catch (IOException   x) {
468         trouble = true;
469     }
470     }
471 
472     private void newLine() {
473     try {
474         synchronized (this) {
475         ensureOpen();
476         textOut.newLine();
477         textOut.flushBuffer();
478         charOut.flushBuffer();
479         if (autoFlush)
480             out.flush();
481         }
482     }
483     catch (InterruptedIOException   x) {
484         Thread.currentThread().interrupt();
485     }
486     catch (IOException   x) {
487         trouble = true;
488     }
489     }
490 
491 
492     /* Methods that do not terminate lines */
493 
494     /**
495      * Print a boolean value.  The string produced by <code>{@link
496      * java.lang.String#valueOf(boolean)}</code> is translated into bytes
497      * according to the platform's default character encoding, and these bytes
498      * are written in exactly the manner of the
499      * <code>{@link #write(int)}</code> method.
500      *
501      * @param      b   The <code>boolean</code> to be printed
502      */
503     public void print(boolean b) {
504     write(b ? "true" : "false");
505     }
506 
507     /**
508      * Print a character.  The character is translated into one or more bytes
509      * according to the platform's default character encoding, and these bytes
510      * are written in exactly the manner of the
511      * <code>{@link #write(int)}</code> method.
512      *
513      * @param      c   The <code>char</code> to be printed
514      */
515     public void print(char c) {
516     write(String.valueOf(c));
517     }
518 
519     /**
520      * Print an integer.  The string produced by <code>{@link
521      * java.lang.String#valueOf(int)}</code> is translated into bytes
522      * according to the platform's default character encoding, and these bytes
523      * are written in exactly the manner of the
524      * <code>{@link #write(int)}</code> method.
525      *
526      * @param      i   The <code>int</code> to be printed
527      * @see        java.lang.Integer#toString(int)
528      */
529     public void print(int i) {
530     write(String.valueOf(i));
531     }
532 
533     /**
534      * Print a long integer.  The string produced by <code>{@link
535      * java.lang.String#valueOf(long)}</code> is translated into bytes
536      * according to the platform's default character encoding, and these bytes
537      * are written in exactly the manner of the
538      * <code>{@link #write(int)}</code> method.
539      *
540      * @param      l   The <code>long</code> to be printed
541      * @see        java.lang.Long#toString(long)
542      */
543     public void print(long l) {
544     write(String.valueOf(l));
545     }
546 
547     /**
548      * Print a floating-point number.  The string produced by <code>{@link
549      * java.lang.String#valueOf(float)}</code> is translated into bytes
550      * according to the platform's default character encoding, and these bytes
551      * are written in exactly the manner of the
552      * <code>{@link #write(int)}</code> method.
553      *
554      * @param      f   The <code>float</code> to be printed
555      * @see        java.lang.Float#toString(float)
556      */
557     public void print(float f) {
558     write(String.valueOf(f));
559     }
560 
561     /**
562      * Print a double-precision floating-point number.  The string produced by
563      * <code>{@link java.lang.String#valueOf(double)}</code> is translated into
564      * bytes according to the platform's default character encoding, and these
565      * bytes are written in exactly the manner of the <code>{@link
566      * #write(int)}</code> method.
567      *
568      * @param      d   The <code>double</code> to be printed
569      * @see        java.lang.Double#toString(double)
570      */
571     public void print(double d) {
572     write(String.valueOf(d));
573     }
574 
575     /**
576      * Print an array of characters.  The characters are converted into bytes
577      * according to the platform's default character encoding, and these bytes
578      * are written in exactly the manner of the
579      * <code>{@link #write(int)}</code> method.
580      *
581      * @param      s   The array of chars to be printed
582      *
583      * @throws  NullPointerException  If <code>s</code> is <code>null</code>
584      */
585     public void print(char s[]) {
586     write(s);
587     }
588 
589     /**
590      * Print a string.  If the argument is <code>null</code> then the string
591      * <code>"null"</code> is printed.  Otherwise, the string's characters are
592      * converted into bytes according to the platform's default character
593      * encoding, and these bytes are written in exactly the manner of the
594      * <code>{@link #write(int)}</code> method.
595      *
596      * @param      s   The <code>String</code> to be printed
597      */
598     public void print(String   s) {
599     if (s == null) {
600         s = "null";
601     }
602     write(s);
603     }
604 
605     /**
606      * Print an object.  The string produced by the <code>{@link
607      * java.lang.String#valueOf(Object)}</code> method is translated into bytes
608      * according to the platform's default character encoding, and these bytes
609      * are written in exactly the manner of the
610      * <code>{@link #write(int)}</code> method.
611      *
612      * @param      obj   The <code>Object</code> to be printed
613      * @see        java.lang.Object#toString()
614      */
615     public void print(Object   obj) {
616     write(String.valueOf(obj));
617     }
618 
619 
620     /* Methods that do terminate lines */
621 
622     /**
623      * Terminate the current line by writing the line separator string.  The
624      * line separator string is defined by the system property
625      * <code>line.separator</code>, and is not necessarily a single newline
626      * character (<code>'\n'</code>).
627      */
628     public void println() {
629     newLine();
630     }
631 
632     /**
633      * Print a boolean and then terminate the line.  This method behaves as
634      * though it invokes <code>{@link #print(boolean)}</code> and then
635      * <code>{@link #println()}</code>.
636      *
637      * @param x  The <code>boolean</code> to be printed
638      */
639     public void println(boolean x) {
640     synchronized (this) {
641         print(x);
642         newLine();
643     }
644     }
645 
646     /**
647      * Print a character and then terminate the line.  This method behaves as
648      * though it invokes <code>{@link #print(char)}</code> and then
649      * <code>{@link #println()}</code>.
650      *
651      * @param x  The <code>char</code> to be printed.
652      */
653     public void println(char x) {
654     synchronized (this) {
655         print(x);
656         newLine();
657     }
658     }
659 
660     /**
661      * Print an integer and then terminate the line.  This method behaves as
662      * though it invokes <code>{@link #print(int)}</code> and then
663      * <code>{@link #println()}</code>.
664      *
665      * @param x  The <code>int</code> to be printed.
666      */
667     public void println(int x) {
668     synchronized (this) {
669         print(x);
670         newLine();
671     }
672     }
673 
674     /**
675      * Print a long and then terminate the line.  This method behaves as
676      * though it invokes <code>{@link #print(long)}</code> and then
677      * <code>{@link #println()}</code>.
678      *
679      * @param x  a The <code>long</code> to be printed.
680      */
681     public void println(long x) {
682     synchronized (this) {
683         print(x);
684         newLine();
685     }
686     }
687 
688     /**
689      * Print a float and then terminate the line.  This method behaves as
690      * though it invokes <code>{@link #print(float)}</code> and then
691      * <code>{@link #println()}</code>.
692      *
693      * @param x  The <code>float</code> to be printed.
694      */
695     public void println(float x) {
696     synchronized (this) {
697         print(x);
698         newLine();
699     }
700     }
701 
702     /**
703      * Print a double and then terminate the line.  This method behaves as
704      * though it invokes <code>{@link #print(double)}</code> and then
705      * <code>{@link #println()}</code>.
706      *
707      * @param x  The <code>double</code> to be printed.
708      */
709     public void println(double x) {
710     synchronized (this) {
711         print(x);
712         newLine();
713     }
714     }
715 
716     /**
717      * Print an array of characters and then terminate the line.  This method
718      * behaves as though it invokes <code>{@link #print(char[])}</code> and
719      * then <code>{@link #println()}</code>.
720      *
721      * @param x  an array of chars to print.
722      */
723     public void println(char x[]) {
724     synchronized (this) {
725         print(x);
726         newLine();
727     }
728     }
729 
730     /**
731      * Print a String and then terminate the line.  This method behaves as
732      * though it invokes <code>{@link #print(String)}</code> and then
733      * <code>{@link #println()}</code>.
734      *
735      * @param x  The <code>String</code> to be printed.
736      */
737     public void println(String   x) {
738     synchronized (this) {
739         print(x);
740         newLine();
741     }
742     }
743 
744     /**
745      * Print an Object and then terminate the line.  This method behaves as
746      * though it invokes <code>{@link #print(Object)}</code> and then
747      * <code>{@link #println()}</code>.
748      *
749      * @param x  The <code>Object</code> to be printed.
750      */
751     public void println(Object   x) {
752     synchronized (this) {
753         print(x);
754         newLine();
755     }
756     }
757 
758     /**
759      * A convenience method to write a formatted string to this output stream
760      * using the specified format string and arguments.
761      *
762      * <p> An invocation of this method of the form <tt>out.printf(format,
763      * args)</tt> behaves in exactly the same way as the invocation
764      *
765      * <pre>
766      *     out.format(format, args) </pre>
767      *
768      * @param  format
769      *         A format string as described in <a
770      *         HREF="../util//Formatter.html#syntax">Format string syntax</a>
771      *
772      * @param  args
773      *         Arguments referenced by the format specifiers in the format
774      *         string.  If there are more arguments than format specifiers, the
775      *         extra arguments are ignored.  The number of arguments is
776      *         variable and may be zero.  The maximum number of arguments is
777      *         limited by the maximum dimension of a Java array as defined by
778      *         the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
779      *         Virtual Machine Specification</a>.  The behaviour on a
780      *         <tt>null</tt> argument depends on the <a
781      *         HREF="../util/Formatter.html#syntax">conversion</a>.
782      *
783      * @throws  IllegalFormatException
784      *          If a format string contains an illegal syntax, a format
785      *          specifier that is incompatible with the given arguments,
786      *          insufficient arguments given the format string, or other
787      *          illegal conditions.  For specification of all possible
788      *          formatting errors, see the <a
789      *          HREF="../util/Formatter.html#detail">Details</a> section of the
790      *          formatter class specification.
791      *
792      * @throws  NullPointerException
793      *          If the <tt>format</tt> is <tt>null</tt>
794      *
795      * @return  This output stream
796      *
797      * @since  1.5
798      */
799     public PrintStream   printf(String   format, Object   ... args) {
800     return format(format, args);
801     }
802 
803     /**
804      * A convenience method to write a formatted string to this output stream
805      * using the specified format string and arguments.
806      *
807      * <p> An invocation of this method of the form <tt>out.printf(l, format,
808      * args)</tt> behaves in exactly the same way as the invocation
809      *
810      * <pre>
811      *     out.format(l, format, args) </pre>
812      *
813      * @param  l
814      *         The {@linkplain java.util.Locale locale} to apply during
815      *         formatting.  If <tt>l</tt> is <tt>null</tt> then no localization
816      *         is applied.
817      *
818      * @param  format
819      *         A format string as described in <a
820      *         HREF="../util/Formatter.html#syntax">Format string syntax</a>
821      *
822      * @param  args
823      *         Arguments referenced by the format specifiers in the format
824      *         string.  If there are more arguments than format specifiers, the
825      *         extra arguments are ignored.  The number of arguments is
826      *         variable and may be zero.  The maximum number of arguments is
827      *         limited by the maximum dimension of a Java array as defined by
828      *         the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
829      *         Virtual Machine Specification</a>.  The behaviour on a
830      *         <tt>null</tt> argument depends on the <a
831      *         HREF="../util/Formatter.html#syntax">conversion</a>.
832      *
833      * @throws  IllegalFormatException
834      *          If a format string contains an illegal syntax, a format
835      *          specifier that is incompatible with the given arguments,
836      *          insufficient arguments given the format string, or other
837      *          illegal conditions.  For specification of all possible
838      *          formatting errors, see the <a
839      *          HREF="../util/Formatter.html#detail">Details</a> section of the
840      *          formatter class specification.
841      *
842      * @throws  NullPointerException
843      *          If the <tt>format</tt> is <tt>null</tt>
844      *
845      * @return  This output stream
846      *
847      * @since  1.5
848      */
849     public PrintStream   printf(Locale   l, String   format, Object   ... args) {
850     return format(l, format, args);
851     }
852 
853     /**
854      * Writes a formatted string to this output stream using the specified
855      * format string and arguments.
856      *
857      * <p> The locale always used is the one returned by {@link
858      * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
859      * previous invocations of other formatting methods on this object.
860      *
861      * @param  format
862      *         A format string as described in <a
863      *         HREF="../util/Formatter.html#syntax">Format string syntax</a>
864      *
865      * @param  args
866      *         Arguments referenced by the format specifiers in the format
867      *         string.  If there are more arguments than format specifiers, the
868      *         extra arguments are ignored.  The number of arguments is
869      *         variable and may be zero.  The maximum number of arguments is
870      *         limited by the maximum dimension of a Java array as defined by
871      *         the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
872      *         Virtual Machine Specification</a>.  The behaviour on a
873      *         <tt>null</tt> argument depends on the <a
874      *         HREF="../util/Formatter.html#syntax">conversion</a>.
875      *
876      * @throws  IllegalFormatException
877      *          If a format string contains an illegal syntax, a format
878      *          specifier that is incompatible with the given arguments,
879      *          insufficient arguments given the format string, or other
880      *          illegal conditions.  For specification of all possible
881      *          formatting errors, see the <a
882      *          HREF="../util/Formatter.html#detail">Details</a> section of the
883      *          formatter class specification.
884      *
885      * @throws  NullPointerException
886      *          If the <tt>format</tt> is <tt>null</tt>
887      *
888      * @return  This output stream
889      *
890      * @since  1.5
891      */
892     public PrintStream   format(String   format, Object   ... args) {
893     try {
894         synchronized (this) {
895         ensureOpen();
896         if ((formatter == null)
897             || (formatter.locale() != Locale.getDefault()))
898             formatter = new Formatter  ((Appendable  ) this);
899         formatter.format(Locale.getDefault(), format, args);
900         }
901     } catch (InterruptedIOException   x) {
902         Thread.currentThread().interrupt();
903     } catch (IOException   x) {
904         trouble = true;
905     }
906     return this;
907     }
908 
909     /**
910      * Writes a formatted string to this output stream using the specified
911      * format string and arguments.
912      *
913      * @param  l
914      *         The {@linkplain java.util.Locale locale} to apply during
915      *         formatting.  If <tt>l</tt> is <tt>null</tt> then no localization
916      *         is applied.
917      *
918      * @param  format
919      *         A format string as described in <a
920      *         HREF="../util/Formatter.html#syntax">Format string syntax</a>
921      *
922      * @param  args
923      *         Arguments referenced by the format specifiers in the format
924      *         string.  If there are more arguments than format specifiers, the
925      *         extra arguments are ignored.  The number of arguments is
926      *         variable and may be zero.  The maximum number of arguments is
927      *         limited by the maximum dimension of a Java array as defined by
928      *         the <a HREF="http://java.sun.com/docs/books/vmspec/">Java
929      *         Virtual Machine Specification</a>.  The behaviour on a
930      *         <tt>null</tt> argument depends on the <a
931      *         HREF="../util/Formatter.html#syntax">conversion</a>.
932      *
933      * @throws  IllegalFormatException
934      *          If a format string contains an illegal syntax, a format
935      *          specifier that is incompatible with the given arguments,
936      *          insufficient arguments given the format string, or other
937      *          illegal conditions.  For specification of all possible
938      *          formatting errors, see the <a
939      *          HREF="../util/Formatter.html#detail">Details</a> section of the
940      *          formatter class specification.
941      *
942      * @throws  NullPointerException
943      *          If the <tt>format</tt> is <tt>null</tt>
944      *
945      * @return  This output stream
946      *
947      * @since  1.5
948      */
949     public PrintStream   format(Locale   l, String   format, Object   ... args) {
950     try {
951         synchronized (this) {
952         ensureOpen();
953         if ((formatter == null)
954             || (formatter.locale() != l))
955             formatter = new Formatter  (this, l);
956         formatter.format(l, format, args);
957         }
958     } catch (InterruptedIOException   x) {
959         Thread.currentThread().interrupt();
960     } catch (IOException   x) {
961         trouble = true;
962     }
963     return this;
964     }
965 
966     /**
967      * Appends the specified character sequence to this output stream.
968      *
969      * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
970      * behaves in exactly the same way as the invocation
971      *
972      * <pre>
973      *     out.print(csq.toString()) </pre>
974      *
975      * <p> Depending on the specification of <tt>toString</tt> for the
976      * character sequence <tt>csq</tt>, the entire sequence may not be
977      * appended.  appended.  For instance, invoking then <tt>toString</tt>
978      * method of a character buffer will return a subsequence whose content
979      * depends upon the buffer's position and limit.
980      *
981      * @param  csq
982      *         The character sequence to append.  If <tt>csq</tt> is
983      *         <tt>null</tt>, then the four characters <tt>"null"</tt> are
984      *         appended to this output stream.
985      *
986      * @return  This character stream
987      *
988      * @since  1.5
989      */
990     public PrintStream   append(CharSequence   csq) {
991     if (csq == null)
992         print("null");
993     else
994         print(csq.toString());
995         return this;
996     }
997 
998     /**
999      * Appends a subsequence of the specified character sequence to this output
1000     * stream. 
1001     * 
1002     * <p> An invocation of this method of the form <tt>out.append(csq, start,
1003     * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
1004     * exactly the same way as the invocation
1005     *
1006     * <pre>
1007     *     out.print(csq.subSequence(start, end).toString()) </pre>
1008     *
1009     * @param  csq
1010     *         The character sequence from which a subsequence will be
1011     *         appended.  If <tt>csq</tt> is <tt>null</tt>, then characters
1012     *         will be appended as if <tt>csq</tt> contained the four
1013     *         characters <tt>"null"</tt>.
1014     *
1015     * @param  start
1016     *         The index of the first character in the subsequence
1017     *
1018     * @param  end
1019     *         The index of the character following the last character in the
1020     *         subsequence
1021     *
1022     * @return  This character stream
1023     *
1024     * @throws  IndexOutOfBoundsException
1025     *          If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1026     *          is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1027     *          <tt>csq.length()</tt>
1028     *
1029     * @since  1.5
1030     */
1031    public PrintStream   append(CharSequence   csq, int start, int end) {
1032    CharSequence   cs = (csq == null ? "null" : csq);
1033    write(cs.subSequence(start, end).toString());
1034        return this;
1035    }
1036    
1037    /**
1038     * Appends the specified character to this output stream.
1039     *
1040     * <p> An invocation of this method of the form <tt>out.append(c)</tt>
1041     * behaves in exactly the same way as the invocation
1042     *
1043     * <pre>
1044     *     out.print(c) </pre>
1045     *
1046     * @param  c
1047     *         The 16-bit character to append
1048     *
1049     * @return  This output stream
1050     *
1051     * @since 1.5
1052     */
1053    public PrintStream   append(char c) {
1054    print(c);
1055    return this;
1056    }
1057
1058}
1059
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags