Adding keys function (#244)

versions/development/SPEC.md

@@ -121,6 +121,7 @@
   * [Array\[Pair(X,Y)\] cross(Array\[X\], Array\[Y\])](#arraypairxy-crossarrayx-arrayy)
   * [Array\[Pair(X,Y)\] as_pairs(Map\[X,Y\])](#arraypairxy-as_pairsmapxy)
   * [Map\[X,Y\] as_map(Array\[Pair(X,Y)\])](#mapxy-as_maparraypairxy)
+  * [Array\[X\] keys(Map\[X,Y\])](#arrayx-keysmapxy)
   * [Map\[X,Array\[Y\]\] collect_by_key(Array\[Pair(X,Y)\])](#mapxarrayy-collect_by_keyarraypairxy)
   * [Integer length(Array\[X\])](#integer-lengtharrayx)
   * [Array\[X\] flatten(Array\[Array\[X\]\])](#arrayx-flattenarrayarrayx)
@@ -3100,6 +3101,20 @@ Map[String,Int] xmap = as_map(x) # {"a": 1, "b": 2, "c": 3}
 Map[String,Pair[File,File]] ymap = as_map(y) # {"a": ("a.bam", "a.bai"), "b": ("b.bam", "b.bai")}
 ```
 
+## Array[X] keys(Map[X,Y])
+
+Given a Map, the `keys` function returns an Array consisting of the keys in the Map. The order of the keys in the resulting Array is the same as the order of the Pairs in the Map.
+
+In cases where multiple Pairs would produce the same key, the workflow will fail.
+
+```
+Map[String,Int] x = {("a", 1), ("b", 2), ("c", 3)}
+Map[String,Pair[File,File]] y = {("a", ("a.bam", "a.bai")), ("b", ("b.bam", "b.bai"))}
+
+Array[String] xmap = keys(x) # ["a", "b", "c"]
+Array[String] ymap = keys(y) # ["a", "b"]
+```
+
 ## Map[X,Array[Y]] collect_by_key(Array[Pair[X,Y]])
 
 Given an Array consisting of Pairs, the `collect_by_key` function returns a Map in which the left elements of the Pairs are the keys and the right elements the values. The left element of the Pairs passed to `as_map` must be a primitive type. The values will be placed in an Array to allow for multiple Pairs to produce the same key. The order of the keys in the Map is the same as the order in the Array based on their first occurence. The order of the elements in the resulting Arrays is the same as their occurence in the given Array of Pairs.