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方法，通过true的endOfInput参数; 接着
4. 调用flush方法，使编码器可以将任何内部状态刷新到输出缓冲区。
encode方法的每次调用都将从输入缓冲区编码尽可能多的字符，将生成的字节写入输出缓冲区。当需要更多输入时，当输出缓冲区中没有足够的空间或发生编码错误时， encode方法返回。在每种情况下，返回一个CoderResult对象来描述终止的原因。调用者可以检查此对象并填写输入缓冲区，刷新输出缓冲区，或尝试从编码错误中恢复，并重试。
有两种一般类型的编码错误。如果输入字符序列不是合法的16位Unicode序列，那么输入被认为是格式错误的 。如果输入字符序列是合法的，但不能映射到给定字符集中的有效字节序列， 则会遇到不可映射的字符。

如何处理编码错误取决于对该类型的错误所请求的操作，由CodingErrorAction类的实例描述。可能的错误动作是ignore错误的输入， report的错误通过返回的CoderResult对象给调用者，或replace错误的输入与替换字节数组的当前值。最初将替换设置为编码器的默认替换，通常（但不总是）初始值为{ (byte)'?' } ; 其值可以通过replaceWith方法更改。

对于错误输入和不可映射的字符错误的默认操作是report他们。畸形输入错误动作可以通过onMalformedInput方法更改; 可以通过onUnmappableCharacter方法更改不可映射的字符动作。

该类旨在处理编码过程的许多细节，包括执行错误操作。特定字符集的编码器是该类的具体子类，仅需实现封装基本编码循环的抽象encodeLoop方法。维护内部状态的子类应另外覆盖implFlush和implReset方法。

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

1.4

另请参见：

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

- 构造方法详细信息
  - 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)
```
    告知给定的字节数组是否是该编码器的合法替换值。
    如果并且只有在编码器的字符集中是一个合法的字节序列，则替换是合法的; 也就是说，必须可以将替换解码为一个或多个16位Unicode字符。
    
    该方法的默认实现不是很有效; 通常应该覆盖以提高性能。
    
    参数
    
    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字节的输出缓冲区来调用此方法。这通常通过从输出缓冲器中排出任何编码字节来完成。
    - A malformed-input结果表示已检测到错误输入错误。格式错误的字符从输入缓冲区（可能增加）的位置开始; 可以通过调用结果对象的length方法来确定格式错误的字符数。这种情况只适用于当malformed action这个编码器是CodingErrorAction.REPORT ; 否则，将根据要求忽略或替换格式错误的输入。
    - unmappable-character结果表示检测到不匹配的字符错误。编码不可映射字符的字符从输入缓冲区（可能增加）的位置开始; 可以通过调用结果对象的length方法来确定这样的字符的数量。这种情况只适用于当unmappable action这个编码器是CodingErrorAction.REPORT ; 否则不可映射的字符将被忽略或替换，根据要求。
    在任何情况下，如果要在相同的编码操作中重新启用此方法，则应注意保留输入缓冲区中剩余的任何字符，以便它们可用于下一个调用。
    endOfInput参数建议这种方法，以确定调用者是否可以提供超出给定输入缓冲区中的输入。如果提供附加输入的可能性，则调用应该传递false为此参数; 如果没有提供进一步输入的可能性，则调用者应通过true 。这并不是错误的，实际上很常见的是在一次调用中传递false，后来发现没有进一步的输入实际上可用。然而，至关重要的是，以一系列调用方式最终调用此方法总是通过true ，以便任何剩余的未编码的输入将被视为格式错误。
    
    该方法通过调用encodeLoop方法，解释其结果，处理错误条件以及根据需要重新启动它。
    参数
    
    in - 输入字符缓冲区
    
    out - 输出字节缓冲区
    
    endOfInput - true如果并且仅当调用者不能提供超出给定缓冲区中的额外输入字符
    
    结果
    
    描述终止原因的编码器结果对象
    
    异常
    
    IllegalStateException -如果编码操作已在进行中和之前的步骤是一个调用既不的 reset方法，也没有该方法与用于 endOfInput参数a的 false值，也没有该方法与用于 endOfInput参数a的 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参数a的值 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 - 如果从输入缓冲区的当前位置开始的字符序列不是合法的16位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 - 如果编码操作已在进行中

Class CharsetEncoder

构造方法摘要

方法摘要

Methods inherited from class java.lang.Object

构造方法详细信息

CharsetEncoder

CharsetEncoder

方法详细信息

charset

replacement

replaceWith

implReplaceWith

isLegalReplacement

malformedInputAction

onMalformedInput

implOnMalformedInput

unmappableCharacterAction

onUnmappableCharacter

implOnUnmappableCharacter

averageBytesPerChar

maxBytesPerChar

encode

flush

implFlush

reset

implReset

encodeLoop

encode

canEncode

canEncode