Stream.peek()

Описание

peek() возвращает следующий байт из входного потока, но не удаляет его из буфера. Это означает, что сколько бы раз вы ни вызвали peek() подряд — каждый раз вы будете получать одно и то же значение. Только вызов read() действительно «заберёт» этот байт и продвинет указатель чтения вперёд.

Эта функция входит в класс Stream и доступна во всех классах, которые его наследуют, например Wire и Serial. Подробнее о классе Stream см. на странице Stream.

Синтаксис

stream.peek()

Параметры

Нет.

Возвращает

Следующий байт (или символ) из потока. Если данных нет — возвращает -1. Тип данных: int.

Где применяется

• Разбор протоколов — перед тем как читать байт, нужно понять, что именно пришло: команда, число или разделитель. peek() позволяет сначала проверить тип данных, не нарушая порядок чтения.
• Условное чтение — если следующий символ не соответствует ожидаемому формату, можно отказаться от чтения и обработать ситуацию иначе, не теряя байт.
• Синхронизация с заголовком пакета — удобно проверять, начинается ли входящий поток с нужного маркера, прежде чем начинать разбор всего пакета.

Практические замечания

• Если буфер пуст, peek() вернёт -1 — это то же поведение, что и у read() при отсутствии данных. Всегда проверяйте возвращаемое значение перед использованием.
• peek() не блокирует выполнение программы: если данных нет, функция немедленно возвращает -1, не ожидая их появления.
• Не путайте peek() и read(): первый только смотрит, второй — забирает. Если вы хотите обработать байт — в итоге всё равно нужно вызвать read().
• Функция работает одинаково для Serial, Wire и других классов-наследников Stream, поэтому паттерн «peek → решение → read» применим в любом из них.