# API design help: potentially modifying argument

**URL:** https://discourse.julialang.org/t/api-design-help-potentially-modifying-argument/11334
**Category:** General Usage
**Tags:** question
**Created:** [June 1, 2018, 12:17pm UTC](https://discourse.julialang.org/t/api-design-help-potentially-modifying-argument/11334 "2018-06-01T12:17:26Z")
**Posts on this page:** 2
**Page:** 1

<div class="post-metadata">

### Author: ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)
#### Post date: [June 1, 2018, 12:17pm UTC](https://discourse.julialang.org/t/api-design-help-potentially-modifying-argument/11334/1 "2018-06-01T12:17:26Z")

</div>

I would like to get comments on a certain point of API design for a package I am pondering over. Specifically, for an MWE, I have a generic function [exposed by the API](https://discourse.julialang.org/t/api-design-question-asking-the-user-for-methods-and-types/10049), the user defines custom types and how to “update” them with some change.

For some user-defined types, _updating in place_ would make sense, while for others (fully immutable all the way down, eg containing `StaticArray`s) one would _make a new one_. I want to design an interface that accommodates both.

# Option 1: single function interface

The **interface** exposed by the package could look like this

```julia
"Subtypes define [`updatestate!`](@ref)."
abstract type AbstractState end

"""
    state′ = updatestate!(state::AbstractState, Δ)

Return `state` updated with `Δ`, possibly (but not necessarily) modifying the
first argument. It is up to the implementation whether `state′` and `state`
share structure. Functions in this package guarantee never to use assume that
`state` is unmodified after a call.
"""
function updatestate! end

```

Then someone using the package defines a custom type, and implements the required interface:

```julia
# some implementation - defined by the user for a specific type

struct ConcreteState{T <: AbstractVector} <: AbstractState
    x::T
end

# fallback, eg for StaticVector
updatestate!(state::ConcreteState, Δ) = ConcreteState(state.x .+ Δ)

# but Vector's we can modify
updatestate!(state::ConcreteState{<:Vector}, Δ) = (state.x .+= Δ; state)

```

# Option 2: traits

Instead, user types could define a trait that describes whether they update in place (default: not). Depending on this, one would call `updatestate` or `updatestate!`.

Any other options? Comments? Examples I could look at?

---

<div class="post-metadata">

### Author: ![mschauer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mschauer/32/13946_2.png) [@mschauer](https://discourse.julialang.org/u/mschauer)
#### Post date: [June 1, 2018, 12:41pm UTC](https://discourse.julialang.org/t/api-design-help-potentially-modifying-argument/11334/2 "2018-06-01T12:41:29Z")

</div>

I always advocate that `f!` can mean: `f!` has the “licence to modify” (and not an obligation).  
That means that modifying functions should, when meaningful, return the modified argument. As example you can check the `_chol!` function underlying the `Cholesky` implementation which modifies matrices, but deals gracefully with `StaticArrays` and `Number's` so it can act recursively.