I'm pretty confused by one of the subtleties of the vimscript extend() function.
If you use it to extend a list with another list, it does pretty much what you'd expect, which is to insert the second list into the first list at the index given by the third parameter:
let list1 = [1,2,3,4,5,6] | echo extend(list1,[1,2,3,4,5,6],5)
" [1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 6, 6]
However if you give it the same list twice it starts tripping out a bit.
let list1 = [1,2,3,4,5,6] | echo extend(list1,list1,0)
" [1, 2, 3, 4, 5, 6, 1, 2, 3, 4, 5, 6]
let list1 = [1,2,3,4,5,6] | echo extend(list1,list1,1)
" [1, 1, 1, 1, 1, 1, 1, 2, 3, 4, 5, 6]
let list1 = [1,2,3,4,5,6] | echo extend(list1,list1,2)
" [1, 2, 1, 2, 1, 2, 1, 2, 3, 4, 5, 6]
let list1 = [1,2,3,4,5,6] | echo extend(list1,list1,3)
" [1, 2, 3, 1, 2, 3, 1, 2, 3, 4, 5, 6]
let list1 = [1,2,3,4,5,6] | echo extend(list1,list1,4)
" [1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 5, 6]
let list1 = [1,2,3,4,5,6] | echo extend(list1,list1,5)
" [1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 1, 6]
let list1 = [1,2,3,4,5,6] | echo extend(list1,list1,6)
" [1, 2, 3, 4, 5, 6, 1, 2, 3, 4, 5, 6]
Extra-confusingly, this behaviour applies when the list is referenced with two different variables:
let list1 = [1,2,3,4,5,6] | let list2 = list1 | echo extend(list1,list2,4)
" [1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 5, 6]
This is totally bizarre to me. I can't fathom a use for this functionality, and it seems like it would be really easy to invoke it by accident when you just wanted to insert one list into another and didn't realize that the variables were referencing the same array.
The documentation says the following:
If they are |Lists|: Append {expr2} to {expr1}.
If {expr3} is given insert the items of {expr2} before item {expr3} in {expr1}.
When {expr3} is zero insert before the first item.
When {expr3} is equal to len({expr1}) then {expr2} is appended.
Examples:
:echo sort(extend(mylist, [7, 5]))
:call extend(mylist, [2, 3], 1)
When {expr1} is the same List as {expr2} then the number of items copied is equal to the original length of the List.
E.g., when {expr3} is 1 you get N new copies of the first item (where N is the original length of the List).
Does this make sense in a way that I'm not getting, or is it just an eccentricity?
