Пакет 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-представлении руны. Если руна не является допустимым значением для кодирования в UTF-8, функция возвращает -1.

Пример

Код:

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