<commit_before># Carp Patterns

This doc captures some common programming patterns in Carp.

## Ref-let

I sometimes find that I want to compute the result of running two different
functions on a non-ref argument from an enclosing scope. Consider the following
function:

```
(defn needs-ref-let [x]
  (Pair.init (inc x) (dec x)))
```

Carp will complain about this function since `inc` and `dec` both
*take-ownership* of the non-ref argument, `x`--this is nice since it ensures we
don't somehow mutate the memory associated with `x`--if we did, we would get
unpredictable results, especially in multi-threaded contexts in which `inc` and
`dec` may try to access `x` simultaneously.

But I still want to compute both `inc` and `dec` on my single `x` value! For
these cases, it's useful to introduce what I'd like to call a "pointer-bind" or
a "ref-let":

```
(defn needs-ref-let [x]
  (let [x* &x]
    (Pair.init (inc @x*) (dec @x*))))
```

`x*`, which is just a references to the `x` argument, allows us to flexibly copy
`x` at will throughout our function body, wherever we need! Of course, the
second copy here is actually unnecessary, since once we've copied `x` once,
we're free to use `x` itself again, since there's no longer threat of bad
mutations or races between `inc` and `dec`:

```
(defn needs-ref-let [x]<commit_msg>Update style, remove personal pronouns<commit_after># Carp Patterns

This doc captures some common programming patterns in Carp.

## Ref-let

You may occasionally that want to compute the result of running two different
ownership-taking functions on a non-ref argument from an enclosing scope.
Consider the following function:

```
(defn needs-ref-let [x]
  (Pair.init (inc x) (dec x)))
```

Carp will complain about this function since `inc` and `dec` both
*take-ownership* of the non-ref argument, `x`--this is nice since it ensures we
don't somehow mutate the memory associated with `x`--if we did, we would get
unpredictable results, especially in multi-threaded contexts in which `inc` and
`dec` may try to access `x` simultaneously.

But you may still want to compute both `inc` and `dec` on the single `x` value!
For these cases, it's useful to introduce a variable bound to a `Ref` to `x`:

```
(defn needs-ref-let [x]
  (let [x* &x]
    (Pair.init (inc @x*) (dec @x*))))
```

`x*`, which is just a references to the `x` argument, allows you to flexibly
copy `x` at will throughout the function body. Of course, the second copy here
is actually unnecessary, since once we've copied `x` once, we're free to use `x`
itself again, since there's no longer threat of bad mutations or races between
`inc` and `dec`:

```
(defn needs-ref-let [x]
{'fraction_non_alphanumeric': 0.10310048561822936, 'fraction_numerical': 0.0, 'mean_word_length': 4.302970297029703, 'pattern_counts': {'":': 1, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1627665', 'n_tokens_mistral': 837, 'n_tokens_neox': 797, 'n_words': 415}