HashMap

Вектор трат и итераторы уже позволяют посчитать общую сумму или сумму по одной категории. Но отчёт хочет другого: сразу увидеть, сколько ушло на еду, сколько на дом, сколько на отдых. Для этого нужна не очередь трат, а таблица «категория — сумма», и в Rust её роль играет HashMap.

Таблица вместо очереди: что такое HashMap

Представьте гардероб с номерками. Вы не перебираете все куртки подряд: называете номерок, и гардеробщик сразу приносит нужную вещь. В Vec вещи лежат по порядку, и искать приходится по месту или перебором. В таблице-гардеробе вы находите значение по имени, а не по позиции.

Официально такая коллекция называется HashMap (хэш-таблица, словарь). Она хранит пары: ключ (то, по чему ищем, у нас — категория) и значение (то, что нашли, у нас — сумма). Ключи в таблице уникальны: одному ключу соответствует одно значение. В стандартной библиотеке HashMap лежит в std::collections, поэтому её нужно подключить строкой use. Тип записывается как HashMap<&str, u32>: в угловых скобках сначала тип ключа, потом тип значения. Мы пока только читаем такие записи, свои обобщённые типы писать не будем.

Создаём пустую таблицу через HashMap::new(), добавляем пары методом insert, считаем записи методом len:

use std::collections::HashMap;

fn main() {
    let mut totals: HashMap<&str, u32> = HashMap::new();
    println!("Записей: {}", totals.len());

    totals.insert("еда", 350);
    totals.insert("транспорт", 60);
    println!("Записей: {}", totals.len());

    totals.insert("еда", 400);
    println!("Записей: {}", totals.len());
}

Записей: 0
Записей: 2
Записей: 2

Достаём значения: get, contains_key и Option

Положить пару мало, нужно ещё её достать. Метод get принимает ключ и отвечает на вопрос «что лежит под этим именем?». А если под таким именем ничего нет? Ответ придётся честно сказать «ничего», и здесь снова выручает знакомый Option: get возвращает Some(...), когда ключ найден, и None, когда нет. Паники при отсутствии ключа не будет.

Есть одна тонкость. Внутри Some лежит не само число, а ссылка на него: тип ответа — Option<&u32>. Таблица только «даёт заглянуть» в своё значение, а не вынимает его (помните заимствование: смотреть можно, не забирая). Печатать такую ссылку можно как обычное число, а вот складывать её с числом напрямую нельзя. Если нужен сам u32, пользуются методом copied(): он превращает Option<&u32> в Option<u32>, то есть делает копию числа. А unwrap_or(0) достаёт значение или подставляет запасное.

use std::collections::HashMap;

fn main() {
    let mut totals: HashMap<&str, u32> = HashMap::new();
    totals.insert("еда", 350);

    println!("{:?}", totals.get("еда"));
    println!("{:?}", totals.get("дом"));
    println!("{}", totals.contains_key("еда"));

    if let Some(sum) = totals.get("еда") {
        println!("На еду: {} руб.", sum);
    }

    let taxi = totals.get("транспорт").copied().unwrap_or(0);
    println!("На транспорт: {} руб.", taxi);
}

Some(350)
None
true
На еду: 350 руб.
На транспорт: 0 руб.

Сведём основные методы в таблицу, чтобы вы могли в неё подглядывать:

Копим суммы: entry и or_insert

Теперь главное для «Копилки»: как копить суммы. Допустим, потратили 350 на еду, потом 60 на транспорт, потом ещё 120 на еду. Вручную пришлось бы каждый раз выяснять: «а есть ли уже запись про еду? Если нет, создать с нулём. Если есть, прочитать, прибавить, записать обратно». Слишком много шагов для простой мысли «прибавь к этой категории».

Представьте учётчика с тетрадью, в которой по странице на категорию. Просьба звучит так: «открой страницу "еда"; если страницы ещё нет, заведи её и запиши 0; и допиши сюда новую сумму». Это и есть entry («запись», интерфейс одной ячейки таблицы). Метод entry(ключ) находит ячейку для ключа, or_insert(0) говорит «если она пуста — положи 0» и отдаёт изменяемую ссылку (&mut u32) на число внутри ячейки. Остаётся пройти по ссылке к самому числу звёздочкой (как *spent += amount в модуле про заимствование) и прибавить.

use std::collections::HashMap;

fn main() {
    let spent = [("еда", 350), ("транспорт", 60), ("еда", 120)];
    let mut totals: HashMap<&str, u32> = HashMap::new();

    for (category, amount) in spent {
        *totals.entry(category).or_insert(0) += amount;
    }

    println!("{:?}", totals.get("еда"));
    println!("{:?}", totals.get("транспорт"));
}

