Класс Charset

Именованное отображение последовательностей шестнадцатибитных юникодовых единиц кода и последовательностей байтов. Этот класс определяет методы для создания декодеров и кодеров, а также для получения различных имён, связанных с кодировкой символов. Экземпляры этого класса неизменяемы.

Этот класс также определяет статические методы для проверки поддержки конкретной кодировки символов, для поиска экземпляров кодировки символов по имени и для построения карты, содержащей каждую кодировку символов, для которой доступна поддержка в текущей виртуальной машине Java. Поддержка новых кодировок символов может быть добавлена через интерфейс поставщика услуг, определённый в CharsetProvider классе.

Все методы, определённые в этом классе, безопасны для использования несколькими одновременными потоками.

Имена кодировок символов

Кодировки символов имеют имена, состоящие из следующих символов:

• Заглавные буквы от 'A' до 'Z' ('\u0041' до '\u005a'),
• Строчные буквы от 'a' до 'z' ('\u0061' до '\u007a'),
• Цифры от '0' до '9' ('\u0030' до '\u0039'),
• Дефис '-' ('\u002d', ТИРЕ),
• Плюс '+' ('\u002b', ПЛЮС),
• Точка '.' ('\u002e', ТОЧКА),
• Двоеточие ':' ('\u003a', ДВОЕТОЧИЕ), и
• Подчеркивание '_' ('\u005f', НИЖНЕЕ ПОДЧЁРКИВАНИЕ).

Каждая кодировка символов имеет каноническое имя и может также иметь одно или несколько псевдонимов. Каноническое имя возвращается методом name этого класса. Канонические имена, как правило, записываются заглавными буквами. Псевдонимы кодировки символов возвращаются методом aliases.

Некоторые кодировки символов имеют историческое имя, которое определено для совместимости с предыдущими версиями платформы Java. Историческое имя кодировки символов — это либо её каноническое имя, либо один из её псевдонимов. Историческое имя возвращается методами getEncoding() классов InputStreamReader и OutputStreamWriter.

Если кодировка символов, перечисленных в реестре кодировок символов IANA, поддерживается реализацией платформы Java, то её каноническое имя должно совпадать с именем в реестре. Многие кодировки символов имеют несколько имён в реестре, при этом реестр идентифицирует одно из имён как предпочтительное MIME. Если кодировка символов имеет более одного имени в реестре, то её каноническое имя должно быть предпочтительным именем MIME, а другие имена в реестре должны быть допустимыми псевдонимами. Если поддерживаемая кодировка символов не указана в реестре IANA, то её каноническое имя должно начинаться с одной из строк "X-" или "x-".

Реестр кодировок символов IANA со временем изменяется, поэтому каноническое имя и псевдонимы конкретной кодировки символов также могут меняться со временем. Для обеспечения совместимости рекомендуется не удалять псевдоним кодировки символов и, если каноническое имя кодировки символов изменено, сделать её предыдущее каноническое имя псевдонимом.

Стандартные кодировки символов

Каждая реализация платформы Java обязана поддерживать следующие стандартные кодировки символов. Обратитесь к документации к релизу вашей реализации, чтобы узнать, поддерживаются ли другие кодировки символов. Поведение таких необязательных кодировок символов может отличаться в разных реализациях.

Кодировка символов UTF-8 задана в RFC 2279; формат преобразования, на котором она основана, задан в поправке 2 к ISO 10646-1 и также описан в стандарте Unicode.

Кодировки символов UTF-16 заданы в RFC 2781; форматы преобразования, на которых они основаны, заданы в поправке 1 к ISO 10646-1 и также описаны в стандарте Unicode.

Кодировки символов UTF-16 используют шестнадцатибитные величины и поэтому чувствительны к порядку байтов. В этих кодировках порядок байтов потока может указываться начальной меткой порядка байтов, представленной символом Unicode '\uFEFF'. Метки порядка байтов обрабатываются следующим образом:

• При декодировании кодировки символов UTF-16BE и UTF-16LE интерпретируют начальные метки порядка байтов как ПРОБЕЛ НУЛЕВОЙ ШИРИНЫ НЕРАЗРЫВНЫЙ; при кодировании они не записывают метки порядка байтов.

