# `Diffo.Util`
[🔗](https://github.com/diffo-dev/diffo/blob/v0.9.0/lib/diffo/helpers/util.ex#L5)

Utility methods

# `close_to_now?`

true if the datetime is close to (+/- 5 mins) from now
## Examples
  iex> Diffo.Util.close_to_now?(DateTime.utc_now() |> DateTime.shift(minute: 4))
  true

  iex> Diffo.Util.close_to_now?(DateTime.utc_now() |> DateTime.shift(minute: -4))
  true

  iex> Diffo.Util.close_to_now?(DateTime.utc_now() |> DateTime.shift(minute: 6))
  false

  iex> Diffo.Util.close_to_now?(DateTime.utc_now() |> DateTime.shift(minute: -6))
  false

# `datetime`

realises a datetime from now conforming to the summary
## Examples
  iex> datetime = Diffo.Util.datetime(:now)
  iex> Diffo.Util.summarise(datetime)
  :now

  iex> datetime = Diffo.Util.datetime(:future)
  iex> Diffo.Util.summarise(datetime)
  :future

  iex> datetime = Diffo.Util.datetime(:past)
  iex> Diffo.Util.summarise(datetime)
  :past

# `delete_if_empty`

Deletes map value if empty []
## Examples
  iex> Diffo.Util.delete_if_empty(%{serviceCharacteristic: [%{name: :port, value: 1}]}, :serviceCharacteristic)
  %{serviceCharacteristic: [%{name: :port, value: 1}]}

  iex> Diffo.Util.delete_if_empty(%{serviceCharacteristic: []}, :serviceCharacteristic)
  %{}

# `ensure_not_nil`

Ensures value in map is not nil. If existing and replacement value both nil removes key
## Examples
  iex> Diffo.Util.ensure_not_nil(%{}, :category, :connectivity)
  %{category: :connectivity}

  iex> Diffo.Util.ensure_not_nil(%{category: :connectivity}, :category, :physical)
  %{category: :physical}

  iex> Diffo.Util.ensure_not_nil(%{category: :connectivity}, nil, :physical)
  %{category: :connectivity}

  iex> Diffo.Util.ensure_not_nil(%{category: :connectivity}, :category, nil)
  %{}

# `extract_suppress`

Extracts value from map in list of tuples, and sets if not nil
  ## Examples
  iex> duration = Duration.new!(month: 1)
  iex> list = [duration: duration]
  iex> tl(Diffo.Util.extract_suppress(list, :duration, :month, :months))
  [months: 1]

# `fragment`

Encapsulate a tuple value as a Jason Fragment
  ## Examples
  iex> list = [state: :initial, service: Jason.encode!(%{state: :initial})]
  iex> list = Diffo.Util.fragment(list, :service)
  iex> {:service, %name{}} = List.keyfind(list, :service, 0)
  iex> name
  Jason.Fragment

# `future?`

true if the datetime is future, more than 5 mins after now
## Examples
  iex> Diffo.Util.future?(DateTime.utc_now() |> DateTime.shift(minute: 6))
  true

  iex> Diffo.Util.future?(DateTime.utc_now() |> DateTime.shift(minute: 4))
  false

# `get`

Gets a value from a list of tuples, or nil
## Examples
  iex> list = [a: 1, b: 2]
  iex> Diffo.Util.get(list, :b)
  2
  iex> Diffo.Util.get(list, :c)
  nil

# `nest`

Nest values from list of tuples into a list, with a new tuple key
  ## Examples
  iex> list = [state: :up, weeks: 1, days: 5]
  iex> Diffo.Util.nest(list, [:weeks, :days], :duration)
  [state: :up, duration: [weeks: 1, days: 5]]

# `nest_as_map`

Nest values from list of tuples into a map, with a new tuple key
  ## Examples
  iex> list = [state: :up, weeks: 1, days: 5]
  iex> Diffo.Util.nest_as_map(list, [:weeks, :days], :duration)
  [state: :up, duration: %{weeks: 1, days: 5}]

# `past?`

true if the datetime is past, more than 5 mins before now
  ## Examples
  iex> Diffo.Util.past?(DateTime.utc_now() |> DateTime.shift(minute: -6))
  true

  iex> Diffo.Util.past?(DateTime.utc_now() |> DateTime.shift(minute: -4))
  false

# `put_not_empty`

Adds value to map if not empty []
## Examples
  iex> Diffo.Util.put_not_empty(%{}, :serviceCharacteristic, [%{name: :port, value: 1}])
  %{serviceCharacteristic: [%{name: :port, value: 1}]}

  iex> Diffo.Util.put_not_empty(%{}, :key, [])
  %{}

  iex> Diffo.Util.put_not_empty(%{}, nil, [%{name: :port, value: 1}])
  %{}

# `remove`

Removes a tuple from a list of tuples
  ## Examples
  iex> list = [a: [], b: [1], c: nil]
  iex> Diffo.Util.remove(list, :a)
  [b: [1], c: nil]
  iex> Diffo.Util.remove(list, :b)
  [a: [], c: nil]
  iex> Diffo.Util.remove(list, :c)
  [a: [], b: [1]]
  iex> Diffo.Util.remove(list, :d)
  [a: [], b: [1], c: nil]

# `rename`

Renames a tuple in a list, preserving its value and position
  ## Examples
  iex> list = [a: 1, b: 2, d: 3]
  iex> Diffo.Util.rename(list, :b, :c)
  [a: 1, c: 2, d: 3]
  iex> Diffo.Util.rename(list, :c, :e)
  [a: 1, b: 2, d: 3]
  iex> Diffo.Util.rename(list, :b, nil)
  [a: 1, d: 3]

# `rename_ensure_not_empty`

Renames map key, unless old value is empty
## Examples
  iex> Diffo.Util.rename_ensure_not_empty(%{characteristic: [%{name: :port, value: 1}]}, :characteristic, :serviceCharacteristic)
  %{serviceCharacteristic: [%{name: :port, value: 1}]}

  iex> Diffo.Util.rename_ensure_not_empty(%{characteristic: []}, :characteristic, :serviceCharacteristic)
  %{}

  iex> Diffo.Util.rename_ensure_not_empty(%{}, :characteristic, :serviceCharacteristic)
  %{}

# `set`

Adds a tuple or updates the existing tuple value in a list of tuples
## Examples
  iex> list = [a: 1, b: 2]
  iex> Diffo.Util.set(list, :c, 3)
  [a: 1, b: 2, c: 3]
  iex> Diffo.Util.set(list, :b, 3)
  [a: 1, b: 3]
  iex> Diffo.Util.set(list, :c, nil)
  [a: 1, b: 2]
  iex> Diffo.Util.set(list, :b, nil)
  [a: 1]
  iex> Diffo.Util.set(list, :c, [])
  [a: 1, b: 2]
  iex> Diffo.Util.set(list, :b, [])
  [a: 1]

# `summarise`

summarize datetimes in relation to now
## Examples
  iex> Diffo.Util.summarise(DateTime.utc_now() |> DateTime.shift(minute: 4))
  :now

  iex> Diffo.Util.summarise(DateTime.utc_now() |> DateTime.shift(minute: -4))
  :now

  iex> Diffo.Util.summarise(DateTime.utc_now() |> DateTime.shift(minute: 6))
  :future

  iex> Diffo.Util.summarise(DateTime.utc_now() |> DateTime.shift(minute: -6))
  :past

# `summarise_dates`

Summarise ISO8601 dates, by comparing them with now, in a payload
## Examples
  iex> now = DateTime.utc_now()
  iex> future = DateTime.shift(now, minute: 6)
  iex> past = DateTime.shift(now, minute: -6)
  iex> payload = Diffo.Util.to_iso8601(past) <> "," <> Diffo.Util.to_iso8601(now) <> "," <> Diffo.Util.to_iso8601(future)
  iex> Diffo.Util.summarise_dates(payload)
  "past,now,future"

# `suppress`

Suppresses a tuple from a list of tuples if nil or empty
  ## Examples
  iex> list = [a: [], b: [1], c: nil]
  iex> Diffo.Util.suppress(list, :a)
  [b: [1], c: nil]
  iex> Diffo.Util.suppress(list, :b)
  [a: [], b: [1], c: nil]
  iex> Diffo.Util.suppress(list, :c)
  [a: [], b: [1]]
  iex> Diffo.Util.suppress(list, :d)
  [a: [], b: [1], c: nil]

# `suppress_rename`

Suppresses or renames, using suppress |> rename
  ## Examples
  iex> list = [a: [], b: [1], c: nil]
  iex> Diffo.Util.suppress_rename(list, :a, :d)
  [b: [1], c: nil]

  iex> list = [a: [1], b: [1], c: nil]
  iex> Diffo.Util.suppress_rename(list, :a, :d)
  [d: [1], b: [1], c: nil]
  iex> Diffo.Util.suppress_rename(list, :a, nil)
  [b: [1], c: nil]

# `to_iso8601`

Convert a dateime to iso8601, with millisecond resolution

---

*Consult [api-reference.md](api-reference.md) for complete listing*