Пакет utf8

• import "unicode/utf8"
• Обзор
• Индекс
• Примеры

Обзор

Пакет utf8 реализует функции и константы для поддержки текста, закодированного в UTF-8. Он включает функции для преобразования между рунами и последовательностями байтов UTF-8. См. https://en.wikipedia.org/wiki/UTF-8

Индекс

• Константы
• func AppendRune(p []byte, r rune) []byte
• func DecodeLastRune(p []byte) (r rune, size int)
• func DecodeLastRuneInString(s string) (r rune, size int)
• func DecodeRune(p []byte) (r rune, size int)
• func DecodeRuneInString(s string) (r rune, size int)
• func EncodeRune(p []byte, r rune) int
• func FullRune(p []byte) bool
• func FullRuneInString(s string) bool
• func RuneCount(p []byte) int
• func RuneCountInString(s string) (n int)
• func RuneLen(r rune) int
• func RuneStart(b byte) bool
• func Valid(p []byte) bool
• func ValidRune(r rune) bool
• func ValidString(s string) bool

Файлы пакета

utf8.go

Константы

Числа, фундаментальные для кодирования.

const (
    RuneError = '\uFFFD'     // the "error" Rune or "Unicode replacement character"
    RuneSelf  = 0x80         // characters below RuneSelf are represented as themselves in a single byte.
    MaxRune   = '\U0010FFFF' // Maximum valid Unicode code point.
    UTFMax    = 4            // maximum number of bytes of a UTF-8 encoded Unicode character.
)

func AppendRune 1.18

func AppendRune(p []byte, r rune) []byte

AppendRune добавляет UTF-8 кодирование r в конец p и возвращает расширенный буфер. Если руна находится вне диапазона, она добавляет кодирование RuneError.

Пример

Код:

buf1 := utf8.AppendRune(nil, 0x10000)
buf2 := utf8.AppendRune([]byte("init"), 0x10000)
fmt.Println(string(buf1))
fmt.Println(string(buf2))

Вывод:

𐀀
init𐀀

func DecodeLastRune

func DecodeLastRune(p []byte) (r rune, size int)

DecodeLastRune распаковывает последнее UTF-8 кодирование в p и возвращает руну и её ширину в байтах. Если p пустой, он возвращает (RuneError, 0). В противном случае, если кодирование недействительно, он возвращает (RuneError, 1). Оба являются невозможными результатами для корректного, непустого UTF-8.

Кодирование недействительно, если оно некорректное UTF-8, кодирует руну вне диапазона или не является самым коротким возможным UTF-8 кодированием для значения. Другая валидация не выполняется.

Пример

Код:

b := []byte("Hello, 世界")

for len(b) > 0 {
    r, size := utf8.DecodeLastRune(b)
    fmt.Printf("%c %v\n", r, size)

    b = b[:len(b)-size]
}

Вывод:

界 3
世 3
  1
, 1
o 1
l 1
l 1
e 1
H 1

func DecodeLastRuneInString

func DecodeLastRuneInString(s string) (r rune, size int)

DecodeLastRuneInString похож на DecodeLastRune, но его входной параметр — строка. Если s пустая, он возвращает (RuneError, 0). В противном случае, если кодирование недействительно, он возвращает (RuneError, 1). Оба являются невозможными результатами для корректного, непустого UTF-8.

Кодирование недействительно, если оно некорректное UTF-8, кодирует руну вне диапазона или не является самым коротким возможным UTF-8 кодированием для значения. Другая валидация не выполняется.

Пример

Код:

str := "Hello, 世界"

for len(str) > 0 {
    r, size := utf8.DecodeLastRuneInString(str)
    fmt.Printf("%c %v\n", r, size)

    str = str[:len(str)-size]
}

Вывод:

界 3
世 3
  1
, 1
o 1
l 1
l 1
e 1
H 1

func DecodeRune

func DecodeRune(p []byte) (r rune, size int)

DecodeRune распаковывает первое UTF-8 кодирование в p и возвращает руну и её ширину в байтах. Если p пустой, он возвращает (RuneError, 0). В противном случае, если кодирование недействительно, он возвращает (RuneError, 1). Оба являются невозможными результатами для корректного, непустого UTF-8.

Кодирование недействительно, если оно некорректное UTF-8, кодирует руну вне диапазона или не является самым коротким возможным UTF-8 кодированием для значения. Другая валидация не выполняется.

Пример

Код:

b := []byte("Hello, 世界")

for len(b) > 0 {
    r, size := utf8.DecodeRune(b)
    fmt.Printf("%c %v\n", r, size)

    b = b[size:]
}

Вывод:

H 1
e 1
l 1
l 1
o 1
, 1
  1
世 3
界 3

func DecodeRuneInString

func DecodeRuneInString(s string) (r rune, size int)

DecodeRuneInString похож на DecodeRune, но его входной параметр — строка. Если s пустая, он возвращает (RuneError, 0). В противном случае, если кодирование недействительно, он возвращает (RuneError, 1). Оба являются невозможными результатами для корректного, непустого UTF-8.

