Updated smnp.collection (markdown)

smnp.collection.md

@@ -1,22 +1,120 @@
 # Functions
 ## `flatten(...lists: list)`
+Converts nested lists to single one. You can think, that the function removes nested square brackets and leaves the outer ones (see examples).
+
+### Example
+```
+list1 = [1, 2, [3]];
+list2 = [4, 5, [6, [7]]];
+list3 = [[8, 9], [10], [[11, 12], 13], 14];
+
+a = flatten(list1, list2, list3);
+b = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
+
+c = flatten([@c, [@d, @e], [@f, [@g, @a], @h, @c5, [@d5]]]);
+d = [@c, @d, @e, @f, @g, @a, @h, @c5, @d5];
+
+overtones = flatten([0.5, 10^0.0, 0.3, 5^0.0, 0.1, 3^0.0, 0.1]);
+
+println(a == b);    
+println(c == d);     
+println(overtones);
+
+# Output:
+# true
+# true
+# [0.5, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.3, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1, 0.0, 0.0, 0.0, 0.1]
+```
+
 ## `shuffle(list: list)`
+Returns a shuffled copy of list.
+
+### Example
+```
+x = range(0, 10);
+y = shuffle(x);
+
+println(x);
+println(y);
+
+# Output:
+# [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+# [6, 1, 2, 0, 5, 3, 4, 7, 9, 8]
+```
 
 # Methods
 ## `list.flatten()`
+Invokes `flatten(...)` on `this` and returns flat copy.
+
 ## `list.contains(value)`
+Checks if list contains given value.
+
 ## `list.indexOf(value)`
+Returns index of given value and `-1` if value not exist.
+
 ## `list.join(separator: string = ", ")`
+Joins list items' string representations with given separator to single string value.
+
+### Example
+```
+x = [@c, @d, 14, 3.14, true].join(" :: ");
+
+println(typeOf(x));
+println(x);
+
+# Output:
+# string
+# C4:(1/4) :: D4:(1/4) :: 14 :: 3.14 :: true
+```
+
 ## `list.isEmpty()`
+Checks if list doesn't contain any element.
+
 ## `list.isNotEmpty()`
+Checks if list contains any element.
+
 ## `list.dropIndex(index: int)`
+Returns a copy of list without given index.
+
 ## `list.put(index: int, value)`
+Returns a copy of list with given value inserted at given index.
+
 ## `list.replace(index: int, value)`
+Returns a copy of list with replaced value at given index.
+
 ## `list.swap(a: int, b: int)`
+Returns a copy of list with swapped values between two indices.
+
+### Example
+```
+x = range(@c, @c5, "diatonic");
+y = x.swap(3, 4);
+
+println(x as i ^ i.pitch);
+println(y as i ^ i.pitch);
+
+# Output:
+# [C, D, E, F, G, A, H]
+# [C, D, E, G, F, A, H]
+```
+
 ## `list.shuffle()`
+Invokes `shuffle(...)` on `this` and returns shuffled copy.
+
 ## `map.containsKey(key)`
+Checks if map contains given key.
+
 ## `map.containsValue(value)`
+Checks if map contains given value.
+
 ## `map.contains(key, value)`
+Checks if map contains given key and given value associated with the key.
+
 ## `map.isEmpty()`
+Checks if map doesn't contain any elements.
+
 ## `map.isNotEmpty()`
+Check if map contains any element.
+
 ## `map.getOrDefault(key, default)`
+Returns map element associated with given key or given default value if key doesn't exist in the map.