Most visited

Recently visited

Results for

Added in API level 1
Summary: Protected Ctors | Methods | Protected Methods | Inherited Methods | [Expand All]

CharsetDecoder

public abstract class CharsetDecoder
extends Object

java.lang.Object
   ↳ java.nio.charset.CharsetDecoder

一种引擎，可以将特定字符集中的字节序列转换为16位Unicode字符序列。

The input byte sequence is provided in a byte buffer or a series of such buffers. The output character sequence is written to a character buffer or a series of such buffers. A decoder should always be used by making the following sequence of method invocations, hereinafter referred to as a decoding operation:

  1. 通过 reset方法重置解码器，除非它之前没有使用;

  2. 只要额外的输入可用，则调用 decode方法零次或多次，为 endOfInput参数传递 false并填充输入缓冲区并在调用之间清空输出缓冲区;

  3. 最后一次调用decode方法，通过true传递endOfInput参数; 接着

  4. 调用 flush方法，以便解码器可以将任何内部状态刷新到输出缓冲区。

Each invocation of the decode method will decode as many bytes as possible from the input buffer, writing the resulting characters to the output buffer. The decode method returns when more input is required, when there is not enough room in the output buffer, or when a decoding error has occurred. In each case a CoderResult object is returned to describe the reason for termination. An invoker can examine this object and fill the input buffer, flush the output buffer, or attempt to recover from a decoding error, as appropriate, and try again.

There are two general types of decoding errors. If the input byte sequence is not legal for this charset then the input is considered malformed. If the input byte sequence is legal but cannot be mapped to a valid Unicode character then an unmappable character has been encountered.

How a decoding error is handled depends upon the action requested for that type of error, which is described by an instance of the CodingErrorAction班。 的可能的错误操作是 ignore错误输入， report经由返回错误给调用CoderResult对象，或 replace与替换串的电流值的错误输入。 更换的初始值为"\uFFFD" ; 其值可能通过replaceWith方法更改。

错误输入和不可映射字符错误的缺省操作是 report 。 格式错误的输入错误操作可能通过onMalformedInput方法更改; 可以通过onUnmappableCharacter方法更改不可映射字符动作。

该类旨在处理解码过程的许多细节，包括错误操作的实现。 特定charset的解码器（这是该类的具体子类）只需实现封装基本解码循环的摘要decodeLoop方法。 另外，维持内部状态的子类应该覆盖implFlush和implReset方法。

这个类的实例对于多个并发线程不安全。

也可以看看：

Summary

Protected constructors
CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)

初始化一个新的解码器。

Public methods
final float averageCharsPerByte()

返回将为每个输入字节生成的平均字符数。
final Charset charset()

返回创建此解码器的字符集。
final CharBuffer decode(ByteBuffer in)

便捷方法将单个输入字节缓冲区的剩余内容解码为新分配的字符缓冲区。
final CoderResult decode(ByteBuffer in, CharBuffer out, boolean endOfInput)

从给定的输入缓冲区解码尽可能多的字节，将结果写入给定的输出缓冲区。
Charset detectedCharset()

检索该解码器检测到的字符集 （可选操作） 。
final CoderResult flush(CharBuffer out)

刷新此解码器。
boolean isAutoDetecting()

告诉这个解码器是否实现了一个自动检测字符集。
boolean isCharsetDetected()

告诉该解码器是否已经检测到字符集 （可选操作） 。
CodingErrorAction malformedInputAction()

返回此解码器针对错误输入错误的当前操作。
final float maxCharsPerByte()

返回将为每个输入字节生成的最大字符数。
final CharsetDecoder onMalformedInput(CodingErrorAction newAction)

更改此解码器对错误输入错误的操作。
final CharsetDecoder onUnmappableCharacter(CodingErrorAction newAction)

更改此解码器对不可映射字符错误的操作。
final CharsetDecoder replaceWith(String newReplacement)

更改此解码器的重置值。
final String replacement()

返回此解码器的重置值。
final CharsetDecoder reset()

重置该解码器，清除任何内部状态。
CodingErrorAction unmappableCharacterAction()

返回此解码器对无法映射字符错误的当前操作。

Protected methods
abstract CoderResult decodeLoop(ByteBuffer in, CharBuffer out)

将一个或多个字节解码为一个或多个字符。
CoderResult implFlush(CharBuffer out)

刷新此解码器。
void implOnMalformedInput(CodingErrorAction newAction)

