День 04 · Чужой код и готовые функции · страница 5 из 7

Документация: go doc

Функций в стандартной библиотеке тысячи, и помнить их не нужно: нужно уметь за полминуты узнать, что функция принимает и что возвращает. Документация уже лежит на вашей машине, интернет не нужен.

Ситуация: какой аргумент первый?

Вы пишете strings.Repeat и не помните, что идёт первым — строка или число. Угадывать — значит ловить cannot use ... as ... value. Спросите Go:

Пример · только посмотреть, набирать не нужно

stagiaire@lab:~/gocourse/day04$ go doc strings.Repeat
package strings // import "strings"

func Repeat(s string, count int) string
    Repeat returns a new string consisting of count copies of the string s.

    It panics if count is negative or if the result of (len(s) * count)
    overflows.

go doc принимает пакет и имя через точку — как в коде, только без скобок.

Как читать сигнатуру

Строка func Repeat(s string, count int) string — сигнатура. В ней всё, что нужно для вызова:

Кусок	Что значит
`func`	это функция
`Repeat`	имя
`(s string, count int)`	параметры по порядку: первый `s` типа `string`, второй `count` типа `int`. Сначала имя, потом тип
`string` после скобок	тип результата

Значит, вызов — строка, запятая, целое число: strings.Repeat("=", 16). Имена параметров в вызове не пишутся. Ещё сигнатуры функций дня, разобранные по частям, — в course extra 04.

Описание под сигнатурой — по-английски. Слова, которые встречаются в нём постоянно:

Слово	Что значит
returns	возвращает
reports whether	сообщает, верно ли — результат `bool`
panics if	программа аварийно остановится, если…

It panics if count is negative — не пустые слова: вызов strings.Repeat("-", -1) соберётся, а при запуске программа упадёт. Как выглядит такая паника, — в course extra 04.

Попробуйте сейчас: две справки go doc.

Цель: найти в ответе go doc сигнатуру и прочитать по ней параметры и результат.

В терминале:
▶ Выполните
go doc strings.Repeat
go doc strings.ToUpper
Найдите во втором ответе сигнатуру: сколько у ToUpper параметров, какого они типа и что она возвращает?

Готово, когда: в ответе найдена строка, которая начинается с func ToUpper, и по ней названы число параметров, их тип и тип результата (пункт проверки t_godoc).

Встроенные функции и целый пакет

len не принадлежит никакому пакету: это встроенная функция, и описание таких функций лежит в разделе builtin — go doc builtin.len. Сегодня из него важна одна строка: String: the number of bytes in v. Это ловушка четвёртой страницы, записанная в документации.

go doc strings без имени функции покажет описание пакета и список всех его функций — 67 строк. Незнакомые типы вроде []string или rune пока пропускайте. Для utf8 можно писать короткое имя: go doc utf8.RuneCountInString найдёт unicode/utf8 сам. Регистр для go doc неважен, а в коде важен всегда.

Что может пойти не так

Что видите	Что это значит	Что делать
`doc: no symbol Upper in package strings`	в пакете нет такого имени	`go doc strings` — список всех функций
`doc: symbol string is not a type in package main installed in "day04/fix1"`	опечатка в имени пакета: `string` вместо `strings`. `go doc` решил, что вы ищете что-то в своей программе	проверить имя пакета
`panic: strings: negative Repeat count` и путь в `/usr/local/go/src/strings`	в `Repeat` попало отрицательное число; путь — файл библиотеки, а не ваш	свою строку искать ниже, по `main.go:N`
вывод уехал за экран	пакет большой	прокрутить терминал колесом мыши

Попробуйте сейчас: шесть справок и сверка этикетки.

Цель: прочитать сигнатуры функций дня, найти пару к HasPrefix и проверить типы аргументов в этикетке.

Выполните по очереди и найдите в каждом ответе сигнатуру:
▶ Выполните
go doc strings.CutPrefix
go doc math.Ceil
go doc math.Round
go doc strconv.Itoa
go doc utf8.RuneCountInString
go doc strings
В списке go doc strings найдите функцию, которая проверяет, кончается ли строка на заданный кусок, — пару к HasPrefix. Потом сверьте этикетку label: в math.Round и math.Ceil передаётся float64?

Готово, когда: в каждом из шести ответов найдена строка с func, найдена пара к HasPrefix, а в label оба вызова math получают float64 (пункты t_godoc и t_godoc2).

Попробуйте сейчас: первая починка fix1.

Цель: fix1 печатает то, что обещано в комментарии в начале файла, после точечной правки.
▶ Выполните
cd ~/gocourse/day04/fix1
go run .
Что программа должна напечатать, написано в комментарии в начале файла. Компилятор выдаст два сообщения — оба про одну строку. Прочитайте их, откройте go doc той функции, о которой они говорят, и сравните сигнатуру с вызовом. Здесь хватает одной строки; проверка принимает не больше двух.

Готово, когда: go run . печатает остаток между двумя чертами, как в комментарии, а изменено не больше двух строк (пункт fix1 — он же сверит размер правки).

Дальше: как читать чужую программу — course next

← Кириллица и len Чтение программы в порядке исполнения →