CharsetEncoder (Java Platform SE 8 )

java.lang.Object
- java.nio.charset.CharsetEncoder

```
public abstract class CharsetEncoder
extends Object
```
一个引擎，可以将一个序列的十六位Unicode字符转换为一个特定的字符一个字节序列。
输入字符序列是在一个字符缓冲区或一系列这样的缓冲区中提供的。输出字节序列被写入到一个字节缓冲区或一系列这样的缓冲区。一个编码器应该做如下的方法调用序列，以下简称编码操作：
1. 复位编码器通过reset方法，除非它没有被使用过；
2. 调用encode方法零次或更多次，只要额外的输入可能是可用的，通过false为endOfInput论点和填充输入缓冲和冲洗之间的调用的输出缓冲器；
3. encode方法调用的最后一次，为endOfInput参数传递true；然后
4. 调用flush方法使编码器可以将任何内部状态到输出缓冲区。
每次调用的 encode方法可以将尽可能多的字符从输入缓冲区中的字节，写入到输出缓冲区。的 encode方法返回时更多的投入是必须的，当没有在输出缓冲区足够的空间，或当一个编码错误已经发生。在每一种情况下， CoderResult对象返回描述终止原因。调用者可以检查该对象和填充输入缓冲，刷新输出缓冲区，或试图从一个编码错误，恢复适当的，并再次尝试。
有两种类型的编码错误。如果输入字符序列不是一个合法的十六位Unicode序列，然后输入是畸形。如果输入字符序列是合法的但不能被映射到一个有效的字节序列在给出一个无法映射的字符已经遇到字符集。

有一个编码错误的处理取决于所要求的那种错误的行动，这是由其CodingErrorAction类的一个实例描述。可能的错误行为是ignore错误输入，report错误的调用通过返回的CoderResult对象，或replace错误输入的替换字节数组的当前值。替换最初设置的编码器的默认置换，通常（但不总是）的初始值 { (byte)'?' }；它的值可以通过replaceWith方法改变。

对于错误的输入，无法映射的字符错误的默认动作是report他们。畸形的输入误差的作用可能是通过onMalformedInput方法改变的行动；无法映射的字符可以通过onUnmappableCharacter方法改变。

这个类的设计是为了处理编码过程中的许多细节，包括错误操作的实现。对于一个特定的字符编码，它是这个类的一个具体子类，只需要实现抽象encodeLoop方法，它封装了基本编码环。一类维护内部状态，此外，覆盖implFlush和implReset方法。

这个类的实例不安全使用多个并发线程。
从以下版本开始：

一点四

另请参见：

ByteBuffer， CharBuffer， Charset， CharsetDecoder

构造方法摘要

构造方法
Modifier	Constructor and Description
`protected`	`CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)` 初始化一个新的编码器。
`protected`	`CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)` 初始化一个新的编码器。

方法摘要