报告此解码器格式错误输入操作的变化。
void implOnUnmappableCharacter(CodingErrorAction newAction)

报告此解码器的无法映射字符操作的更改。
void implReplaceWith(String newReplacement)

报告此解码器重置值的更改。
void implReset()

重置此解码器，清除任何字符集特定的内部状态。

Inherited methods
From class java.lang.Object

Protected constructors

CharsetDecoder

Added in API level 1 
CharsetDecoder (Charset cs, 
                float averageCharsPerByte, 
                float maxCharsPerByte)

初始化一个新的解码器。 新的解码器将具有给定的每字节字符数值，其替换将是字符串"\uFFFD" 。

Parameters
cs Charset
averageCharsPerByte float: A positive float value indicating the expected number of characters that will be produced for each input byte
maxCharsPerByte float: A positive float value indicating the maximum number of characters that will be produced for each input byte
Throws
IllegalArgumentException If the preconditions on the parameters do not hold

Public methods

averageCharsPerByte

Added in API level 1 
float averageCharsPerByte ()

返回将为每个输入字节生成的平均字符数。 该启发式值可以用于估计给定输入序列所需的输出缓冲器的大小。

Returns
float The average number of characters produced per byte of input

charset

Added in API level 1 
Charset charset ()

返回创建此解码器的字符集。

Returns
Charset This decoder's charset

decode

Added in API level 1 
CharBuffer decode (ByteBuffer in)

便捷方法将单个输入字节缓冲区的剩余内容解码为新分配的字符缓冲区。

该方法实现了整个decoding operation ; 也就是说，它重置该解码器，然后解码给定字节缓冲区中的字节，最后清空该解码器。 因此，如果解码操作已在进行中，则不应调用此方法。

Parameters
in ByteBuffer: The input byte buffer
Returns
CharBuffer A newly-allocated character buffer containing the result of the decoding operation. The buffer's position will be zero and its limit will follow the last character written.
Throws
IllegalStateException If a decoding operation is already in progress
MalformedInputException If the byte sequence starting at the input buffer's current position is not legal for this charset and the current malformed-input action is REPORT
UnmappableCharacterException If the byte sequence starting at the input buffer's current position cannot be mapped to an equivalent character sequence and the current unmappable-character action is REPORT
CharacterCodingException

decode

Added in API level 1 
CoderResult decode (ByteBuffer in, 
                CharBuffer out, 
                boolean endOfInput)

从给定的输入缓冲区解码尽可能多的字节，将结果写入给定的输出缓冲区。

从当前位置开始读取和写入缓冲区。 最多in.remaining()字节将被读取，最多out.remaining()字符将被写入。 缓冲区的位置将被提前以反映读取的字节和写入的字符，但它们的标记和限制不会被修改。

除了从输入缓冲区读取字节并将字符写入输出缓冲区外，此方法还会返回一个 CoderResult对象来描述其终止的原因：

  • UNDERFLOW表示尽可能多的输入缓冲区已被解码。 如果没有进一步的输入，则调用者可以继续进行decoding operation的下一步 。 否则，应该再次调用该方法并进一步输入。

  • OVERFLOW表示输出缓冲区中没有足够的空间来解码更多字节。 应该再次使用具有更多remaining字符的输出缓冲区调用此方法。 这通常是通过从输出缓冲器中去除所有解码字符来完成的。

  • A malformed-input结果表示检测到格式错误的输入错误。 格式错误的字节从输入缓冲区的位置开始（可能增加）; 畸形的字节数可以通过调用结果对象的确定length方法。 这种情况只适用于该解码器的 malformed action为REPORT ; 否则根据要求，格式错误的输入将被忽略或替换。

  • unmappable-character结果表示已检测到无法映射的字符错误。 解码不可映射字符的字节从输入缓冲区（可能增加）开始; 这样的字节数可以通过调用结果对象的确定length方法。 这种情况只适用于该解码器的 unmappable action为REPORT ; 否则根据要求，不可映射的字符将被忽略或替换。

In any case, if this method is to be reinvoked in the same decoding operation then care should be taken to preserve any bytes remaining in the input buffer so that they are available to the next invocation.

endOfInput参数建议此方法，以确定调用程序是否可以提供超出给定输入缓冲区中所包含输入的输入。 如果有可能提供额外的输入，那么调用者应该通过false这个参数; 如果没有提供进一步输入的可能性，则调用者应该通过true 。 这并不是错误的，实际上很常见的情况是，在一次调用中传递false ，然后发现实际上没有进一步的输入。 然而，关键是在调用序列中最后调用此方法总是通过true，以便任何未解码的输入将被视为格式错误。

