1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
.TH MPU_STRING_CONVERSION 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_ucs2_to_utf8, mpu_utf8_to_ucs2
\- преобразование между строгими строками UCS-2 LIBMPUIO и UTF-8
.SH ОБЗОР
.nf
#include <libmpuio.h>
__mpu_size_t mpu_ucs2_to_utf8( __mpu_char8_t *dest, const __mpu_char16_t *src, __mpu_size_t nb );
__mpu_size_t mpu_utf8_to_ucs2( __mpu_char16_t *dest, const __mpu_char8_t *src, __mpu_size_t nb );
.fi
.SH ОПИСАНИЕ
Эти функции преобразуют текст между внутренним строгим представлением UCS-2
LIBMPUIO и внешним представлением UTF-8. Они намеренно работают с обычными
буферами, предоставленными вызывающей стороной; строковый объект типа
указатель-на-указатель не требуется.
.PP
.B mpu_ucs2_to_utf8()
преобразует NUL-терминированную строку UCS-2
.I src
в UTF-8. Аргумент
.I nb
задаёт доступный размер буфера назначения в байтах.
.PP
.B mpu_utf8_to_ucs2()
преобразует NUL-терминированную строку UTF-8
.I src
в строгий UCS-2. Аргумент
.I nb
задаёт доступный размер буфера назначения в кодовых единицах
.BR __mpu_char16_t .
.PP
Если
.I dest
равен NULL, вывод не производится, а
.I nb
игнорируется. Функция проверяет весь вход и возвращает точный размер,
необходимый для преобразованной полезной части, без завершающего NUL. Это
обеспечивает обычную двухпроходную схему определения размера без использования
двойного указателя.
.PP
Если
.I dest
не равен NULL, записывается столько полного результата, сколько помещается.
Завершающий NUL записывается только если после полного преобразованного
результата остаётся место. Возвращаемое значение равно объёму фактически
записанной полезной части без терминатора.
.SH СТРОГИЙ UCS-2
Суррогатные кодовые единицы UCS-2 от U+D800 до U+DFFF являются недопустимым
входом для
.BR mpu_ucs2_to_utf8 ().
Аналогично,
.B mpu_utf8_to_ucs2()
отвергает корректные символы UTF-8 выше U+FFFF, поскольку они не могут быть
представлены одной строгой кодовой единицей UCS-2. Суррогатные скалярные
значения и некорректный UTF-8 также отвергаются.
.SH ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успехе
.B mpu_ucs2_to_utf8()
возвращает число байтов, а
.B mpu_utf8_to_ucs2()
\- число кодовых единиц UCS-2. Завершающий NUL не учитывается.
.PP
При ошибке кодирования функции возвращают
.B (__mpu_size_t)-1
и устанавливают
.B errno
в
.BR EILSEQ .
.SH ПРИМЕР
.nf
__mpu_char16_t text[] = MPU_UCS2( "Hello" );
__mpu_size_t bytes;
__mpu_char8_t *utf8;
bytes = mpu_ucs2_to_utf8( NULL, text, 0 );
utf8 = malloc( bytes + 1 );
if( utf8 != NULL )
mpu_ucs2_to_utf8( utf8, text, bytes + 1 );
.fi
.SH СМ. ТАКЖЕ
.BR mpu_str16ing (3),
.BR mpu_utf8ing (3),
.BR mpu_printf (3)
|
