List - methods

1. clear() - полное очищение данных -

1. add(value)

• Объяснение: Добавляет один новый элемент в самый конец списка.

• Аналогия: Поставить еще одну книгу на полку с правого края.

• Применение: Пользователь создал новый пост, товар упал в корзину.

• Код:

  codeDart

  List<Map<String, dynamic>> users = [{'name': 'Oleg'}];
  
  // Добавляем Анну
  users.add({'name': 'Anna'}); 
  // Результат: [{'name': 'Oleg'}, {'name': 'Anna'}]

---

2. addAll(iterable)

• Объяснение: Добавляет сразу много элементов (другой список) в конец текущего.

• Аналогия: Высыпать ведро кубиков LEGO в общую кучу.

• Применение: Загрузка "следующей страницы" (пагинация) в ленте новостей.

• Код:

  codeDart

  List<Map<String, dynamic>> mainList = [{'id': 1}];
  List<Map<String, dynamic>> newItems = [{'id': 2}, {'id': 3}];
  
  mainList.addAll(newItems);
  // Результат: [{'id': 1}, {'id': 2}, {'id': 3}]

---

3. any(test)

• Объяснение: Проверяет, есть ли в списке хотя бы один элемент, который подходит под условие. Возвращает true (да) или false (нет).

• Аналогия: "Есть ли в классе хоть кто-то, кто забыл сменку?" (Достаточно найти одного).

• Применение: Проверить, есть ли в корзине товары с ошибкой или есть ли у пользователя права админа.

• Код:

  codeDart

  var users = [
    {'name': 'Max', 'age': 15},
    {'name': 'Leo', 'age': 20}
  ];
  
  // Есть ли совершеннолетние?
  bool hasAdult = users.any((u) => u['age'] >= 18); // true

---

4. asMap()

• Объяснение: Превращает список в Map (словарь), где ключами становятся порядковые номера (индексы).

• Аналогия: Пронумеровать страницы в тетради. Теперь у тебя есть пары: "Страница 0 — Текст", "Страница 1 — Текст".

• Применение: Когда нужно перебрать список циклом и знать индекс элемента (например, чтобы написать "Товар №1", "Товар №2").

• Код:

  codeDart

  var fruits = [{'name': 'Apple'}, {'name': 'Banana'}];
  
  fruits.asMap().forEach((index, fruit) {
    print('Фрукт $index: ${fruit['name']}');
  });
  // Вывод:
  // Фрукт 0: Apple
  // Фрукт 1: Banana

---

5. cast()

• Объяснение: Меняет "этикетку" типа списка, не меняя сами данные. Заставляет программу считать, что элементы имеют более строгий тип.

• Аналогия: На коробке написано "Вещи", ты переклеиваешь наклейку на "Игрушки". Содержимое не поменялось, но теперь ты относишься к ним как к игрушкам.

• Применение: Чаще всего, когда сервер или библиотека присылает List<dynamic>, а ты точно знаешь, что там Map<String, dynamic>, и хочешь использовать методы Map.

• Код:

  codeDart

  List<dynamic> rawData = [{'id': 1}, {'id': 2}]; // Пришло как dynamic
  
  // Говорим Dart'у: "Мамой клянусь, там внутри Map<String, dynamic>"
  var typedList = rawData.cast<Map<String, dynamic>>();

---

6. clear()

• Объяснение: Удаляет всё из списка. Список становится пустым, длина 0.

• Аналогия: Стереть всё с доски тряпкой.

• Применение: Кнопка "Очистить корзину" или сброс фильтров поиска.

• Код:

  codeDart

  var cart = [{'item': 'Phone'}];
  cart.clear();
  print(cart.length); // 0

---

7. contains(element)

• Объяснение: Проверяет, лежит ли конкретный объект в списке.

• Важно: Для Map {id: 1} и {id: 1} — это разные объекты в памяти. Вернет true только если ты ищешь ссылку на тот же самый объект.

• Аналогия: "Лежит ли у тебя в кармане именно этот ключ от дома?" (А не просто похожий дубликат).

• Применение: Проверить, выбран ли уже этот элемент (например, в списке выделения), используя переменную-ссылку.

• Код:

  codeDart

  var itemA = {'id': 1};
  var list = [itemA];
  
  print(list.contains(itemA)); // true (это тот же объект)
  print(list.contains({'id': 1})); // false (это новый объект с такими же данными)

---