此方法通过调用 decodeLoop方法，解释其结果，处理错误条件并根据需要重新调用它来工作。

Parameters
in ByteBuffer: The input byte buffer
out CharBuffer: The output character buffer
endOfInput boolean: true if, and only if, the invoker can provide no additional input bytes beyond those in the given buffer
Returns
CoderResult A coder-result object describing the reason for termination
Throws
IllegalStateException If a decoding operation is already in progress and the previous step was an invocation neither of the reset method, nor of this method with a value of false for the endOfInput parameter, nor of this method with a value of true for the endOfInput parameter but a return value indicating an incomplete decoding operation
CoderMalfunctionError If an invocation of the decodeLoop method threw an unexpected exception

detectedCharset

Added in API level 1 
Charset detectedCharset ()

检索该解码器检测到的字符集 （可选操作） 。

如果此解码器实现自动检测字符集，则此方法一旦检测到就返回实际字符集。 在那之后，该方法在当前解码操作的持续时间内返回相同的值。 如果尚未读取足够的输入字节以确定实际字符集，则此方法将抛出IllegalStateException 。

此方法的默认实现始终引发UnsupportedOperationException ; 它应该被自动检测解码器覆盖以返回适当的值。

Returns
Charset The charset detected by this auto-detecting decoder, or null if the charset has not yet been determined
Throws
IllegalStateException If insufficient bytes have been read to determine a charset
UnsupportedOperationException If this decoder does not implement an auto-detecting charset

flush

Added in API level 1 
CoderResult flush (CharBuffer out)

刷新此解码器。

一些解码器保持内部状态，并且可能需要在读取整个输入序列后将一些最终字符写入输出缓冲器。

任何额外的输出都会从当前位置开始写入输出缓冲区。 最多可以写out.remaining()字符。 缓冲区的位置将被适当地推进，但其标记和限制不会被修改。

如果此方法成功完成，则返回UNDERFLOW 。 如果输出缓冲区的空间不足，则返回OVERFLOW 。 如果发生这种情况，那么必须再次调用此方法，并输出缓冲区占用更多空间，以完成当前的decoding operation 。

如果此解码器已被刷新，则调用此方法不起作用。

该方法调用 implFlush方法来执行实际的清理操作。

Parameters
out CharBuffer: The output character buffer
Returns
CoderResult A coder-result object, either UNDERFLOW or OVERFLOW
Throws
IllegalStateException If the previous step of the current decoding operation was an invocation neither of the flush method nor of the three-argument decode method with a value of true for the endOfInput parameter

isAutoDetecting

Added in API level 1 
boolean isAutoDetecting ()

告诉这个解码器是否实现了一个自动检测字符集。

此方法的默认实现始终返回false ; 它应该被自动检测解码器覆盖返回true 。

Returns
boolean true if, and only if, this decoder implements an auto-detecting charset

isCharsetDetected

Added in API level 1 
boolean isCharsetDetected ()

告诉该解码器是否已经检测到字符集 （可选操作） 。

如果此解码器实现自动检测字符集，则在解码操作期间的单个点处，此方法可开始返回true以指示在输入字节序列中检测到特定字符集。 一旦发生这种情况，可调用detectedCharset方法来检索检测到的字符集。

该方法返回false并不意味着没有字节尚未解码。 一些自动检测解码器能够解码一些或甚至全部的输入字节序列而不固定在特定的字符集上。

此方法的默认实现始终引发UnsupportedOperationException ; 一旦确定了输入字符集，它应该被自动检测解码器覆盖以返回true 。

Returns
boolean true if, and only if, this decoder has detected a specific charset
Throws
UnsupportedOperationException If this decoder does not implement an auto-detecting charset

malformedInputAction

Added in API level 1 
CodingErrorAction malformedInputAction ()

返回此解码器针对错误输入错误的当前操作。

Returns
CodingErrorAction The current malformed-input action, which is never null

maxCharsPerByte

Added in API level 1 
float maxCharsPerByte ()

Returns the maximum number of characters that will be produced for each byte of input. This value may be used to compute the worst-case size of the output buffer required for a given input sequence.

Returns
float The maximum number of characters that will be produced per byte of input

onMalformedInput

Added in API level 1 
CharsetDecoder onMalformedInput (CodingErrorAction newAction)