Some(470)
Some(60)

Какие ключи годятся: Hash и derive

Откуда таблица знает, в какую ячейку положить ключ? Она превращает его в число-отпечаток (хэш) и по нему выбирает место. Чтобы это работало, у типа ключа должны быть два умения. Первое — Hash: «умею превращаться в отпечаток». Второе — Eq: «умею точно сказать, равны ли два значения». Слово трейт в нашем курсе значит просто «умение типа», и подробно мы в них не копаем: нам достаточно, что умения подключаются одной строкой #[derive(...)] над типом — её вы уже писали для Debug.

Строки (&str, String), целые числа и bool эти умения имеют сразу. А вот наши собственные типы, например Category, придётся оснастить. Самое время дать перечислению полный набор:

use std::collections::HashMap;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum Category {
    Food,
    Transport,
    Home,
    Fun,
    Other,
}

fn main() {
    let mut totals: HashMap<Category, u32> = HashMap::new();
    *totals.entry(Category::Food).or_insert(0) += 350;
    *totals.entry(Category::Food).or_insert(0) += 120;

    println!("{:?}", totals.get(&Category::Food));
    println!("{:?}", totals.get(&Category::Home));
}

Some(470)
None

Порядок и сортировка для отчёта

Высыпьте карточки из коробки на стол: порядок получится случайный, и при следующем высыпании может быть другим. Так ведёт себя и HashMap. Она быстро находит значение по ключу, но не обещает никакого порядка при обходе: ни порядка вставки, ни алфавитного. Печатая таблицу в цикле, вы можете получить строки в разном порядке от запуска к запуску. Для отчёта это неудобно, поэтому мы сначала переносим пары в вектор, а потом сортируем.

Для этого нужны три шага. into_iter() разбирает таблицу на пары (ключ, значение) — саму таблицу он при этом забирает, она больше не нужна. collect() собирает пары в Vec; нужный тип мы подсказываем слева у переменной. А sort_by сортирует вектор по правилу, которое записывается замыканием, знакомым по итераторам.

use std::collections::HashMap;

fn main() {
    let mut totals: HashMap<&str, u32> = HashMap::new();
    totals.insert("еда", 470);
    totals.insert("дом", 900);
    totals.insert("отдых", 200);

    let mut rows: Vec<(&str, u32)> = totals.into_iter().collect();
    rows.sort_by(|a, b| b.1.cmp(&a.1));

    for (title, sum) in rows {
        println!("{}: {}", title, sum);
    }
}

дом: 900
еда: 470
отдых: 200

Практика: суммы по категориям в Копилке

Применим всё это в проекте kopilka. Откройте src/main.rs — он такой, каким вы оставили его в прошлом уроке. Цикл команд не трогаем: суммы по категориям появятся прямо в нём, в ответе на отчёт. Менять будем четыре места: подключим HashMap, дадим Category нужные умения, напишем totals_by_category и заменим ветку отчёта.

Шаг 1. Подключение и derive

Первой строкой файла, над use std::io;, добавьте use для словаря, а у Category замените строку derive:

use std::collections::HashMap;
use std::io;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum Category {

Eq и Hash делают Category годным ключом таблицы; остальные умения вы уже знаете, они остаются.

Шаг 2. Функция totals_by_category

Добавьте её над fn main(), под total_in:

fn totals_by_category(expenses: &[Expense]) -> HashMap<Category, u32> {
    let mut totals: HashMap<Category, u32> = HashMap::new();
    for expense in expenses {
        *totals.entry(expense.category).or_insert(0) += expense.amount;
    }
    totals
}

Шаг 3. Отчёт по категориям

В match замените содержимое ветки Some(Command::Report). Строка «Из них еда» была нужна только для проверки total_in: теперь еда — одна из строк отчёта.

Some(Command::Report) => {
    let mut rows: Vec<(Category, u32)> = totals_by_category(&expenses).into_iter().collect();
    rows.sort_by(|a, b| b.1.cmp(&a.1));
    for (category, sum) in &rows {
        println!("{}: {} руб.", category.title(), sum);
    }
    let spent = total(&expenses);
    println!("Всего: {} руб. из {} руб.", spent, MONTH_LIMIT);
    print_status(spent, MONTH_LIMIT);
}

Шаг 4. Убираем лишнее

Теперь total_in нигде не вызывается, и компилятор предупредит: warning: function `total_in` is never used. Отчёт по категориям эту функцию заменил, поэтому удалите её целиком: лишнего кода в «Копилке» держать не будем.

Запуск

Выполните cargo run и введите: добавить 350 еда обед, добавить 60 транспорт метро, добавить 120 еда ужин, добавить 900 дом свет, добавить 200 отдых кино, отчёт, выход. Две первые строки вывода (заголовок и подсказка) в примере опущены.

Записано: 350 руб., еда, «обед»
Потрачено: 350 руб. из 30000 руб.
Статус: в норме
Записано: 60 руб., транспорт, «метро»
Потрачено: 410 руб. из 30000 руб.
Статус: в норме
Записано: 120 руб., еда, «ужин»
Потрачено: 530 руб. из 30000 руб.
Статус: в норме
Записано: 900 руб., дом, «свет»
Потрачено: 1430 руб. из 30000 руб.
Статус: в норме
Записано: 200 руб., отдых, «кино»
Потрачено: 1630 руб. из 30000 руб.
Статус: в норме
дом: 900 руб.
еда: 470 руб.
отдых: 200 руб.
транспорт: 60 руб.
Всего: 1630 руб. из 30000 руб.
Статус: в норме
Итого потрачено: 1630 руб. из 30000 руб.

Строки отчёта идут по убыванию сумм: дом, еда, отдых, транспорт. Категории Other в отчёте нет: по ней трат не было, и в таблице нет такой ячейки. Если ввести отчёт до всяких трат, напечатаются только «Всего: 0 руб.» и статус: пустой отчёт мы тоже приведём в порядок в следующем уроке.

Проверьте себя

• Вывод совпадает с примером, а строки отчёта идут по убыванию сумм: дом, еда, отдых, транспорт.
• Уберите Hash из derive. Какая ошибка появилась и в какой функции? Верните Hash обратно.
• Добавьте ещё одну трату: добавить 80 еда кофе. Как изменилась строка про еду в отчёте и сколько в ней рублей теперь?
• Поменяйте b.1.cmp(&a.1) на a.1.cmp(&b.1). В каком порядке теперь идут категории?
• Добавьте трату в категорию другое. Появилась ли в отчёте новая строка и где она встала?

Частые ошибки

Ключ без Hash

Что видно: error[E0599]: the method entry exists for struct HashMap<Category, u32>, but its trait bounds were not satisfied, а в пояснении — Category: Hash и подсказка про #[derive(Hash)]. Почему: тип ключа не умеет давать хэш. Тот же текст вы увидите и для insert. Как исправить: добавьте Eq и Hash в #[derive(...)] над перечислением или структурой, которая служит ключом.

Ждут порядок вставки

Что видно: категории печатаются не в том порядке, в каком вы их добавляли, а при другом запуске — ещё иначе. Почему: HashMap не хранит порядок. Как исправить: перенесите пары в вектор (into_iter().collect()) и отсортируйте его (sort_by) перед печатью.

get вернул не число, а Option

Что видно: error[E0308]: mismatched types с пояснением expected u32, found Option<&u32>; при сложении — error[E0369]: cannot add {integer} to Option<&u32>. Почему: get возвращает Option, а внутри лежит ссылка. Как исправить: разберите ответ через match или if let, либо превратите его в число: totals.get(&key).copied().unwrap_or(0).

Забыли звёздочку у entry

Что видно: error[E0368]: binary assignment operation += cannot be applied to type &mut u32. Почему: or_insert возвращает не число, а изменяемую ссылку на него, и прибавить число к ссылке нельзя. Как исправить: поставьте * в начале выражения — *totals.entry(key).or_insert(0) += amount;.

Что важно запомнить

• HashMap<K, V> хранит пары «ключ — значение»; подключается строкой use std::collections::HashMap;, создаётся через HashMap::new().
• insert по существующему ключу заменяет значение, поэтому ключи в таблице уникальны; len считает пары.
• get(&ключ) возвращает Option<&V>: найдено — Some, не найдено — None. Число достаём через copied().unwrap_or(0), match или if let.
• Копить суммы нужно через *map.entry(ключ).or_insert(0) += значение;: entry находит ячейку, or_insert создаёт её с нулём, * проходит к числу.
• Ключ должен уметь Eq и Hash; для своих типов это #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]. Ключом не может быть f64.
• У HashMap нет порядка. Для упорядоченного отчёта: into_iter().collect() в Vec пар и sort_by(|a, b| b.1.cmp(&a.1)) по убыванию.
• В «Копилке» теперь есть fn totals_by_category(expenses: &[Expense]) -> HashMap<Category, u32> и Category с полным derive.

Суммы по категориям уже лежат в таблице, но печатаем мы их пока по-простому. В следующем уроке соберём из этого настоящую команду отчёт: с выровненными колонками, итогом и статусом лимита.