8. elementAt(index)

• Объяснение: Возвращает элемент под конкретным номером. Если номера нет — ошибка (Crash).

• Аналогия: "Дай мне пятого человека в очереди". (Если людей всего трое — паника).

• Применение: Стандартное получение данных, когда ты уверен в длине списка (например, внутри ListView.builder).

• Код:

  codeDart

  var colors = [{'hex': '#000'}, {'hex': '#FFF'}];
  print(colors.elementAt(1)); // {'hex': '#FFF'}
  // То же самое, что colors[1]

---

9. elementAtOrNull(index)

• Объяснение: То же самое, но безопасно. Если индекса нет — вернет null, а не ошибку.

• Аналогия: "Дай мне пятого человека. Никого нет? Ну ладно, тогда ничего не давай".

• Применение: Безопасное чтение данных, когда список может быть короче, чем ожидалось.

• Код:

  codeDart

  var list = [{'a': 1}];
  var item = list.elementAtOrNull(100); 
  if (item == null) print('Элемента нет'); // Сработает это

---

10. every(test)

• Объяснение: Проверяет, удовлетворяют ли условию абсолютно все элементы списка.

• Аналогия: Фейс-контроль: "Всем ли здесь есть 18 лет?". Если хоть одному нет — результат false.

• Применение: Проверить, все ли поля формы заполнены валидно, или все ли задачи в чек-листе выполнены.

• Код:

  codeDart

  var tasks = [
    {'title': 'Code', 'done': true},
    {'title': 'Sleep', 'done': true}
  ];
  
  bool allDone = tasks.every((t) => t['done'] == true); // true

---

11. expand(toElements)

• Объяснение: "Распаковка". Берет каждый элемент, превращает его в список (или несколько элементов) и склеивает всё в один плоский список.

• Аналогия: У тебя список чемоданов. Ты открываешь каждый и вываливаешь содержимое на кровать. Получается одна большая куча вещей без чемоданов.

• Применение: У тебя есть список категорий, в каждой список товаров. Ты хочешь получить плоский список всех товаров.

• Код:

  codeDart

  var menu = [
    {'category': 'Sup', 'dishes': ['Borsch', 'Shi']},
    {'category': 'Drinks', 'dishes': ['Tea', 'Coffee']}
  ];
  
  // Собираем все блюда в один простой список
  var allDishes = menu.expand((m) => m['dishes'] as List).toList();
  // Результат: ['Borsch', 'Shi', 'Tea', 'Coffee']

---

12. fillRange(start, end, value)

• Объяснение: Заменяет элементы в определенном диапазоне на одно и то же значение.

• Аналогия: Закрасить часть забора (с 2-й по 5-ю доску) одной краской.

• Применение: Используется редко для Map. Можно использовать для создания "заглушек" (placeholders) при загрузке.

• Код:

  codeDart

  // Список из 3 пустышек
  List<Map<String, dynamic>?> slots = [null, null, null];
  
  // Заполняем данными первые два
  slots.fillRange(0, 2, {'status': 'loading'});
  // Результат: [{'status': 'loading'}, {'status': 'loading'}, null]

---

13. firstWhere(test, {orElse})

• Объяснение: Ищет и возвращает самый первый элемент, который подходит под условие. Останавливается, как только нашел.

• Аналогия: "Кто первый в очереди в красной шапке? Выходи!"

• Применение: Найти конкретного пользователя по ID или первый активный заказ.

• Важно: Всегда добавляй orElse, иначе если ничего не найдется — приложение упадет.

• Код:

  codeDart

  var users = [
    {'id': 1, 'name': 'Bob'},
    {'id': 2, 'name': 'Alice'}
  ];
  
  // Ищем ID 2
  var result = users.firstWhere(
    (u) => u['id'] == 2,
    orElse: () => {'id': -1, 'name': 'Not Found'}, // Если не нашли
  );
  print(result['name']); // Alice

14. fold(initialValue, combine)

• Объяснение: "Сворачивает" весь список в одно-единственное значение. Ты даешь ему "начальный ноль" (например, 0 или пустую строку), а он проходит по каждому элементу, прибавляя его к накопленному результату.

• Аналогия: Снежный ком. Ты берешь маленький снежок (initialValue) и катишь его по склону (списку). С каждым оборотом он вбирает в себя новый снег (элемент) и становится больше (результат).

• Применение: Самый частый случай — посчитать общую сумму всех товаров в корзине.