所有方法接口方法抽象方法具体的方法
Modifier and Type	Method and Description
`float`	`averageBytesPerChar()` 返回将为每个输入字符产生的字节数的平均值。
`boolean`	`canEncode(char c)` 告诉是否该编码器可以对给定的字符进行编码。
`boolean`	`canEncode(CharSequence cs)` 告诉是否该编码器可以对给定的字符序列进行编码。
`Charset`	`charset()` 返回创建此编码器的字符集。
`ByteBuffer`	`encode(CharBuffer in)` 将单个输入字符缓冲区的其余内容编码成新分配的字节缓冲区的方便方法。
`CoderResult`	`encode(CharBuffer in, ByteBuffer out, boolean endOfInput)` 从给定的输入缓冲区中尽可能多的字符编码，将结果写入给定的输出缓冲区中。
`protected abstract CoderResult`	`encodeLoop(CharBuffer in, ByteBuffer out)` 将一个或多个字符编码成一个或多个字节。
`CoderResult`	`flush(ByteBuffer out)` 刷新编码器。
`protected CoderResult`	`implFlush(ByteBuffer out)` 刷新编码器。
`protected void`	`implOnMalformedInput(CodingErrorAction newAction)` 报道改变该编码器的格式不正确的输入动作。
`protected void`	`implOnUnmappableCharacter(CodingErrorAction newAction)` 报道改变这个编码器无法映射的字符行动。
`protected void`	`implReplaceWith(byte[] newReplacement)` 报告这个编码器的替换值的变化。
`protected void`	`implReset()` 重置该编码器，清除任何字符集的特定的内部状态。
`boolean`	`isLegalReplacement(byte[] repl)` 告诉是否给定的字节数组是这个编码器的一个合法的替换值。
`CodingErrorAction`	`malformedInputAction()` 返回错误的输入错误该编码器的当前动作。
`float`	`maxBytesPerChar()` 返回将为输入的每个字符产生的最大字节数。
`CharsetEncoder`	`onMalformedInput(CodingErrorAction newAction)` 该编码器的行动改变畸形的输入错误。
`CharsetEncoder`	`onUnmappableCharacter(CodingErrorAction newAction)` 改变这种编码器的行动无法映射的字符错误。
`byte[]`	`replacement()` 返回此编码器的替换值。
`CharsetEncoder`	`replaceWith(byte[] newReplacement)` 改变此编码器的替换值。
`CharsetEncoder`	`reset()` 重置该编码器，清除任何内部状态。
`CodingErrorAction`	`unmappableCharacterAction()` 返回无法映射的字符错误该编码器的当前动作。

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

- Constructor Detail
  - CharsetEncoder
```
protected CharsetEncoder(Charset cs,
                         float averageBytesPerChar,
                         float maxBytesPerChar,
                         byte[] replacement)
```
    初始化一个新的编码器。新的编码器将有每个字符的每个字符和替换值的字节数。
    
    参数
    
    cs -创建此编码字符集
    
    averageBytesPerChar -正浮点数表示的字节，将为每个输入字符的预期数量
    
    maxBytesPerChar -正浮点数表示的字节，将为每个输入字符的最大数量
    
    replacement -初始置换；不得 null，必须有非零的长度，最长不得超过maxbytesperchar，必须 legal
    
    异常
    
    IllegalArgumentException -如果在参数的前提条件不成立
  - CharsetEncoder
```
protected CharsetEncoder(Charset cs,
                         float averageBytesPerChar,
                         float maxBytesPerChar)
```
    初始化一个新的编码器。新的编码器具有给定的字节字符值及其置换将字节数组 { (byte)'?' }。
    
    参数
    
    cs -创建此编码字符集
    
    averageBytesPerChar -正浮点数表示的字节，将为每个输入字符的预期数量
    
    maxBytesPerChar -正浮点数表示的字节，将为每个输入字符的最大数量
    
    异常
    
    IllegalArgumentException -如果在参数的前提条件不成立
- 方法详细信息
  - charset
```
public final Charset charset()
```
    返回创建此编码器的字符集。
    
    结果
    
    这个编码的字符集
  - replacement
```
public final byte[] replacement()
```
    返回此编码器的替换值。
    
    结果
    
    该编码器的更换，这是从来没有 null不会是空的
  - replaceWith
```
public final CharsetEncoder replaceWith(byte[] newReplacement)
```
    改变此编码器的替换值。
    此方法调用implReplaceWith方法，通过新的替换，在检验新的替换是可以接受的。
    
    参数
    
    newReplacement的重置价值新更换的；不能 null，必须有非零的长度不能大于价值的 maxBytesPerChar方法返回的时间，必须 legal
    
    结果
    
    该编码器
    
    异常
    
    IllegalArgumentException -如果在参数的前提条件不成立
  - implReplaceWith
```
protected void implReplaceWith(byte[] newReplacement)
```
    报告这个编码器的替换值的变化。
    这种方法的默认实现不做任何事。这种方法应该由编码器，需要更换的变化通知重写。
    
    参数
    
    newReplacement -重置价值
  - isLegalReplacement