• При декодировании кодировка символов UTF-16 интерпретирует метку порядка байтов в начале входного потока, чтобы указать порядок байтов потока, но по умолчанию использует большой порядок байтов, если метка порядка байтов отсутствует; при кодировании она использует большой порядок байтов и записывает метку порядка байтов с большим порядком байтов.

Каждая виртуальная машина Java имеет кодировку символов по умолчанию, которая может или не может быть одной из стандартных кодировок символов. Кодировка символов по умолчанию определяется при запуске виртуальной машины и, как правило, зависит от локали и кодировки символов, используемых базовой операционной системой.

Класс StandardCharsets определяет константы для каждой из стандартных кодировок символов.

Терминология

Название этого класса взято из терминов, используемых в RFC 2278. В этом документе кодировка символов определяется как сочетание одного или нескольких наборов символов и схемы кодирования символов. (Это определение запутанное; в некоторых других системах программного обеспечения кодировка символов определяется как синоним набора символов).

Набор символов — это отображение между набором абстрактных символов и набором целых чисел. US-ASCII, ISO 8859-1, JIS X 0201 и Unicode являются примерами наборов символов.

Некоторые стандарты определили набор символов как просто набор абстрактных символов без соответствующего присвоенного номера. Алфавит является примером такого набора символов. Однако тонкое различие между набором символов и набором кодированных символов редко используется на практике; первый стал сокращённой формой для второго, включая в спецификации API Java.

Схема кодирования символов — это отображение между одним или несколькими наборами кодированных символов и набором последовательностей октетов (восьмибитных байтов). UTF-8, UTF-16, ISO 2022 и EUC являются примерами схем кодирования символов. Схемы кодирования часто ассоциируются с конкретным набором кодированных символов; например, UTF-8 используется только для кодирования Unicode. Однако некоторые схемы ассоциируются с несколькими наборами кодированных символов; например, EUC может использоваться для кодирования символов в различных азиатских наборах кодированных символов.

Когда набор кодированных символов используется исключительно с одной схемой кодирования символов, то соответствующая кодировка символов обычно называется по имени набора кодированных символов; в противном случае кодировка символов обычно называется по имени схемы кодирования и, возможно, по локали наборов кодированных символов, которые она поддерживает. Таким образом, US-ASCII — это одновременно имя набора кодированных символов и кодировки символов, которая его кодирует, в то время как EUC-JP — это имя кодировки символов, которая кодирует наборы кодированных символов JIS X 0201, JIS X 0208 и JIS X 0212 для японского языка.

Встроенной кодировкой символов языка программирования Java является UTF-16. Поэтому кодировка символов в платформе Java определяет отображение между последовательностями шестнадцатибитных юникодовых единиц UTF-16 (то есть последовательностями символов) и последовательностями байтов.

Конструкторы

Charset

protected Charset(String canonicalName,
                  String[] aliases)

Инициализирует новый набор символов с заданным каноническим именем и набором псевдонимов.

Параметры:

canonicalName - Каноническое имя этого набора символов

aliases - Массив псевдонимов этого набора символов или null, если псевдонимов нет

Исключения:

IllegalCharsetNameException - Если каноническое имя или любой из псевдонимов являются недопустимыми

Методы

isSupported

public static boolean isSupported(String charsetName)

Определяет, поддерживается ли указанный набор символов.

Параметры:

charsetName - Имя запрошенного набора символов; может быть каноническим именем или псевдонимом

Возвращает:

true тогда и только тогда, когда поддержка указанного набора символов доступна в текущей виртуальной машине Java

Исключения:

IllegalCharsetNameException - Если заданное имя набора символов является недопустимым

IllegalArgumentException - Если заданное charsetName имеет значение null

forName

public static Charset forName(String charsetName)

Возвращает объект набора символов для указанного набора символов.

Параметры:

charsetName - Имя запрошенного набора символов; может быть каноническим именем или псевдонимом

Возвращает:

Объект набора символов для указанного набора символов

Исключения:

IllegalCharsetNameException - Если заданное имя набора символов является недопустимым

IllegalArgumentException - Если заданное charsetName имеет значение null

UnsupportedCharsetException - Если поддержка указанного набора символов недоступна в данной виртуальной машине Java

availableCharsets

public static SortedMap<String,Charset> availableCharsets()

Возвращает:

Неизменяемая карта, игнорирующая регистр, из канонических имён наборов символов к объектам наборов символов

defaultCharset

public static Charset defaultCharset()

Возвращает:

Объект набора символов для набора символов по умолчанию

С:

1.5

name

public final String name()

Возвращает каноническое имя этого набора символов.

Возвращает:

Каноническое имя этого набора символов

aliases

public final Set<String> aliases()

Возвращает набор, содержащий псевдонимы этого набора символов.

Возвращает:

Неизменяемый набор псевдонимов этого набора символов

displayName

public String displayName()

Возвращает:

Отображаемое имя этого набора символов в наборе символов по умолчанию

isRegistered

public final boolean isRegistered()

Определяет, зарегистрирован ли этот набор символов в реестре наборов символов IANA.

Возвращает:

true если и только если этот набор символов известен своему реализатору как зарегистрированный в IANA

displayName

public String displayName(Locale locale)

Параметры:

locale - Набор символов, для которого требуется отображаемое имя

Возвращает:

Отображаемое имя этого набора символов в заданном наборе символов

contains

public abstract boolean contains(Charset cs)

Параметры:

cs - Указанный набор символов

Возвращает:

true если указанный набор символов содержится в этом наборе символов

newDecoder

public abstract CharsetDecoder newDecoder()

Создаёт новый декодер для этого набора символов.

Возвращает:

Новый декодер для этого набора символов

newEncoder

public abstract CharsetEncoder newEncoder()

Создаёт новый кодировщик для этого набора символов.

Возвращает:

Новый кодировщик для этого набора символов

Исключения:

UnsupportedOperationException - Если этот набор символов не поддерживает кодирование

canEncode

public boolean canEncode()

Возвращает:

true если и только если этот набор символов поддерживает кодирование

decode

public final CharBuffer decode(ByteBuffer bb)

cs.newDecoder()
       .onMalformedInput(CodingErrorAction.REPLACE)
       .onUnmappableCharacter(CodingErrorAction.REPLACE)
       .decode(bb);

Параметры:

bb - Буфер байтов, который должен быть декодирован

Возвращает:

Буфер символов, содержащий декодированные символы

encode

public final ByteBuffer encode(CharBuffer cb)

cs.newEncoder()
       .onMalformedInput(CodingErrorAction.REPLACE)
       .onUnmappableCharacter(CodingErrorAction.REPLACE)
       .encode(bb);

Параметры:

cb - Буфер символов, который должен быть закодирован

Возвращает:

Буфер байтов, содержащий закодированные символы

encode

public final ByteBuffer encode(String str)

cs.encode(CharBuffer.wrap(s));

Параметры:

str - Строка, которая должна быть закодирована

Возвращает:

Буфер байтов, содержащий закодированные символы

compareTo

public final int compareTo(Charset that)

Определено:

compareTo в интерфейсе Comparable<Charset>

Параметры:

that - Набор символов, с которым сравнивается этот набор символов

Возвращает:

Отрицательное целое число, ноль или положительное целое число, в зависимости от того, меньше, равно или больше, чем указанный набор символов

hashCode

public final int hashCode()

Вычисляет хэш-код для этого набора символов.

Переопределяет:

hashCode в классе Object

Возвращает:

Целое число хэш-кода

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

equals

public final boolean equals(Object ob)

Переопределяет:

equals в классе Object

Параметры:

ob - Ссылаемый объект для сравнения.

Возвращает:

true если и только если этот набор символов равен заданному объекту

См. также:

Object.hashCode(), HashMap

toString

public final String toString()

Возвращает строку, описывающую этот набор символов.

Переопределяет:

toString в классе Object

Возвращает:

Строка, описывающая этот набор символов