• Код:

  codeDart

  var cart = [
    {'name': 'Phone', 'price': 1000},
    {'name': 'Case', 'price': 50}
  ];
  
  // Считаем общую сумму. Начинаем с 0.
  int totalPrice = cart.fold(0, (previousSum, item) {
    return previousSum + (item['price'] as int);
  });
  
  print(totalPrice); // 1050

---

15. followedBy(other)

• Объяснение: "Лениво" объединяет два списка. Он не создает новый большой список в памяти сразу, а просто "обещает" пробежаться сначала по первому, а потом сразу по второму.

• Аналогия: Два поезда. Вместо того чтобы перегружать всех пассажиров в один новый состав, вы просто сцепляете второй поезд к первому.

• Применение: Когда нужно обработать данные из двух больших списков как единое целое, не тратя память на создание их копии.

• Код:

  codeDart

  var oldClients = [{'name': 'Anna'}];
  var newClients = [{'name': 'Boris'}, {'name': 'Victor'}];
  
  // Объединяем "на лету" и выводим
  var allClients = oldClients.followedBy(newClients);
  
  allClients.forEach((client) {
    print(client['name']); // Anna, потом Boris, потом Victor
  });

---

16. forEach(action)

• Объяснение: "Для каждого". Пробегает по каждому элементу списка и выполняет для него указанное действие. Ничего не возвращает (void).

• Аналогия: Рассылка писем. Почтальон берет каждого адресата из списка и просто опускает ему письмо в ящик. Он не создает новый список адресатов.

• Применение: Когда нужно выполнить "побочный эффект": вывести что-то в консоль, сохранить каждый элемент в базу данных, обновить UI.

• Код:

  codeDart

  var users = [{'name': 'Oleg'}, {'name': 'Irina'}];
  
  // Просто выводим имя каждого
  users.forEach((user) {
    print('Hello, ${user['name']}!');
  });

---

17. getRange(start, end)

• Объяснение: Дает "ленивый" доступ к куску списка. Похоже на sublist, но не создает новый список сразу, а предоставляет Iterable (итерируемый объект).

• Аналогия: Выделить абзац текста в редакторе. Вы определили границы, но еще не скопировали его. Вы можете работать с этим выделением.

• Применение: Эффективная работа с частями очень больших списков, когда создавать копию накладно.

• Код:

  codeDart

  var numbers = [{'val': 10}, {'val': 20}, {'val': 30}, {'val': 40}];
  
  // Получаем "представление" элементов с индекса 1 до 3 (не включая 3)
  var range = numbers.getRange(1, 3); // это {'val': 20}, {'val': 30}
  
  range.forEach(print);

---

18. indexOf(element, [start]) / lastIndexOf(element, [start])

• Объяснение: Ищет конкретный объект в списке и возвращает его индекс (номер по порядку). indexOf — ищет с начала, lastIndexOf — с конца.

• Важно: Как и с contains, работает по ссылке. {'id': 1} и {'id': 1} — это разные объекты!

• Аналогия: Найти номер страницы, на которой находится именно та фотография, на которую вы поставили закладку.

• Применение: Только если у вас есть переменная, хранящая ссылку на объект из списка, и вам нужен его индекс.

• Код:

  codeDart

  var userA = {'name': 'Alex'};
  var userB = {'name': 'Alex'};
  var users = [userA, userB];
  
  print(users.indexOf(userA)); // 0 (нашел тот самый объект)
  print(users.indexOf({'name': 'Alex'})); // -1 (не нашел, т.к. это новый объект)

---

19. indexWhere(test, [start]) / lastIndexWhere(test, [start])

• Объяснение: Это полезный вариант! Ищет индекс первого (или последнего) элемента, который подходит под условие.

• Аналогия: Найти номер страницы, где впервые упоминается слово "дракон".

• Применение: Самый частый способ найти позицию элемента в списке Map по его id или другому уникальному полю.

• Код:

  codeDart

  var products = [
    {'id': 10, 'name': 'Milk'},
    {'id': 25, 'name': 'Bread'},
    {'id': 10, 'name': 'Kefir'}
  ];
  
  // Ищем индекс первого товара с id=10
  int firstIndex = products.indexWhere((p) => p['id'] == 10); // 0
  // Ищем индекс последнего товара с id=10
  int lastIndex = products.lastIndexWhere((p) => p['id'] == 10); // 2

