TextIO

java.lang.Object
- net.algart.lib.TextIO

Direct Known Subclasses:

TextIO.ForCharset, TextIO.SystemDefault
```
public abstract class TextIO
extends java.lang.Object
```
A tool for reading and writing text files. Different instances of this class use different encoding ("UTF-8", "ASCII", "UnicodeBig", etc.) To write or read the text file in the given encoding, you may use one of the constants declared in this class (such as ASCII) or create a new instance of the TextIO.ForCharset inheritor by TextIO.ForCharset.getInstance(String) call.
Methods of this class throw NullPointerException if one of the arguments is null.

Version:

1.0

Author:

Daniel Alievsky

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`TextIO.ForCharset` An implementation of `TextIO` class that writes and reads text files in encodings specified by their names (as the second argument of `InputStreamReader` and `OutputStreamWriter` constructors).
`static class`	`TextIO.SystemDefault` An implementation of `TextIO` class that writes and reads text files in the current system-dependent encoding.

Field Summary

Fields
Modifier and Type	Field and Description
`static TextIO.ForCharset`	`ASCII` This `TextIO` instance writes and reads text files in the standard 7-bit "ASCII" encoding.
`static TextIO.ForCharset`	`CP1252` This `TextIO` instance writes and reads text files in the standard 8-bit "Cp1252" encoding.
`static TextIO.ForCharset`	`ISO8859_1` This `TextIO` instance writes and reads text files in the standard 8-bit "ISO8859_1" encoding.
`static TextIO.SystemDefault`	`SYSTEM_DEFAULT` This `TextIO` instance writes and reads text files in the current system-dependent encoding.
`static TextIO.ForCharset`	`UNICODE_BIG` This `TextIO` instance writes and reads text files in the standard 16-bit "UnicodeBig" encoding.
`static TextIO.ForCharset`	`UNICODE_BIG_UNMARKED` This `TextIO` instance writes and reads text files in the standard 16-bit "UnicodeBigUnmarked" encoding.
`static TextIO.ForCharset`	`UNICODE_LITTLE` This `TextIO` instance writes and reads text files in the standard 16-bit "UnicodeLittle" encoding.
`static TextIO.ForCharset`	`UNICODE_LITTLE_UNMARKED` This `TextIO` instance writes and reads text files in the standard 16-bit "UnicodeLittleUnmarked" encoding.
`static TextIO.ForCharset`	`UTF16` This `TextIO` instance writes and reads text files in the standard 16-bit "UTF-16" encoding.
`static TextIO.ForCharset`	`UTF8` This `TextIO` instance writes and reads text files in the standard "UTF-8" encoding.

Method Summary

Methods
Modifier and Type	Method and Description
`java.lang.String`	`read(java.io.File file)` Reads the full content of the given text file and returns it as a `String`.
`java.lang.String`	`read(java.io.InputStream inputStream, boolean closeStream)` Reads the text file from the current position of the input stream until the end of this stream and returns it as a `String`.
`char[]`	`readChars(java.io.File file)` Reads the full content of the given text file and returns it as a `char[]`.
`char[]`	`readChars(java.io.InputStream inputStream, boolean closeStream)` Reads the text file from the current position of the input stream until the end of this stream and returns it as a `char[]`.
`void`	`write(java.io.File file, java.lang.String data)` Saves the text passed in the `data` argument in the given text file.
`void`	`writeChars(java.io.File file, char[] data)` Saves the text passed in the `data` argument in the given text file.
`void`	`writeCharsOrDelete(java.io.File file, char[] data)` If `data == null`, deletes `file`; in other case, equivalent to `writeChars(File, char[])`.
`void`	`writeOrDelete(java.io.File file, java.lang.String data)` If `data == null`, deletes `file`; in other case, equivalent to `write(File, String)`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SYSTEM_DEFAULT
```
public static final TextIO.SystemDefault SYSTEM_DEFAULT
```
    This TextIO instance writes and reads text files in the current system-dependent encoding.
  - ASCII
```
public static final TextIO.ForCharset ASCII
```
    This TextIO instance writes and reads text files in the standard 7-bit "ASCII" encoding.
  - CP1252
```
public static final TextIO.ForCharset CP1252
```
    This TextIO instance writes and reads text files in the standard 8-bit "Cp1252" encoding.
  - ISO8859_1
```
public static final TextIO.ForCharset ISO8859_1
```
    This TextIO instance writes and reads text files in the standard 8-bit "ISO8859_1" encoding.
  - UNICODE_BIG
```
public static final TextIO.ForCharset UNICODE_BIG
```
    This TextIO instance writes and reads text files in the standard 16-bit "UnicodeBig" encoding. In this encoding:
    - every character is written as its 16-bit Unicode number: high bytes (bits 8-15) of all characters are stored at the offsets 2*k (k=1,2,...) from the beginning of the file, low bytes (bits 0-7) are stored at the offsets 2*k+1 (k=1,2,...) after bits 8-15;
    - first 16 bits of the text file contain 0xFEFF prefix (0xFE is the first byte of the file, 0xFF is the second).
  - UNICODE_BIG_UNMARKED
```
public static final TextIO.ForCharset UNICODE_BIG_UNMARKED
```
    This TextIO instance writes and reads text files in the standard 16-bit "UnicodeBigUnmarked" encoding. In this encoding:
    - every character is written as its 16-bit Unicode number: high bytes (bits 8-15) of all characters are stored at the offsets 2*k (k=0,1,...) from the beginning of the file, low bytes (bits 0-7) are stored at the offsets 2*k+1 (k=0,1,...) after bits 8-15;
    - start file prefix is not used, unlike UNICODE_BIG encoding.
  - UNICODE_LITTLE