```
public boolean isLegalReplacement(byte[] repl)
```
    告诉是否给定的字节数组是这个编码器的一个合法的替换值。
    如果更换是合法的，只有当它是这个编码器的字符一个字节的法律序列；即，它必须能够解码替换为一个或多个十六位字符。
    
    此方法的默认实现是不是很有效；它一般应以提高性能。
    
    参数
    
    repl -被测试的字节数组
    
    结果
    
    true如果，仅仅是如果，给定的字节数组是这一法律的替换值编码器
  - malformedInputAction
```
public CodingErrorAction malformedInputAction()
```
    返回错误的输入错误该编码器的当前动作。
    
    结果
    
    当前畸形的输入动作，这是从来没有 null
  - onMalformedInput
```
public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)
```
    该编码器的行动改变畸形的输入错误。
    此方法调用implOnMalformedInput方法，通过新的行动。
    
    参数
    
    newAction -新的行动；不能 null
    
    结果
    
    该编码器
    
    异常
    
    IllegalArgumentException -如果在参数的前提不成立
  - implOnMalformedInput
```
protected void implOnMalformedInput(CodingErrorAction newAction)
```
    报道改变该编码器的格式不正确的输入动作。
    这种方法的默认实现不做任何事。这种方法应该由编码器需要的格式不正确的输入动作变化通知重写。
    
    参数
    
    newAction -新的行动
  - unmappableCharacterAction
```
public CodingErrorAction unmappableCharacterAction()
```
    返回无法映射的字符错误该编码器的当前动作。
    
    结果
    
    当前无法映射的字符，这是从来没有 null
  - onUnmappableCharacter
```
public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)
```
    改变这种编码器的行动无法映射的字符错误。
    此方法调用implOnUnmappableCharacter方法，通过新的行动。
    
    参数
    
    newAction -新的行动；不能 null
    
    结果
    
    该编码器
    
    异常
    
    IllegalArgumentException -如果在参数的前提不成立
  - implOnUnmappableCharacter
```
protected void implOnUnmappableCharacter(CodingErrorAction newAction)
```
    报道改变这个编码器无法映射的字符行动。
    这种方法的默认实现不做任何事。这种方法应该由编码器需要到无法映射的字符的动作变化通知重写。
    
    参数
    
    newAction -新的行动
  - averageBytesPerChar
```
public final float averageBytesPerChar()
```
    返回将为每个输入字符产生的字节数的平均值。此启发式值可用于估计给定输入序列所需的输出缓冲区的大小。
    
    结果
    
    按输入的字符产生的平均字节数
  - maxBytesPerChar
```
public final float maxBytesPerChar()
```
    返回将为输入的每个字符产生的最大字节数。此值可用于计算给定输入序列所需的输出缓冲区的最坏情况大小。
    
    结果
    
    将按输入的字符产生的最大字节数
  - encode
