Package groovy.util

# Class CharsetToolkit

java.lang.Object
groovy.util.CharsetToolkit

public class CharsetToolkit extends Object
Utility class to guess the encoding of a given text file.

Unicode files encoded in UTF-16 (low or big endian) or UTF-8 files with a Byte Order Marker are correctly discovered. For UTF-8 files with no BOM, if the buffer is wide enough, the charset should also be discovered.

A byte buffer of 4KB is used to be able to guess the encoding.

Usage:

     CharsetToolkit toolkit = new CharsetToolkit(file);

     // guess the encoding
     Charset guessedCharset = toolkit.getCharset();

     // create a reader with the correct charset
     BufferedReader reader = toolkit.getReader();

     // read the file content
     String line;
     while ((line = br.readLine())!= null)
     {
         System.out.println(line);
     }

Author:
  Guillaume Laforge

## Constructor Summary

Constructors
Constructor
Description
`CharsetToolkit(File file)`
Constructor of the `CharsetToolkit` utility class.

## Method Summary

Modifier and Type
Method
Description
`static Charset[]`
`getAvailableCharsets()`
Retrieves all the available `Charset`s on the platform, among which the default `charset`.
`Charset`
`getCharset()`
`Charset`
`getDefaultCharset()`
Retrieves the default Charset
`static Charset`
`getDefaultSystemCharset()`
Retrieve the default charset of the system.
`boolean`
`getEnforce8Bit()`
Gets the enforce8Bit flag, in case we do not want to ever get a US-ASCII encoding.
`BufferedReader`
`getReader()`
Gets a `BufferedReader` (indeed a `LineNumberReader`) from the `File` specified in the constructor of `CharsetToolkit` using the charset discovered or the default charset if an 8-bit `Charset` is encountered.
`boolean`
`hasUTF16BEBom()`
Has a Byte Order Marker for UTF-16 Big Endian (utf-16 and ucs-2).
`boolean`
`hasUTF16LEBom()`
Has a Byte Order Marker for UTF-16 Low Endian (ucs-2le, ucs-4le, and ucs-16le).
`boolean`
`hasUTF8Bom()`
Has a Byte Order Marker for UTF-8 (Used by Microsoft's Notepad and other editors).
`void`
`setDefaultCharset(Charset defaultCharset)`
Defines the default `Charset` used in case the buffer represents an 8-bit `Charset`.
`void`
`setEnforce8Bit(boolean enforce)`
If US-ASCII is recognized, enforce to return the default encoding, rather than US-ASCII.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### CharsetToolkit

public CharsetToolkit(File file) throws IOException
Constructor of the `CharsetToolkit` utility class.

Parameters:
  `file` - of which we want to know the encoding.
Throws:
  `IOException`

## Method Details

### setDefaultCharset

public void setDefaultCharset(Charset defaultCharset)
Defines the default `Charset` used in case the buffer represents an 8-bit `Charset`.

Parameters:
  `defaultCharset` - the default `Charset` to be returned if an 8-bit `Charset` is encountered.

### getCharset

public Charset getCharset()

### setEnforce8Bit

public void setEnforce8Bit(boolean enforce)
If US-ASCII is recognized, enforce to return the default encoding, rather than US-ASCII. It might be a file without any special character in the range 128-255, but that may be or become a file encoded with the default `charset` rather than US-ASCII.

Parameters:
  `enforce` - a boolean specifying the use or not of US-ASCII.

### getEnforce8Bit

public boolean getEnforce8Bit()
Gets the enforce8Bit flag, in case we do not want to ever get a US-ASCII encoding.

Returns:
  a boolean representing the flag of use of US-ASCII.

### getDefaultCharset

public Charset getDefaultCharset()
Retrieves the default Charset

### getDefaultSystemCharset

public static Charset getDefaultSystemCharset()
Retrieve the default charset of the system.

Returns:
  the default `Charset`.

### hasUTF8Bom

public boolean hasUTF8Bom()
Has a Byte Order Marker for UTF-8 (Used by Microsoft's Notepad and other editors).

Returns:
  true if the buffer has a BOM for UTF8.

### hasUTF16LEBom

public boolean hasUTF16LEBom()
Has a Byte Order Marker for UTF-16 Low Endian (ucs-2le, ucs-4le, and ucs-16le).

Returns:
  true if the buffer has a BOM for UTF-16 Low Endian.

### hasUTF16BEBom

public boolean hasUTF16BEBom()
Has a Byte Order Marker for UTF-16 Big Endian (utf-16 and ucs-2).

Returns:
  true if the buffer has a BOM for UTF-16 Big Endian.

### getReader

public BufferedReader getReader() throws FileNotFoundException
Gets a `BufferedReader` (indeed a `LineNumberReader`) from the `File` specified in the constructor of `CharsetToolkit` using the charset discovered or the default charset if an 8-bit `Charset` is encountered.

Returns:
  a `BufferedReader`
Throws:
  `FileNotFoundException` - if the file is not found.

### getAvailableCharsets

public static Charset[] getAvailableCharsets()
Retrieves all the available `Charset`s on the platform, among which the default `charset`.

Returns:
  an array of `Charset`s.