Кодирование недействительно, если оно некорректное UTF-8, кодирует руну вне диапазона или не является самым коротким возможным UTF-8 кодированием для значения. Другая валидация не выполняется.

Пример

Код:

str := "Hello, 世界"

for len(str) > 0 {
    r, size := utf8.DecodeRuneInString(str)
    fmt.Printf("%c %v\n", r, size)

    str = str[size:]
}

Вывод:

H 1
e 1
l 1
l 1
o 1
, 1
  1
世 3
界 3

func EncodeRune

func EncodeRune(p []byte, r rune) int

EncodeRune записывает в p (который должен быть достаточно большим) UTF-8 кодирование руны. Если руна вне диапазона, он записывает кодирование RuneError. Он возвращает количество записанных байтов.

Пример

Код:

r := '世'
buf := make([]byte, 3)

n := utf8.EncodeRune(buf, r)

fmt.Println(buf)
fmt.Println(n)

Вывод:

[228 184 150]
3

Пример (OutOfRange)

Код:

runes := []rune{
    // Less than 0, out of range.
    -1,
    // Greater than 0x10FFFF, out of range.
    0x110000,
    // The Unicode replacement character.
    utf8.RuneError,
}
for i, c := range runes {
    buf := make([]byte, 3)
    size := utf8.EncodeRune(buf, c)
    fmt.Printf("%d: %d %[2]s %d\n", i, buf, size)
}

Вывод:

0: [239 191 189] � 3
1: [239 191 189] � 3
2: [239 191 189] � 3

func FullRune

func FullRune(p []byte) bool

FullRune сообщает, начинается ли байты в p со полным UTF-8 кодированием руны. Некорректное кодирование считается полной руной, так как оно будет преобразовываться как руна ошибки с шириной 1 байт.

Пример

Код:

buf := []byte{228, 184, 150} // 世
fmt.Println(utf8.FullRune(buf))
fmt.Println(utf8.FullRune(buf[:2]))

Вывод:

true
false

func FullRuneInString

func FullRuneInString(s string) bool

FullRuneInString похож на FullRune, но его входной параметр — строка.

Пример

Код:

str := "世"
fmt.Println(utf8.FullRuneInString(str))
fmt.Println(utf8.FullRuneInString(str[:2]))

Вывод:

true
false

func RuneCount

func RuneCount(p []byte) int

RuneCount возвращает количество рун в p. Ошибочные и короткие кодирования обрабатываются как одиночные руны шириной 1 байт.

Пример

Код:

buf := []byte("Hello, 世界")
fmt.Println("bytes =", len(buf))
fmt.Println("runes =", utf8.RuneCount(buf))

Вывод:

bytes = 13
runes = 9

func RuneCountInString

func RuneCountInString(s string) (n int)

RuneCountInString похож на RuneCount, но его входной параметр — строка.

Пример

Код:

str := "Hello, 世界"
fmt.Println("bytes =", len(str))
fmt.Println("runes =", utf8.RuneCountInString(str))

Вывод:

bytes = 13
runes = 9

func RuneLen

func RuneLen(r rune) int

RuneLen возвращает количество байтов в UTF-8 кодировании руны. Он возвращает -1, если руна не является допустимым значением для кодирования в UTF-8.

Пример

Код:

fmt.Println(utf8.RuneLen('a'))
fmt.Println(utf8.RuneLen('界'))

Вывод:

1
3

func RuneStart

func RuneStart(b byte) bool

RuneStart сообщает, может ли байт быть первым байтом закодированной, возможно, недействительной руны. Второй и последующие байты всегда имеют два старших бита, установленные в 10.

Пример

Код:

buf := []byte("a界")
fmt.Println(utf8.RuneStart(buf[0]))
fmt.Println(utf8.RuneStart(buf[1]))
fmt.Println(utf8.RuneStart(buf[2]))

Вывод:

true
true
false

func Valid

func Valid(p []byte) bool

Valid сообщает, состоит ли p полностью из валидных UTF-8 кодированных рун.

Пример

Код:

valid := []byte("Hello, 世界")
invalid := []byte{0xff, 0xfe, 0xfd}

fmt.Println(utf8.Valid(valid))
fmt.Println(utf8.Valid(invalid))

Вывод:

true
false

func ValidRune 1.1

func ValidRune(r rune) bool

ValidRune сообщает, может ли r быть законно закодирована как UTF-8. Кодовые точки, которые находятся вне диапазона или суррогатные половинки, являются незаконными.

Пример

Код:

valid := 'a'
invalid := rune(0xfffffff)

fmt.Println(utf8.ValidRune(valid))
fmt.Println(utf8.ValidRune(invalid))

Вывод:

true
false

func ValidString

func ValidString(s string) bool

ValidString сообщает, состоит ли s полностью из валидных UTF-8 кодированных рун.

Пример

Код:

valid := "Hello, 世界"
invalid := string([]byte{0xff, 0xfe, 0xfd})

fmt.Println(utf8.ValidString(valid))
fmt.Println(utf8.ValidString(invalid))

Вывод:

true
false