diff --git a/src/guide/lists.md b/src/guide/lists.md index 3e91f71d..279b47fa 100644 --- a/src/guide/lists.md +++ b/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.