```
public static final TextIO.ForCharset UNICODE_LITTLE
```
    This TextIO instance writes and reads text files in the standard 16-bit "UnicodeLittle" encoding. In this encoding:
    - every character is written as its 16-bit Unicode number: low bytes (bits 0-7) of all characters are stored at the offsets 2*k (k=1,2,...) from the beginning of the file, high bytes (bits 8-15) are stored at the offsets 2*k+1 (k=1,2,...) (such an order is usual for Intel processors);
    - first 16 bits of the text file contain 0xFEFF prefix (0xFF is the first byte of the file, 0xFE is the second, unlike UNICODE_BIG).
  - UNICODE_LITTLE_UNMARKED
```
public static final TextIO.ForCharset UNICODE_LITTLE_UNMARKED
```
    This TextIO instance writes and reads text files in the standard 16-bit "UnicodeLittleUnmarked" encoding. In this encoding:
    - every character is written as its 16-bit Unicode number: low bytes (bits 0-7) of all characters are stored at the offsets 2*k (k=0,1,...) from the beginning of the file, high bytes (bits 8-15) are stored at the offsets 2*k+1 (k=0,1,...) (such an order is usual for Intel processors);
    - start file prefix is not used, unlike UNICODE_LITTLE encoding.
  - UTF16
```
public static final TextIO.ForCharset UTF16
```
    This TextIO instance writes and reads text files in the standard 16-bit "UTF-16" encoding. In this encoding, unlike UNICODE_BIG and UNICODE_LITTLE, an order of writing bytes in every character can depend on the used operating system. The start 16-bit prefix 0xFEFF is always written in the text file. The read methods use this prefix to determine the order of bytes: if the first byte is 0xFE, it is "big-endian" order (as in UNICODE_BIG), if the first byte is 0xFF, it is "little-endian" order (as in UNICODE_LITTLE).
  - UTF8
```
public static final TextIO.ForCharset UTF8
```
    This TextIO instance writes and reads text files in the standard "UTF-8" encoding. It is the best variant for most needs.
- Method Detail
  - read
```
public final java.lang.String read(java.io.InputStream inputStream,
                    boolean closeStream)
                            throws java.io.IOException
```
    Reads the text file from the current position of the input stream until the end of this stream and returns it as a String. Useful for reading text data stored in resources when the Class.getResourceAsStream method is used to access such resources.
    
    Parameters:
    inputStream - the input stream (will be read until its end)
    closeStream - if true, the input stream will be closed for sure before ending this method
    
    Returns:
    the full text stored in the input stream from the current position until the end of the stream
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    See Also:
    readChars(InputStream, boolean)
  - readChars
```
public final char[] readChars(java.io.InputStream inputStream,
               boolean closeStream)
                       throws java.io.IOException
```
    Reads the text file from the current position of the input stream until the end of this stream and returns it as a char[]. Useful for reading text data stored in resources when the Class.getResourceAsStream method is used to access such resources.
    
    Parameters:
    inputStream - the input stream (will be read until its end)
    closeStream - if true, the input stream will be closed for sure before ending this method
    
    Returns:
    the full text stored in the input stream from the current position until the end of the stream
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    See Also:
    read(InputStream, boolean)
  - read
```
public final java.lang.String read(java.io.File file)
                            throws java.io.IOException
```
    Reads the full content of the given text file and returns it as a String.
    
    Parameters:
    file - the file to be read
    
    Returns:
    the full text content of the given file
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    See Also:
    readChars(File)
  - readChars
```
public final char[] readChars(java.io.File file)
                       throws java.io.IOException
```
    Reads the full content of the given text file and returns it as a char[].
    
    Parameters:
    file - the file to be read
    
    Returns:
    the full text content of the given file
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    See Also:
    read(File)
  - write
```
public final void write(java.io.File file,
         java.lang.String data)
                 throws java.io.IOException
```
    Saves the text passed in the data argument in the given text file. The file is fully rewritten and will contain this text only. In a case of I/O errors, the file will be attempted to be deleted.
    
    Parameters:
    file - the file to be saved
    data - the text saved in the file (String object)
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    See Also:
    writeChars(File, char[])
  - writeChars
```
public final void writeChars(java.io.File file,
              char[] data)
                      throws java.io.IOException
```
    Saves the text passed in the data argument in the given text file. The file is fully rewritten and will contain this text only. In a case of I/O errors, the file will be attempted to be deleted.
    
    Parameters:
    file - the file to be saved
    data - the text saved in the file (array of characters)
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    See Also:
    write(File, String)
  - writeOrDelete
```
public final void writeOrDelete(java.io.File file,
                 java.lang.String data)
                         throws java.io.IOException
```
    If data == null, deletes file; in other case, equivalent to write(File, String).
    
    Parameters:
    file - the file to be saved
    data - the bytes saved in the file
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
  - writeCharsOrDelete
```
public final void writeCharsOrDelete(java.io.File file,
                      char[] data)
                              throws java.io.IOException
```
    If data == null, deletes file; in other case, equivalent to writeChars(File, char[]).
    
    Parameters:
    file - the file to be saved
    data - the bytes saved in the file
    
    Throws:
    
    java.io.IOException - if an I/O error occurs

Class TextIO

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SYSTEM_DEFAULT

ASCII

CP1252

ISO8859_1

UNICODE_BIG

UNICODE_BIG_UNMARKED

UNICODE_LITTLE

UNICODE_LITTLE_UNMARKED

UTF16

UTF8

Method Detail

read

readChars

read

readChars

write

writeChars

writeOrDelete

writeCharsOrDelete