```
public final CoderResult encode(CharBuffer in,
                                ByteBuffer out,
                                boolean endOfInput)
```
    从给定的输入缓冲区中尽可能多的字符编码，将结果写入给定的输出缓冲区中。
    缓冲区被读取，并写入，开始在他们目前的位置。在最in.remaining()汉字会读会写在最out.remaining()字节。缓冲区的位置将是先进的，以反映读取和写入字节的字符，但他们的标志和限制将不会被修改。
    
    除了从输入缓冲区和字节写入输出缓冲区读取字符，该方法返回一个CoderResult对象描述其终止的原因：
    - CoderResult.UNDERFLOW显示尽可能多的输入缓冲器已编码。如果没有进一步的输入，然后调用程序，可以进行下一步的encoding operation。否则该调用的方法应该是再进一步的输入。
    - CoderResult.OVERFLOW表明输出缓冲区的字符编码再没有足够的空间。这种方法应该被调用了输出缓冲区，更remaining字节。这通常是通过耗尽输出缓冲区中的任何编码字节来完成的。
    - 一个malformed-input结果表明检测到错误的输入错误。在输入缓冲区中的字符开始的畸形（可能是递增的）位置；畸形的字符数可以通过调用对象的length法测定结果。如果该编码器的malformed action是CodingErrorAction.REPORT本案适用；否则，错误的输入将被忽略或更换，按要求。
    - 一个unmappable-character结果表明检测到一个无法映射的字符错误。字符编码无法映射的字符在输入缓冲区的开始位置（可能是递增的）；这样的字符数可以通过调用对象的length法测定结果。如果该编码器的unmappable action是CodingErrorAction.REPORT本案适用；否则无法映射的字符将被忽略，或更换，按要求。
    在任何情况下，如果这个方法被重新调用在同一编码操作后应注意保留剩余的输入缓冲区中以便他们可以下次调用任何字符。
    的endOfInput参数建议此方法的调用者是否可以提供进一步的输入超出包含在给定的输入缓冲器。如果有可能提供额外的输入，然后调用程序应该通过false这个参数；如果不可能提供进一步的输入，然后调用应该通过true。这是不是错误的，事实上这是很常见的，在一个调用通过false后来发现没有进一步的输入实际上是可用的。然而，这是至关重要的，，，在一系列的调用这个方法的调用都通过true最终使剩余的未编码的输入将被视为畸形。
    
    该方法通过调用encodeLoop方法，解释其结果，处理错误条件，并reinvoking这是必要的。
    参数
    
    in -输入字符缓冲区
    
    out -输出字节缓冲区
    
    endOfInput - true如果，仅仅如果调用者可以提供任何额外的输入的字符超过给定的缓冲区
    
    结果
    
    描述终止的原因的编码器结果对象
    
    异常
    
    IllegalStateException如果编码操作已在进行中，前一步是调用的方法也不 reset，这种方法对 endOfInput参数值 false，也没有这种方法对 endOfInput参数值 true但返回值指示一个不完整的编码操作
    
    如果 CoderMalfunctionError的encodeloop方法调用抛出异常
  - flush
```
public final CoderResult flush(ByteBuffer out)
```
    刷新编码器。
    一些编码器保持内部状态，并可能需要写一些最终字节的输出缓冲区一旦整体输入序列已被读取。
    
    任何额外的输出写入到输出缓冲区开始在其当前位置。在最out.remaining()将被写入字节。缓冲区的位置将适当提前，但它的标记和限制将不会被修改。
    
    如果此方法成功完成，则返回CoderResult.UNDERFLOW。如果在输出缓冲区空间不足则返回CoderResult.OVERFLOW。如果发生这种情况，那么这个方法必须调用一次，与一个输出缓冲区，有更多的空间，为了完成当前的encoding operation。
    
    如果这个编码器已经被刷新，那么调用这个方法没有任何效果。
    
    此方法调用implFlush方法来执行实际的冲洗操作。
    
    参数
    
    out -输出字节缓冲区
    
    结果
    
    编码器的结果对象，要么 CoderResult.UNDERFLOW或 CoderResult.OVERFLOW
    
    异常
    
    IllegalStateException -如果当前编码操作之前的步骤被调用的方法不 flush的三参数 encode方法为 endOfInput参数值 true
  - implFlush
```
protected CoderResult implFlush(ByteBuffer out)
```
    刷新编码器。
    这种方法的默认实现不执行任何操作，并且总是返回CoderResult.UNDERFLOW。这种方法应该由编码器可能需要写最后的字节输出缓冲区一旦整个输入序列已读重写。
    
    参数
    
    out -输出字节缓冲区
    
    结果
    
    编码器的结果对象，要么 CoderResult.UNDERFLOW或 CoderResult.OVERFLOW
  - reset
```
public final CharsetEncoder reset()
```
    重置该编码器，清除任何内部状态。
    这个方式将字符集的独立国家并调用implReset方法以执行任何字符集的特定的复位动作。
    
    结果
    
    该编码器
  - implReset
```
protected void implReset()
```
    重置该编码器，清除任何字符集的特定的内部状态。
    这种方法的默认实现不做任何事。这种方法应该通过保持内部状态编码器重写。
  - encodeLoop