更改此解码器对错误输入错误的操作。

此方法调用 implOnMalformedInput方法，传递新操作。

Parameters
newAction CodingErrorAction: The new action; must not be null
Returns
CharsetDecoder This decoder
Throws
IllegalArgumentException If the precondition on the parameter does not hold

onUnmappableCharacter

Added in API level 1 
CharsetDecoder onUnmappableCharacter (CodingErrorAction newAction)

更改此解码器对不可映射字符错误的操作。

此方法调用 implOnUnmappableCharacter方法，传递新操作。

Parameters
newAction CodingErrorAction: The new action; must not be null
Returns
CharsetDecoder This decoder
Throws
IllegalArgumentException If the precondition on the parameter does not hold

replaceWith

Added in API level 1 
CharsetDecoder replaceWith (String newReplacement)

更改此解码器的重置值。

此方法调用 implReplaceWith方法，在检查新替换可接受后传递新替换。

Parameters
newReplacement String: The new replacement; must not be null and must have non-zero length
Returns
CharsetDecoder This decoder
Throws
IllegalArgumentException If the preconditions on the parameter do not hold

replacement

Added in API level 1 
String replacement ()

Returns this decoder's replacement value.

Returns
String This decoder's current replacement, which is never null and is never empty

reset

Added in API level 1 
CharsetDecoder reset ()

重置该解码器，清除任何内部状态。

此方法重置字符集独立状态，并调用 implReset方法以执行任何字符集特定的重置操作。

Returns
CharsetDecoder This decoder

unmappableCharacterAction

Added in API level 1 
CodingErrorAction unmappableCharacterAction ()

返回此解码器对无法映射字符错误的当前操作。

Returns
CodingErrorAction The current unmappable-character action, which is never null

Protected methods

decodeLoop

Added in API level 1 
CoderResult decodeLoop (ByteBuffer in, 
                CharBuffer out)

将一个或多个字节解码为一个或多个字符。

该方法封装了基本的解码循环，尽可能多地解码字节，直到输出用完，输出缓冲区内空间不足，或遇到解码错误。 该方法由decode方法调用，该方法处理结果解释和错误恢复。

从当前位置开始读取和写入缓冲区。 至多in.remaining()字节将被读取，并且最多将写入out.remaining()字符。 缓冲区的位置将被提前以反映读取的字节和写入的字符，但它们的标记和限制不会被修改。

此方法返回一个CoderResult对象来描述其终止的原因，方法与decode方法相同。 此方法的大多数实现将通过返回适当的结果对象以解释decode方法来处理解码错误。 优化的实现可能会检查相关的错误操作并实施该操作本身。

该方法的实现可以通过返回 UNDERFLOW来执行任意 UNDERFLOW直到它接收到足够的输入。

Parameters
in ByteBuffer: The input byte buffer
out CharBuffer: The output character buffer
Returns
CoderResult A coder-result object describing the reason for termination

implFlush

Added in API level 1 
CoderResult implFlush (CharBuffer out)

刷新此解码器。

这个方法的默认实现什么都不做，总是返回UNDERFLOW 。 该方法应该被解码器覆盖，解码器在读取完整个输入序列后可能需要将最终字符写入输出缓冲区。

Parameters
out CharBuffer: The output character buffer
Returns
CoderResult A coder-result object, either UNDERFLOW or OVERFLOW

implOnMalformedInput

Added in API level 1 
void implOnMalformedInput (CodingErrorAction newAction)

报告此解码器格式错误输入操作的变化。

此方法的默认实现不做任何事情。 这种方法应该被要求通知对格式错误的输入操作进行更改的解码器覆盖。

Parameters
newAction CodingErrorAction

implOnUnmappableCharacter

Added in API level 1 
void implOnUnmappableCharacter (CodingErrorAction newAction)

报告此解码器的无法映射字符操作的更改。

此方法的默认实现不做任何事情。 此方法应由需要通知对无法映射字符操作进行更改的解码器覆盖。

Parameters
newAction CodingErrorAction

implReplaceWith

Added in API level 1 
void implReplaceWith (String newReplacement)

报告此解码器重置值的更改。

此方法的默认实现不做任何事情。 这种方法应该被需要通知更换替换的解码器覆盖。

implReset

Added in API level 1 
void implReset ()

重置此解码器，清除任何字符集特定的内部状态。

此方法的默认实现不做任何事情。 这个方法应该被维护内部状态的解码器覆盖。

Android开发手册

Hooray!