Справочник Ada 2012
A.4.11 Кодировка строк
Для кодирования, декодирования и преобразования строк в различных кодировках символов предоставляются пакеты Strings.UTF_Encoding, Strings.UTF_Encoding.Conversions, Strings.UTF_Encoding.Strings, Strings.UTF_Encoding.Wide_Strings и Strings.UTF_Encoding.Wide_Wide_Strings.
Статическая семантика
Пакеты библиотек кодирования имеют следующие объявления:
package Ada.Strings.UTF_Encoding is
pragma Pure (UTF_Encoding);
pragma Pure (UTF_Encoding);
-- Объявления, общие для пакетов кодирования строк
type Encoding_Scheme is (UTF_8, UTF_16BE, UTF_16LE);
type Encoding_Scheme is (UTF_8, UTF_16BE, UTF_16LE);
subtype UTF_String is String;
subtype UTF_8_String is String;
subtype UTF_16_Wide_String is Wide_String;
Encoding_Error : exception;
BOM_8 : constant UTF_8_String :=
Character'Val(16#EF#) &
Character'Val(16#BB#) &
Character'Val(16#BF#);
Character'Val(16#EF#) &
Character'Val(16#BB#) &
Character'Val(16#BF#);
BOM_16BE : constant UTF_String :=
Character'Val(16#FE#) &
Character'Val(16#FF#);
Character'Val(16#FE#) &
Character'Val(16#FF#);
BOM_16LE : constant UTF_String :=
Character'Val(16#FF#) &
Character'Val(16#FE#);
Character'Val(16#FF#) &
Character'Val(16#FE#);
BOM_16 : constant UTF_16_Wide_String :=
(1 => Wide_Character'Val(16#FEFF#));
(1 => Wide_Character'Val(16#FEFF#));
function Encoding (Item : UTF_String;
Default : Encoding_Scheme := UTF_8)
return Encoding_Scheme;
Default : Encoding_Scheme := UTF_8)
return Encoding_Scheme;
end Ada.Strings.UTF_Encoding;
package Ada.Strings.UTF_Encoding.Conversions is
pragma Pure (Conversions);
pragma Pure (Conversions);
-- Преобразования между различными кодировками
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Input_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
function Convert (Item : UTF_8_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
function Convert (Item : UTF_16_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Convert (Item : UTF_16_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
end Ada.Strings.UTF_Encoding.Conversions;
package Ada.Strings.UTF_Encoding.Strings is
pragma Pure (Strings);
pragma Pure (Strings);
-- Кодирование/декодирование между String и различными кодировками
function Encode (Item : String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Encode (Item : String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Encode (Item : String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
function Encode (Item : String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return String;
Input_Scheme : Encoding_Scheme) return String;
function Decode (Item : UTF_8_String) return String;
function Decode (Item : UTF_16_Wide_String) return String;
end Ada.Strings.UTF_Encoding.Strings;
package Ada.Strings.UTF_Encoding.Wide_Strings is
pragma Pure (Wide_Strings);
pragma Pure (Wide_Strings);
-- Кодирование/декодирование между Wide_String и различными кодировками
function Encode (Item : Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Encode (Item : Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Encode (Item : Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
function Encode (Item : Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_String;
Input_Scheme : Encoding_Scheme) return Wide_String;
function Decode (Item : UTF_8_String) return Wide_String;
function Decode (Item : UTF_16_Wide_String) return Wide_String;
end Ada.Strings.UTF_Encoding.Wide_Strings;
package Ada.Strings.UTF_Encoding.Wide_Wide_Strings is
pragma Pure (Wide_Wide_Strings);
pragma Pure (Wide_Wide_Strings);
-- Кодирование/декодирование между Wide_Wide_String и различными кодировками
function Encode (Item : Wide_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Encode (Item : Wide_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_Wide_String;
Input_Scheme : Encoding_Scheme) return Wide_Wide_String;
function Decode (Item : UTF_8_String) return Wide_Wide_String;
function Decode (Item : UTF_16_Wide_String) return Wide_Wide_String;
end Ada.Strings.UTF_Encoding.Wide_Wide_Strings;
Тип Encoding_Scheme определяет схемы кодирования. UTF_8 соответствует схеме кодирования UTF-8, определенной в приложении D стандарта ISO/IEC 10646. UTF_16BE соответствует схеме кодирования UTF-16, определенной в приложении C стандарта ISO/IEC 10646 в 8-битном формате с порядком байтов big-endian; а UTF_16LE соответствует схеме кодирования UTF-16 в 8-битном формате с порядком байтов little-endian.
Подтип UTF_String используется для представления строки 8-битных значений, содержащей последовательность значений, закодированных одним из трех способов (UTF-8, UTF-16BE или UTF-16LE). Подтип UTF_8_String используется для представления строки 8-битных значений, содержащей последовательность значений, закодированных в UTF-8. Подтип UTF_16_Wide_String используется для представления Wide_String 16-битных значений, содержащих последовательность значений, закодированных в UTF-16.
Константы BOM_8, BOM_16BE, BOM_16LE и BOM_16 соответствуют значениям, используемым в начале строки для указания кодировки.
Каждая из функций Encode принимает в качестве параметра Item строку String, Wide_String или Wide_Wide_String, которая предполагается как массив не закодированных символов. Каждая из функций Convert принимает в качестве параметра Item UTF_String, UTF_8_String или UTF_16_String, который предполагается содержащим символы, значения позиций которых соответствуют допустимой последовательности кодирования в соответствии со схемой кодирования, требуемой функцией или заданной параметром Input_Scheme.
Каждая из функций Convert и Encode возвращает значение UTF_String, UTF_8_String или UTF_16_String, символы которого имеют значения позиций, соответствующие кодировке параметра Item в соответствии со схемой кодирования, требуемой функцией или заданной параметром Output_Scheme. Для UTF-8 не возвращается никакая избыточная кодировка. BOM включается в начало возвращаемой строки, если параметр Output_BOM установлен в True. Нижний предел возвращаемой строки равен 1.
Каждая из функций Decode принимает в качестве параметра Item UTF_String, UTF_8_String или UTF_16_String, который предполагается содержащим символы, значения позиций которых соответствуют допустимой последовательности кодирования в соответствии со схемой кодирования, требуемой функцией или заданной параметром Input_Scheme, и возвращает соответствующее значение String, Wide_String или Wide_Wide_String. Нижний предел возвращаемой строки равен 1.
Для каждой из функций Convert и Decode начальный BOM в входных данных, соответствующий ожидаемой схеме кодирования, игнорируется, а другой начальный BOM приводит к распространению Encoding_Error.
Исключение Encoding_Error также распространяется в следующих ситуациях:
- Функцией Convert или Decode, когда закодированная по UTF строка содержит недопустимую последовательность кодирования.
- Функцией Convert или Decode, когда ожидаемая кодировка — UTF-16BE или UTF-16LE, а длина входной строки нечётная.
- Функцией Decode, возвращающей String, когда декодирование последовательности приводит к кодовому пункту, значение которого превышает 16#FF#.
- Функцией Decode, возвращающей Wide_String, когда декодирование последовательности приводит к кодовому пункту, значение которого превышает 16#FFFF#.
- Функцией Encode, принимающей Wide_String в качестве входных данных, когда в вводе появляется недопустимый символ. В частности, символы, позиция которых находится в диапазоне 16#D800# .. 16#DFFF#, недопустимы, потому что они конфликтуют с суррогатными кодировками UTF-16, а символы с позицией 16#FFFE# или 16#FFFF# также недопустимы, поскольку они конфликтуют с кодами BOM.
function Encoding (Item : UTF_String;
Default : Encoding_Scheme := UTF_8)
return Encoding_Scheme;
Default : Encoding_Scheme := UTF_8)
return Encoding_Scheme;
Проверяет значение UTF_String, чтобы определить, начинается ли оно с BOM для UTF-8, UTF-16BE или UTF_16LE. Если да, то возвращает схему, соответствующую BOM; в противном случае возвращает значение Default.
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Input_Scheme : Encoding_Scheme;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Возвращает значение Item (изначально закодированное в UTF-8, UTF-16LE или UTF-16BE, как указано в Input_Scheme), закодированное одним из этих трех способов, как указано в Output_Scheme.
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Input_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Возвращает значение Item (изначально закодированное в UTF-8, UTF-16LE или UTF-16BE, как указано в Input_Scheme), закодированное в UTF-16.
function Convert (Item : UTF_8_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Возвращает значение Item (изначально закодированное в UTF-8), закодированное в UTF-16.
function Convert (Item : UTF_16_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Возвращает значение Item (первоначально закодированное в UTF-16), закодированное в UTF-8, UTF-16LE или UTF-16BE в соответствии со значением Output_Scheme.
function Convert (Item : UTF_16_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
Возвращает значение Item (первоначально закодированное в UTF-16), закодированное в UTF-8.
function Encode (Item : String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Возвращает значение Item, закодированное в UTF-8, UTF-16LE или UTF-16BE в соответствии со значением Output_Scheme.
function Encode (Item : String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
Возвращает значение Item, закодированное в UTF-8.
function Encode (Item : String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Возвращает значение Item, закодированное в UTF-16.
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return String;
Input_Scheme : Encoding_Scheme) return String;
Возвращает результат декодирования Item, закодированного в UTF-8, UTF-16LE или UTF-16BE в соответствии со значением Input_Scheme.
function Decode (Item : UTF_8_String) return String;
Возвращает результат декодирования Item, закодированного в UTF-8.
function Decode (Item : UTF_16_Wide_String) return String;
Возвращает результат декодирования Item, закодированного в UTF-16.
function Encode (Item : Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Возвращает значение Item, закодированное в UTF-8, UTF-16LE или UTF-16BE в соответствии со значением Output_Scheme.
function Encode (Item : Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
Возвращает значение Item, закодированное в UTF-8.
function Encode (Item : Wide_String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Возвращает значение Item, закодированное в UTF-16.
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_String;
Input_Scheme : Encoding_Scheme) return Wide_String;
Возвращает результат декодирования Item, закодированного в UTF-8, UTF-16LE или UTF-16BE в соответствии со значением Input_Scheme.
function Decode (Item : UTF_8_String) return Wide_String;
Возвращает результат декодирования Item, закодированного в UTF-8.
function Decode (Item : UTF_16_Wide_String) return Wide_String;
Возвращает результат декодирования Item, закодированного в UTF-16.
function Encode (Item : Wide_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Возвращает значение Item, закодированное в UTF-8, UTF-16LE или UTF-16BE в соответствии со значением Output_Scheme.
function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Output_BOM : Boolean := False) return UTF_8_String;
Возвращает значение Item, закодированное в UTF-8.
function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Возвращает значение Item, закодированное в UTF-16.
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_Wide_String;
Input_Scheme : Encoding_Scheme) return Wide_Wide_String;
Возвращает результат декодирования Item, закодированного в UTF-8, UTF-16LE или UTF-16BE в соответствии со значением Input_Scheme.
function Decode (Item : UTF_8_String) return Wide_Wide_String;
Возвращает результат декодирования Item, закодированного в UTF-8.
function Decode (Item : UTF_16_Wide_String) return Wide_Wide_String;
Возвращает результат декодирования Item, закодированного в UTF-16.
Рекомендации по реализации
Если реализация поддерживает другие схемы кодирования, следует определить другой аналогичный подтип Ada.Strings.
ПРИМЕЧАНИЯ
18 BOM (Byte-Order Mark, код позиции 16#FEFF#) может быть включён в файл или другой объект для указания кодировки; он пропускается при декодировании. Как правило, BOM содержится только в первой строке файла или другого объекта. При декодировании функция Encoding может быть вызвана для первой строки, чтобы определить кодировку; эта кодировка затем будет использоваться в последующих вызовах Decode для преобразования всех строк в внутренний формат.
