Feedback Needed: New "Arrays" Tutorial on OCaml.org

Community
,
1

Hey everyone,

there’s a new tutorial on “Arrays” at

https://staging.ocaml.org/docs/arrays

with a corresponding PR here:

Looking for constructive feedback.

Is there any information missing or questions that you would need answered in order for this tutorial to be useful? Anything you would change?

4 Likes
2

I think a tutorial on arrays should mention for loop since those are quite natural with a random access mutable structure. It would make sense to make the parallel between loops and iterators functions but not mentioning for seems quite partial in this case.

2 Likes
3

Makes sense, I think that will be a good addition before we merge the PR.

4

It might also be a good idea to add a “Caveat” section or to say that Array.make can be misleading if you pass a constructor that is also mutable.

Ie. I’ve been bitten too many times by a version of:

let m = Array.make 2 (Array.make 2 0)
let () =
   assert (m.(1).(0) = 0); (* OK *)
   m.(0).(0) <- 1;
   assert (m.(1).(0) = 0) (* BOOM *)
5 Likes
5

I think I got bit by exactly this a couple of weeks ago on my first use of arrays.

let m = Array.make 2 (Array.make 2 0)

Re-uses the inner Array + you need to use… make_matrix instead (or force creation of a new inner array each time yourself).

So +1 on the idea of putting an example in about that.

1 Like
6

There is a typo in the subheader “Lenght of an array.”

You may also want to mention the functions Array.iteri and Array.mapi under the iterate and map sections. Those are often the functions I need, and someone coming from, say, Python who is used to enumerate() may not find those obvious.

1 Like
7

Interesting article. It was useful for me.

There are a few typos in the paragraph under “Sorting an Array”:

an array Ir sorts the provided array in place, in ascending order, according to the provided comparison function. [The?] Sorting performed by Array.sort modifies the content of the provided array, that['s?] why it returns unit .

1 Like
8

This is a lovely tutorial! :yellow_heart:

I think it would greatly benefit from two things:

  1. Complete example of a simple function that uses Arrays. Currently all examples are written in utop but I think it would be helpful to see how to put all things together in a small function inside a module. For example, reversing an array.
  2. Comparison with lists. Especially considering that the List tutorial comes first. It might not be obvious which one to pick for folks without extensive knowledge of Computer Science, Software Engineering and OCaml runtime system.
2 Likes