```
protected abstract CoderResult encodeLoop(CharBuffer in,
                                          ByteBuffer out)
```
    将一个或多个字符编码成一个或多个字节。
    这种方法封装的基本编码环，编码尽可能多的字符，直到它运行的输入，跑出房间在输出缓冲区，或者遇到一个编码错误。该方法由encode方法调用时，处理结果解释和错误恢复。
    
    缓冲区被读取，并写入，开始在他们目前的位置。在最in.remaining()字符将被读取，并在最out.remaining()将被写入字节。缓冲区的位置将是先进的，以反映读取和写入字节的字符，但他们的标志和限制将不会被修改。
    
    此方法返回一个CoderResult对象描述其终止的原因，以同样的方式为encode方法。大多数这种方法实现将处理由encode方法返回适当的结果对象编码错误的解释。一个优化的实现可能会检查相关的错误动作，并实现行动本身。
    
    此方法的实现可以执行任意的先行返回CoderResult.UNDERFLOW直到它接收到足够的输入。
    
    参数
    
    in -输入字符缓冲区
    
    out -输出字节缓冲区
    
    结果
    
    描述终止的原因的编码器结果对象
  - encode
```
public final ByteBuffer encode(CharBuffer in)
                        throws CharacterCodingException
```
    将单个输入字符缓冲区的其余内容编码成新分配的字节缓冲区的方便方法。
    该方法实现了一个完整的encoding operation；即它重置该编码器，然后它编码的字符在字符缓冲区，最后刷新编码器。因此，如果一个编码操作已经在进行中，则不调用此方法。
    
    参数
    
    in -输入字符缓冲区
    
    结果
    
    一种新分配的字节缓冲器，包含编码操作的结果。缓冲区的位置将为零，它的限制将按照最后一个字节写的。
    
    异常
    
    IllegalStateException如果编码操作已在进行中
    
    MalformedInputException如果字符序列从输入缓冲区中的当前位置是不是一个合法的十六位Unicode序列和当前畸形的输入动作 CodingErrorAction.REPORT
    
    UnmappableCharacterException如果字符序列从输入缓冲区中的当前位置不能映射到等效字节序列，目前无法映射的字符的作用是 CodingErrorAction.REPORT
    
    CharacterCodingException
  - canEncode
```
public boolean canEncode(char c)
```
    告诉是否该编码器可以对给定的字符进行编码。
    如果给定的字符是一个替代性方法返回false；这样的人物可以解释他们只有会员一个代理其次是低代理项。的canEncode(CharSequence)方法可以用来测试一个字符序列是否可以编码。
    
    这种方法可以修改该编码器的状态；它不应该被调用，如果一个encoding operation已经在进步。
    
    此方法的默认实现是不是很有效；它一般应以提高性能。
    
    参数
    
    c -给定的字符
    
    结果
    
    true如果，如果，该编码器编码的字符
    
    异常
    
    IllegalStateException如果编码操作已在进行中
  - canEncode
```
public boolean canEncode(CharSequence cs)
```
    告诉是否该编码器可以对给定的字符序列进行编码。
    如果这个方法返回一个特定的字符序列，然后false更多信息关于为什么序列不能被编码可以通过执行一个完整的encoding operation获得。
    
    此方法可以修改该编码器的状态；因此，如果一个编码操作已经在进行中，它不应该被调用。
    
    此方法的默认实现是不是很有效；它一般应以提高性能。
    
    参数
    
    cs -给定的字符序列
    
    结果
    
    true如果，如果，该编码器编码的字符而不抛出任何异常和不执行任何的替代品
    
    异常
    
    IllegalStateException如果编码操作已在进行中

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.

Class CharsetEncoder

构造方法摘要

方法摘要

Methods inherited from class java.lang.Object

Constructor Detail

CharsetEncoder

CharsetEncoder

方法详细信息

charset

replacement

replaceWith

implReplaceWith

isLegalReplacement

malformedInputAction

onMalformedInput

implOnMalformedInput

unmappableCharacterAction

onUnmappableCharacter

implOnUnmappableCharacter

averageBytesPerChar

maxBytesPerChar

encode

flush

implFlush

reset

implReset

encodeLoop

encode

canEncode

canEncode