feat: Document arbitrary-position list spreads

src/guide/lists.md

@@ -25,6 +25,22 @@ print(oneTwoThree) // [1, 2, 3]
 
 We can also write functions that process data in lists, but we'll save that fun for the section on Pattern Matching.
 
+## More On Spreads (`...`)
+
+Although spreads are recommended to only be put at the end of a list, for convenience it is also possible to use the spread syntax at any position in a list:
+
+```grain
+let oneTwo = [1, 2]
+let threeFour = [3, 4]
+let result = [...oneTwo, ...threeFour, 5]
+
+print(result) // [1, 2, 3, 4, 5]
+```
+
+However, it is important to be aware of the **performance implications of arbitrary-position spreads**. Grain lists are immutable linked lists, and therefore prepending new elements to the beginning of one is a very efficient operation—the new element simply points to the list being extended! On the other hand, we do not get this same benefit if a spread appears somewhere other than at the end of a list expression. In this case, a brand new list must be created, copying one element at a time, pointing each one at the next, to point to the new elements at the end.
+
+Use arbitrary-position spreads sparingly, only when they make your code more expressive and where performance isn't a major concern.
+
 ## The List Standard Library
 
 Lists wouldn't be all that interesting if we couldn't do anything with them, right? Conveniently, the Grain standard library provides a set of functions that work with lists.