After some months out of Elixir I am trying to refresh my knowledge on it, therefore I am going through the Elixir for Programmers 2 from @pragdave, because I have done the first edition and it was the one that made made my brain click in the functional programming paradigm.

So I am now at the Agent lesson and he shows the same example we can see in the docs:

iex(12)> Agent.get_and_update(counter, fn state -> {state, state + 1} end)
2
iex(13)> Agent.get(counter, fn state -> state end)                        
3

So, from the function name I would expect to have back the new state, but instead I got back the old state. I know I can control that from the anonymous function I pass, but my question is why the example in the docs is done this way and not this way:

Agent.get_and_update(counter, fn state -> state = state + 1; {state, state} end)    
4
iex(15)> Agent.get_and_update(counter, fn state -> state = state + 1; {state, state} end)
5
iex(16)> Agent.get_and_update(counter, fn state -> state = state + 1; {state, state} end)

I am not seeing immediately how useful it can be to update a state in the Agent and get back the old state, instead of the new state, but for sure it will exist some use cases for it.

Wouldn’t be better to have the official docs showing an example that returns the updated state?