---

20. insert(index, element) / insertAll(index, iterable)

• Объяснение: Вставляет один (insert) или несколько (insertAll) элементов в конкретное место по индексу, сдвигая всех остальных "вправо".

• Аналогия: Влезть в очередь (insert). Или когда группа друзей влезает в очередь вместе (insertAll). Все, кто был за этим местом, делают шаг назад.

• Применение: Добавить рекламный баннер после 3-го поста в ленте. Поставить VIP-заказ в начало очереди.

• Код:

  codeDart

  var list = [{'id': 1}, {'id': 4}];
  
  // Вставляем {id: 2} на позицию 1
  list.insert(1, {'id': 2}); // стало [1, 2, 4]
  
  // Вставляем еще два в начало
  list.insertAll(0, [{'id': 0}, {'id': -1}]);
  // Результат: [{'id': 0}, {'id': -1}, {'id': 1}, {'id': 2}, {'id': 4}]

---

21. join([separator])

• Объяснение: Склеивает все элементы списка в одну длинную строку, вставляя между ними разделитель.

• Важно: Для List<Map> напрямую не работает, т.к. система не знает, как превратить Map в строку. Сначала нужно использовать map, чтобы извлечь нужные данные.

• Аналогия: Нанизывание бусин на нитку. Разделитель — это узелок между бусинами.

• Применение: Сформировать красивую строку тегов через запятую: "flutter, dart, mobile".

• Код:

  codeDart

  var users = [{'name': 'Anna'}, {'name': 'Boris'}];
  
  // 1. Сначала извлекаем имена с помощью map
  var names = users.map((u) => u['name']);
  
  // 2. Теперь склеиваем имена
  String result = names.join(', '); // "Anna, Boris"
  print(result);

---

22. lastWhere(test, {orElse})

• Объяснение: Находит самый последний элемент в списке, который подходит под условие.

• Аналогия: "Кто последний в очереди в красной шапке?"

• Применение: Найти самое последнее событие нужного типа в логах. Найти последнюю версию документа.

• Код:

  codeDart

  var events = [
    {'type': 'login', 'user': 'Bob'},
    {'type': 'click', 'user': 'Bob'},
    {'type': 'login', 'user': 'Ann'}
  ];
  
  // Ищем последнее событие входа в систему
  var lastLogin = events.lastWhere(
    (e) => e['type'] == 'login',
    orElse: () => {'type': 'not_found'},
  );
  print(lastLogin); // {'type': 'login', 'user': 'Ann'}

---

23. map(toElement) — КЛЮЧЕВОЙ МЕТОД

• Объяснение: Трансформация. Проходит по каждому элементу и "переделывает" его во что-то новое. Возвращает новый Iterable с этими новыми элементами.

• Аналогия: Заводской конвейер. На вход подаются Map (сырье), станок их обрабатывает, на выходе — String или объекты вашего класса (готовый продукт).

• Применение: Постоянно. Превращение "сырых" данных с сервера (List<Map>) в список объектов вашего класса (List<User>). Извлечение только одного поля из списка объектов (получить список всех имен).

• Код:

  codeDart

  var data = [
    {'name': 'iPhone', 'price': 1000},
    {'name': 'Pixel', 'price': 900}
  ];
  
  // Получаем новый список, состоящий только из названий
  var names = data.map((item) => item['name'] as String).toList();
  print(names); // ['iPhone', 'Pixel']

---

24. reduce(combine)

• Объяснение: Похож на fold, но у него нет начального значения. Он берет первый элемент как стартовый и начинает "складывать" с ним второй, потом результат с третьим и т.д.

• Важно: Если список пустой, приложение упадет с ошибкой!

• Аналогия: Турнир на выбывание. Первый боец дерется со вторым. Победитель дерется с третьим, и так до финала.

• Применение: Найти элемент с максимальным/минимальным значением.

• Код:

  codeDart

  var products = [
    {'name': 'A', 'price': 100},
    {'name': 'B', 'price': 200},
    {'name': 'C', 'price': 150}
  ];
  
  // Находим самый дорогой товар
  var mostExpensive = products.reduce((currentItem, nextItem) {
    return (currentItem['price'] as int) > (nextItem['price'] as int)
        ? currentItem // если текущий дороже, оставляем его
        : nextItem;   // иначе берем следующий
  });
  print(mostExpensive); // {'name': 'B', 'price': 200}