001/* PrintWriter.java -- prints primitive values and objects to a stream as text 002 Copyright (C) 1998, 1999, 2000, 2001, 2005 Free Software Foundation 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038package java.io; 039 040import java.util.Locale; 041import java.util.Formatter; 042 043/* Written using "Java Class Libraries", 2nd edition, plus online 044 * API docs for JDK 1.2 beta from http://www.javasoft.com. 045 * Status: Believed complete and correct. 046 * However, should use native methods for conversion. 047 */ 048 049/** 050 * This class prints Java primitive values and objects to a stream as 051 * text. None of the methods in this class throw an exception. However, 052 * errors can be detected by calling the <code>checkError()</code> method. 053 * Additionally, this stream can be designated as "autoflush" when 054 * created so that any writes are automatically flushed to the underlying 055 * output sink whenever one of the <code>println</code> methods is 056 * called. (Note that this differs from the <code>PrintStream</code> 057 * class which also auto-flushes when it encounters a newline character 058 * in the chars written). 059 * 060 * @author Per Bothner (bothner@cygnus.com) 061 * @author Aaron M. Renn (arenn@urbanophile.com) 062 * @date April 17, 1998. 063 */ 064public class PrintWriter extends Writer 065{ 066 /** 067 * <code>true</code> if auto-flush is enabled, <code>false</code> otherwise 068 */ 069 private boolean autoflush; 070 071 /** 072 * This boolean indicates whether or not an error has ever occurred 073 * on this stream. 074 */ 075 private boolean error; 076 077 /** 078 * Indicates whether or not the stream has been closed. 079 */ 080 private boolean closed; 081 082 /** 083 * This is the underlying <code>Writer</code> we are sending output 084 * to 085 */ 086 protected Writer out; 087 088 /** 089 * This method intializes a new <code>PrintWriter</code> object to write 090 * to the specified output sink. The form of the constructor does not 091 * enable auto-flush functionality. 092 * 093 * @param wr The <code>Writer</code> to write to. 094 */ 095 public PrintWriter(Writer wr) 096 { 097 super(wr.lock); 098 this.out = wr; 099 } 100 101 /** 102 * This method intializes a new <code>PrintWriter</code> object to write 103 * to the specified output sink. This constructor also allows "auto-flush" 104 * functionality to be specified where the stream will be flushed after 105 * every line is terminated or newline character is written. 106 * 107 * @param wr The <code>Writer</code> to write to. 108 * @param autoflush <code>true</code> to flush the stream after every 109 * line, <code>false</code> otherwise 110 */ 111 public PrintWriter(Writer wr, boolean autoflush) 112 { 113 super(wr.lock); 114 this.out = wr; 115 this.autoflush = autoflush; 116 } 117 118 /** 119 * This method initializes a new <code>PrintWriter</code> object to write 120 * to the specified <code>OutputStream</code>. Characters will be converted 121 * to chars using the system default encoding. Auto-flush functionality 122 * will not be enabled. 123 * 124 * @param out The <code>OutputStream</code> to write to 125 */ 126 public PrintWriter(OutputStream out) 127 { 128 super(); 129 this.out = new OutputStreamWriter(out); 130 this.lock = this.out; 131 } 132 133 /** 134 * This method initializes a new <code>PrintWriter</code> object to write 135 * to the specified <code>OutputStream</code>. Characters will be converted 136 * to chars using the system default encoding. This form of the 137 * constructor allows auto-flush functionality to be enabled if desired 138 * 139 * @param out The <code>OutputStream</code> to write to 140 * @param autoflush <code>true</code> to flush the stream after every 141 * <code>println</code> call, <code>false</code> otherwise. 142 */ 143 public PrintWriter(OutputStream out, boolean autoflush) 144 { 145 this(out); 146 this.autoflush = autoflush; 147 } 148 149 /** 150 * This initializes a new PrintWriter object to write to the specified 151 * file. It creates a FileOutputStream object and wraps it in an 152 * OutputStreamWriter using the default encoding. 153 * @param file name of the file to write to 154 * @throws FileNotFoundException if the file cannot be written or created 155 * 156 * @since 1.5 157 */ 158 public PrintWriter(String file) throws FileNotFoundException 159 { 160 this(new FileOutputStream(file)); 161 } 162 163 /** 164 * This initializes a new PrintWriter object to write to the specified 165 * file. It creates a FileOutputStream object and wraps it in an 166 * OutputStreamWriter using the specified encoding. 167 * @param file name of the file to write to 168 * @param enc the encoding to use 169 * @throws FileNotFoundException if the file cannot be written or created 170 * @throws UnsupportedEncodingException if the encoding is not supported 171 * 172 * @since 1.5 173 */ 174 public PrintWriter(String file, String enc) 175 throws FileNotFoundException, UnsupportedEncodingException 176 { 177 this(new OutputStreamWriter(new FileOutputStream(file), enc)); 178 } 179 180 /** 181 * This initializes a new PrintWriter object to write to the specified 182 * file. It creates a FileOutputStream object and wraps it in an 183 * OutputStreamWriter using the default encoding. 184 * @param file the file to write to 185 * @throws FileNotFoundException if the file cannot be written or created 186 * 187 * @since 1.5 188 */ 189 public PrintWriter(File file) throws FileNotFoundException 190 { 191 this(new FileOutputStream(file)); 192 } 193 194 /** 195 * This initializes a new PrintWriter object to write to the specified 196 * file. It creates a FileOutputStream object and wraps it in an 197 * OutputStreamWriter using the specified encoding. 198 * @param file the file to write to 199 * @param enc the encoding to use 200 * @throws FileNotFoundException if the file cannot be written or created 201 * @throws UnsupportedEncodingException if the encoding is not supported 202 * 203 * @since 1.5 204 */ 205 public PrintWriter(File file, String enc) 206 throws FileNotFoundException, UnsupportedEncodingException 207 { 208 this(new OutputStreamWriter(new FileOutputStream(file), enc)); 209 } 210 211 /** 212 * This method can be called by subclasses to indicate that an error 213 * has occurred and should be reported by <code>checkError</code>. 214 */ 215 protected void setError() 216 { 217 error = true; 218 } 219 220 /** 221 * This method checks to see if an error has occurred on this stream. Note 222 * that once an error has occurred, this method will continue to report 223 * <code>true</code> forever for this stream. Before checking for an 224 * error condition, this method flushes the stream. 225 * 226 * @return <code>true</code> if an error has occurred, 227 * <code>false</code> otherwise 228 */ 229 public boolean checkError() 230 { 231 if (! closed) 232 flush(); 233 return error; 234 } 235 236 /** 237 * This method flushes any buffered chars to the underlying stream and 238 * then flushes that stream as well. 239 */ 240 public void flush() 241 { 242 try 243 { 244 out.flush(); 245 } 246 catch (IOException ex) 247 { 248 error = true; 249 } 250 } 251 252 /** 253 * This method closes this stream and all underlying streams. 254 */ 255 public void close() 256 { 257 try 258 { 259 out.close(); 260 closed = true; 261 } 262 catch (IOException ex) 263 { 264 error = true; 265 } 266 } 267 268 /** 269 * This method prints a <code>String</code> to the stream. The actual 270 * value printed depends on the system default encoding. 271 * 272 * @param str The <code>String</code> to print. 273 */ 274 public void print(String str) 275 { 276 write(str == null ? "null" : str); 277 } 278 279 /** 280 * This method prints a char to the stream. The actual value printed is 281 * determined by the character encoding in use. 282 * 283 * @param ch The <code>char</code> value to be printed 284 */ 285 public void print(char ch) 286 { 287 write((int) ch); 288 } 289 290 /** 291 * This method prints an array of characters to the stream. The actual 292 * value printed depends on the system default encoding. 293 * 294 * @param charArray The array of characters to print. 295 */ 296 public void print(char[] charArray) 297 { 298 write(charArray, 0, charArray.length); 299 } 300 301 /** 302 * This methods prints a boolean value to the stream. <code>true</code> 303 * values are printed as "true" and <code>false</code> values are printed 304 * as "false". 305 * 306 * @param bool The <code>boolean</code> value to print 307 */ 308 public void print(boolean bool) 309 { 310 // We purposely call write() and not print() here. This preserves 311 // compatibility with JDK 1.2. 312 write (bool ? "true" : "false"); 313 } 314 315 /** 316 * This method prints an integer to the stream. The value printed is 317 * determined using the <code>String.valueOf()</code> method. 318 * 319 * @param inum The <code>int</code> value to be printed 320 */ 321 public void print(int inum) 322 { 323 // We purposely call write() and not print() here. This preserves 324 // compatibility with JDK 1.2. 325 write(Integer.toString(inum)); 326 } 327 328 /** 329 * This method prints a long to the stream. The value printed is 330 * determined using the <code>String.valueOf()</code> method. 331 * 332 * @param lnum The <code>long</code> value to be printed 333 */ 334 public void print(long lnum) 335 { 336 // We purposely call write() and not print() here. This preserves 337 // compatibility with JDK 1.2. 338 write(Long.toString(lnum)); 339 } 340 341 /** 342 * This method prints a float to the stream. The value printed is 343 * determined using the <code>String.valueOf()</code> method. 344 * 345 * @param fnum The <code>float</code> value to be printed 346 */ 347 public void print(float fnum) 348 { 349 // We purposely call write() and not print() here. This preserves 350 // compatibility with JDK 1.2. 351 write(Float.toString(fnum)); 352 } 353 354 /** 355 * This method prints a double to the stream. The value printed is 356 * determined using the <code>String.valueOf()</code> method. 357 * 358 * @param dnum The <code>double</code> value to be printed 359 */ 360 public void print(double dnum) 361 { 362 // We purposely call write() and not print() here. This preserves 363 // compatibility with JDK 1.2. 364 write(Double.toString(dnum)); 365 } 366 367 /** 368 * This method prints an <code>Object</code> to the stream. The actual 369 * value printed is determined by calling the <code>String.valueOf()</code> 370 * method. 371 * 372 * @param obj The <code>Object</code> to print. 373 */ 374 public void print(Object obj) 375 { 376 // We purposely call write() and not print() here. This preserves 377 // compatibility with JDK 1.2. 378 write(obj == null ? "null" : obj.toString()); 379 } 380 381 /** 382 * This is the system dependent line separator 383 */ 384 private static final char[] line_separator 385 = System.getProperty("line.separator", "\n").toCharArray(); 386 387 /** 388 * This method prints a line separator sequence to the stream. The value 389 * printed is determined by the system property <xmp>line.separator</xmp> 390 * and is not necessarily the Unix '\n' newline character. 391 */ 392 public void println() 393 { 394 synchronized (lock) 395 { 396 try 397 { 398 write(line_separator, 0, line_separator.length); 399 if (autoflush) 400 out.flush(); 401 } 402 catch (IOException ex) 403 { 404 error = true; 405 } 406 } 407 } 408 409 /** 410 * This methods prints a boolean value to the stream. <code>true</code> 411 * values are printed as "true" and <code>false</code> values are printed 412 * as "false". 413 * 414 * This method prints a line termination sequence after printing the value. 415 * 416 * @param bool The <code>boolean</code> value to print 417 */ 418 public void println(boolean bool) 419 { 420 synchronized (lock) 421 { 422 print(bool); 423 println(); 424 } 425 } 426 427 /** 428 * This method prints an integer to the stream. The value printed is 429 * determined using the <code>String.valueOf()</code> method. 430 * 431 * This method prints a line termination sequence after printing the value. 432 * 433 * @param inum The <code>int</code> value to be printed 434 */ 435 public void println(int inum) 436 { 437 synchronized (lock) 438 { 439 print(inum); 440 println(); 441 } 442 } 443 444 /** 445 * This method prints a long to the stream. The value printed is 446 * determined using the <code>String.valueOf()</code> method. 447 * 448 * This method prints a line termination sequence after printing the value. 449 * 450 * @param lnum The <code>long</code> value to be printed 451 */ 452 public void println(long lnum) 453 { 454 synchronized (lock) 455 { 456 print(lnum); 457 println(); 458 } 459 } 460 461 /** 462 * This method prints a float to the stream. The value printed is 463 * determined using the <code>String.valueOf()</code> method. 464 * 465 * This method prints a line termination sequence after printing the value. 466 * 467 * @param fnum The <code>float</code> value to be printed 468 */ 469 public void println(float fnum) 470 { 471 synchronized (lock) 472 { 473 print(fnum); 474 println(); 475 } 476 } 477 478 /** 479 * This method prints a double to the stream. The value printed is 480 * determined using the <code>String.valueOf()</code> method. 481 * 482 * This method prints a line termination sequence after printing the value. 483 * 484 * @param dnum The <code>double</code> value to be printed 485 */ 486 public void println(double dnum) 487 { 488 synchronized (lock) 489 { 490 print(dnum); 491 println(); 492 } 493 } 494 495 /** 496 * This method prints an <code>Object</code> to the stream. The actual 497 * value printed is determined by calling the <code>String.valueOf()</code> 498 * method. 499 * 500 * This method prints a line termination sequence after printing the value. 501 * 502 * @param obj The <code>Object</code> to print. 503 */ 504 public void println(Object obj) 505 { 506 synchronized (lock) 507 { 508 print(obj); 509 println(); 510 } 511 } 512 513 /** 514 * This method prints a <code>String</code> to the stream. The actual 515 * value printed depends on the system default encoding. 516 * 517 * This method prints a line termination sequence after printing the value. 518 * 519 * @param str The <code>String</code> to print. 520 */ 521 public void println(String str) 522 { 523 synchronized (lock) 524 { 525 print(str); 526 println(); 527 } 528 } 529 530 /** 531 * This method prints a char to the stream. The actual value printed is 532 * determined by the character encoding in use. 533 * 534 * This method prints a line termination sequence after printing the value. 535 * 536 * @param ch The <code>char</code> value to be printed 537 */ 538 public void println(char ch) 539 { 540 synchronized (lock) 541 { 542 print(ch); 543 println(); 544 } 545 } 546 547 /** 548 * This method prints an array of characters to the stream. The actual 549 * value printed depends on the system default encoding. 550 * 551 * This method prints a line termination sequence after printing the value. 552 * 553 * @param charArray The array of characters to print. 554 */ 555 public void println(char[] charArray) 556 { 557 synchronized (lock) 558 { 559 print(charArray); 560 println(); 561 } 562 } 563 564 /** 565 * This method writes a single char to the stream. 566 * 567 * @param ch The char to be written, passed as a int 568 */ 569 public void write(int ch) 570 { 571 try 572 { 573 out.write(ch); 574 } 575 catch (IOException ex) 576 { 577 error = true; 578 } 579 } 580 581 /** 582 * This method writes <code>count</code> chars from the specified array 583 * starting at index <code>offset</code> into the array. 584 * 585 * @param charArray The array of chars to write 586 * @param offset The index into the array to start writing from 587 * @param count The number of chars to write 588 */ 589 public void write(char[] charArray, int offset, int count) 590 { 591 try 592 { 593 out.write(charArray, offset, count); 594 } 595 catch (IOException ex) 596 { 597 error = true; 598 } 599 } 600 601 /** 602 * This method writes <code>count</code> chars from the specified 603 * <code>String</code> to the output starting at character position 604 * <code>offset</code> into the <code>String</code> 605 * 606 * @param str The <code>String</code> to write chars from 607 * @param offset The offset into the <code>String</code> to start writing from 608 * @param count The number of chars to write. 609 */ 610 public void write(String str, int offset, int count) 611 { 612 try 613 { 614 out.write(str, offset, count); 615 } 616 catch (IOException ex) 617 { 618 error = true; 619 } 620 } 621 622 /** 623 * This method write all the chars in the specified array to the output. 624 * 625 * @param charArray The array of characters to write 626 */ 627 public void write(char[] charArray) 628 { 629 write(charArray, 0, charArray.length); 630 } 631 632 /** 633 * This method writes the contents of the specified <code>String</code> 634 * to the underlying stream. 635 * 636 * @param str The <code>String</code> to write 637 */ 638 public void write(String str) 639 { 640 write(str, 0, str.length()); 641 } 642 643 /** @since 1.5 */ 644 public PrintWriter append(char c) 645 { 646 write(c); 647 return this; 648 } 649 650 /** @since 1.5 */ 651 public PrintWriter append(CharSequence cs) 652 { 653 write(cs == null ? "null" : cs.toString()); 654 return this; 655 } 656 657 /** @since 1.5 */ 658 public PrintWriter append(CharSequence cs, int start, int end) 659 { 660 write(cs == null ? "null" : cs.subSequence(start, end).toString()); 661 return this; 662 } 663 664 /** @since 1.5 */ 665 public PrintWriter printf(String format, Object... args) 666 { 667 return format(format, args); 668 } 669 670 /** @since 1.5 */ 671 public PrintWriter printf(Locale locale, String format, Object... args) 672 { 673 return format(locale, format, args); 674 } 675 676 /** @since 1.5 */ 677 public PrintWriter format(String format, Object... args) 678 { 679 return format(Locale.getDefault(), format, args); 680 } 681 682 /** @since 1.5 */ 683 public PrintWriter format(Locale locale, String format, Object... args) 684 { 685 Formatter f = new Formatter(this, locale); 686 f.format(format, args); 687 return this; 688 } 689}