> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NormandoRamirezDelgado/6C-Febrero-2026/llms.txt
> Use this file to discover all available pages before exploring further.

# Maps (Dictionaries)

> Learn about Maps in Dart - key-value pair collections for efficient data storage and retrieval

## What are Maps?

Maps (also called dictionaries) are collections that store data in key-value pairs. Each key is unique and maps to a specific value, making it easy to look up data quickly.

## Creating Maps

Create a map by specifying the key and value types:

```dart theme={null}
Map<String, int> edades = {
  'Juan'  : 17,
  'María' : 16,
  'Carlos': 18,
};
```

<Info>
  The syntax `Map<String, int>` means keys are Strings and values are integers. You can use any type for both keys and values.
</Info>

## Accessing Values

Access values using the key in square brackets:

```dart theme={null}
print(edades['Juan']);  // 17
print(edades['María']); // 16
print(edades['Maria']); // null
```

<Warning>
  Accessing a non-existent key returns `null`, not an error. Always check if a key exists before using its value if you're unsure.
</Warning>

## Adding and Updating Values

### Adding New Entries

Assign a value to a new key to add it to the map:

```dart theme={null}
edades['Ana'] = 17;
print(edades); // {Juan: 17, María: 16, Carlos: 18, Ana: 17}
```

### Updating Existing Entries

Assigning to an existing key updates its value:

```dart theme={null}
edades['Ana'] = 167;
print(edades); // {Juan: 17, María: 16, Carlos: 18, Ana: 167}
```

<Note>
  There's no difference in syntax between adding and updating - if the key exists, it updates; if not, it adds.
</Note>

## Checking for Keys and Values

### Check if Key Exists

Use `containsKey()` to verify if a key is present:

```dart theme={null}
print(edades.containsKey('Juan')); // true
```

### Check if Value Exists

Use `containsValue()` to check if any key has that value:

```dart theme={null}
print(edades.containsValue(17)); // true
```

| Method                 | Description                      | Returns           |
| ---------------------- | -------------------------------- | ----------------- |
| `containsKey(key)`     | Checks if the key exists         | `true` or `false` |
| `containsValue(value)` | Checks if any key has this value | `true` or `false` |

## Removing Entries

Use the `remove()` method to delete a key-value pair:

```dart theme={null}
edades.remove('Carlos');
print(edades); // {Juan: 17, María: 16, Ana: 167}

edades.remove('Pedro'); // No error if key doesn't exist
print(edades); // {Juan: 17, María: 16, Ana: 167}
```

<Tip>
  The `remove()` method doesn't throw an error if the key doesn't exist - it simply does nothing.
</Tip>

## Map Properties

Maps provide several useful properties:

### Get All Keys

```dart theme={null}
print(edades.keys); // (Juan, María, Ana)
```

### Get All Values

```dart theme={null}
print(edades.values); // (17, 16, 167)
```

### Get Number of Entries

```dart theme={null}
print(edades.length); // 3
```

### Check if Empty

```dart theme={null}
print(edades.isEmpty); // false
```

## Common Map Properties

| Property     | Description                       | Example             |
| ------------ | --------------------------------- | ------------------- |
| `keys`       | Returns all keys                  | `edades.keys`       |
| `values`     | Returns all values                | `edades.values`     |
| `length`     | Number of key-value pairs         | `edades.length`     |
| `isEmpty`    | Returns `true` if map is empty    | `edades.isEmpty`    |
| `isNotEmpty` | Returns `true` if map has entries | `edades.isNotEmpty` |

## Complete Example

```dart theme={null}
void main() {
  Map<String, int> edades = {
    'Juan'  : 17,
    'María' : 16,
    'Carlos': 18,
  };

  // ACCEDER
  print(edades['Juan']);  // 17
  print(edades['María']); // 16
  print(edades['Maria']); // null

  // AGREGAR si no Existe
  edades['Ana'] = 17;
  //Sobreescribir si ya Existe
  edades['Ana'] = 167;
  print(edades);

  // VERIFICAR
  print(edades.containsKey('Juan')); // ¿Existe la clave?
  print(edades.containsValue(17));   // ¿Existe el valor?

  // ELIMINAR
  edades.remove('Carlos');
  print(edades);
  edades.remove('Pedro');
  print(edades);

  // CONSULTAR
  print(edades.keys);   // Todas las claves
  print(edades.values); // Todos los valores
  print(edades.length);    // Cantidad de pares
  print(edades.isEmpty);   // ¿Vacío?
  
}
```

## When to Use Maps

<CardGroup cols={2}>
  <Card title="Quick Lookups" icon="magnifying-glass">
    Find data instantly using a unique identifier (like ID, name, or code)
  </Card>

  <Card title="Associations" icon="link">
    Connect related data, like names to phone numbers or products to prices
  </Card>

  <Card title="Counting" icon="calculator">
    Track occurrences or frequencies of items
  </Card>

  <Card title="Configuration" icon="gear">
    Store settings and preferences with named keys
  </Card>
</CardGroup>

## Maps vs Lists

| Feature        | List                          | Map                                    |
| -------------- | ----------------------------- | -------------------------------------- |
| **Access**     | By numeric index (0, 1, 2...) | By unique key (any type)               |
| **Order**      | Maintains insertion order     | Maintains insertion order\*            |
| **Duplicates** | Values can repeat             | Keys must be unique, values can repeat |
| **Use Case**   | Ordered collections           | Key-value associations                 |
| **Speed**      | O(1) by index                 | O(1) by key                            |

<Note>
  \*Dart maps maintain insertion order, but this is an implementation detail. If order matters, consider using a List instead.
</Note>

## Best Practices

<Tip>
  **Check before accessing**: Use `containsKey()` to avoid null values:

  ```dart theme={null}
  if (edades.containsKey('Pedro')) {
    print(edades['Pedro']);
  } else {
    print('Pedro no está en el mapa');
  }
  ```
</Tip>

<Tip>
  **Use descriptive keys**: Choose meaningful key names that clearly represent the data:

  ```dart theme={null}
  // Good
  Map<String, int> studentGrades = {'Alice': 95, 'Bob': 87};

  // Avoid
  Map<String, int> data = {'a': 95, 'b': 87};
  ```
</Tip>