---
title: "with"
url: https://una-lang.org/en/docs/std/builtin/with/
release: v0.4.0
edition: "0.2 and later"
source: https://github.com/una-lang/una/blob/v0.4.0/docs/std/builtins.json
---

# with

A built-in method, resolved by the type of its receiver ([`spec/14 §2`](https://una-lang.org/en/docs/spec/14-standard-library/#s2)). Edition 0.2 and later.

## Edition 0.2 and later

```una
m.with(key: K, value: V) -> Map[K, V]
  where m: Map[K, V]
```

A map with the contract of `set`, for the result (`spec/21 §2`). On a `Set`, a set with the contract of `add`, for the result (`spec/28 §6`); on a `HashMap` and a `HashSet`, the same for the hash table (`spec/28 §7`); on a `BitSet`, the same for the bit set (`spec/28 §9`).

## Edition 0.5 preview

```una
m.with(key: K, value: V) -> Map[K, V]
  where m: Map[K, V]
s.with(item: T) -> Set[T]
  where s: Set[T]
m.with(key: K, value: V) -> HashMap[K, V]
  where m: HashMap[K, V]
s.with(item: T) -> HashSet[T]
  where s: HashSet[T]
b.with(item: Int) -> BitSet
  where b: BitSet
```

A map with the contract of `set`, for the result (`spec/21 §2`). On a `Set`, a set with the contract of `add`, for the result (`spec/28 §6`); on a `HashMap` and a `HashSet`, the same for the hash table (`spec/28 §7`); on a `BitSet`, the same for the bit set (`spec/28 §9`).

In editions 0.5. In edition 0.2, 0.3, 0.4: no `Set[T]`\, `HashMap[K, V]`\, `HashSet[T]` or `BitSet` receiver\, since `std.collections` begins in edition 0\.5\: it has none of `s.with(item: T) -> Set[T]`\, `where s: Set[T]`\, `m.with(key: K, value: V) -> HashMap[K, V]`\, `where m: HashMap[K, V]`\, `s.with(item: T) -> HashSet[T]`\, `where s: HashSet[T]`\, `b.with(item: Int) -> BitSet` and `where b: BitSet`.

## On a `Map[K, V]`

The receiver is the map `m`.

### Parameters

- `key`: the key\; from edition 0\.3\, with a refined key type `K`\, it is stored at `K`\, an obligation that `una check` proves at the call
- `value`: the value at `key`\; from edition 0\.3\, with a refined value type `V`\, it is stored at `V`\, an obligation that `una check` proves at the call

### Returns

`Map[K, V]`: a map with the contract of `set` for the result\: `m` with `value` at `key`\; `m` itself is unchanged.

## On a `Set[T]`

The receiver is the set `s`.

### Parameters

- `item`: the item\; with a refined item type `T`\, it is stored at `T`\, an obligation that `una check` proves at the call

### Returns

`Set[T]`: a set with the contract of `add` for the result\: `s` with `item`\; `s` itself is unchanged.

## On a `HashMap[K, V]`

The receiver is the hash map `m`.

### Parameters

- `key`: the key\; with a refined key type `K`\, it is stored at `K`\, an obligation that `una check` proves at the call
- `value`: the value at `key`\; with a refined value type `V`\, it is stored at `V`\, an obligation that `una check` proves at the call

### Returns

`HashMap[K, V]`: a map with the contract of `set` for the result\: `m` with `value` at `key`\, a new key listed last\; `m` itself is unchanged.

## On a `HashSet[T]`

The receiver is the hash set `s`.

### Parameters

- `item`: the item\; with a refined item type `T`\, it is stored at `T`\, an obligation that `una check` proves at the call

### Returns

`HashSet[T]`: a set with the contract of `add` for the result\: `s` with `item`\, a new item listed last\; `s` itself is unchanged.

## On a `BitSet`

The receiver is the bit set `b`.

### Parameters

- `item`: the integer\, which must be in the range from 0 to `b.size - 1`\: an obligation that `una check` proves at the call

### Returns

`BitSet`: a bit set with the contract of `add` for the result\: `b` with `item`\, of the same size\; `b` itself is unchanged.

## See also

[`set`](https://una-lang.org/en/docs/std/builtin/set/), [`without`](https://una-lang.org/en/docs/std/builtin/without/)

## Cost

Time `O(log n) per lookup, insertion and removal` on a `Map[K, V]` (spec/21 §5), where:

- `n`: the number of entries in `m`\; the update is in place when the call is the last use of `m` and nothing else holds it\, and on a copy\, in O\(n\)\, otherwise

## Example

`src/shop.una`

```una
module shop

--- A price list built one entry at a time.
pub main() -> Unit
  uses @console: Console[print]
=
  let prices = empty_map().with(key: "lamp", value: 1999).with(key: "desk", value: 4999)
  @console.print("{prices.len} prices")
```

`una run .` prints:

```text
2 prices
```

## Specification

- [`spec/21 §2`](https://una-lang.org/en/docs/spec/21-maps/#s2)
- `spec/28 §6`
- `spec/28 §7`
- `spec/28 §9`

Generated from una v0.4.0 ([`docs/std/builtins.json`](https://github.com/una-lang/una/blob/5fec93d88932b333feec25e589355a2cb34c37b5/docs/std/builtins.json), which is not part of the specification): built-in methods have no declaration, so una writes these signature lines and tests each against its checker. The specification governs: [`spec/14 §2`](https://una-lang.org/en/docs/spec/14-standard-library/#s2).
