From 245a3dbe3467892c30508ab4007e9ca81824378b Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 11 Nov 2022 14:58:39 +1100
Subject: [PATCH] v4.30.1

---
 SUMMARY.md                 |  1 +
 operators/array-to-map.md  | 28 ++++++++++++++++++++++++++++
 operators/datetime.md      |  2 +-
 operators/encode-decode.md |  6 +++---
 operators/slice-array.md   | 23 +++++++++++++++++++++++
 operators/sort.md          | 18 ++++++++++++++++++
 usage/properties.md        | 17 +++++++++++++++++
 usage/xml.md               |  8 ++++----
 8 files changed, 95 insertions(+), 8 deletions(-)
 create mode 100644 operators/array-to-map.md

diff --git a/SUMMARY.md b/SUMMARY.md
index 6b2c9321..16fb15a0 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -16,6 +16,7 @@
   * [Add](operators/add.md)
   * [Alternative (Default value)](operators/alternative-default-value.md)
   * [Anchor and Alias Operators](operators/anchor-and-alias-operators.md)
+  * [Array to Map](operators/array-to-map.md)
   * [Assign (Update)](operators/assign-update.md)
   * [Boolean Operators](operators/boolean-operators.md)
   * [Collect into Array](operators/collect-into-array.md)
diff --git a/operators/array-to-map.md b/operators/array-to-map.md
new file mode 100644
index 00000000..5930aaac
--- /dev/null
+++ b/operators/array-to-map.md
@@ -0,0 +1,28 @@
+# Array to Map
+
+Use this operator to convert an array to..a map. The indices are used as map keys, null values in the array are skipped over.
+
+Behind the scenes, this is implemented using reduce:
+
+```
+(.[] | select(. != null) ) as $i ireduce({}; .[$i | key] = $i)
+```
+
+## Simple example
+Given a sample.yml file of:
+```yaml
+cool:
+  - null
+  - null
+  - hello
+```
+then
+```bash
+yq '.cool |= array_to_map' sample.yml
+```
+will output
+```yaml
+cool:
+  2: hello
+```
+
diff --git a/operators/datetime.md b/operators/datetime.md
index 555fe292..0dc3ed5e 100644
--- a/operators/datetime.md
+++ b/operators/datetime.md
@@ -60,7 +60,7 @@ a: 2001-12-15
 ## Format: get the day of the week
 Given a sample.yml file of:
 ```yaml
-a: 2001-12-15T02:59:43.1Z
+a: 2001-12-15
 ```
 then
 ```bash
diff --git a/operators/encode-decode.md b/operators/encode-decode.md
index 71a1863c..f9e5097d 100644
--- a/operators/encode-decode.md
+++ b/operators/encode-decode.md
@@ -337,7 +337,7 @@ Given a sample.yml file of:
 a:
   cool:
     foo: bar
-    +id: hi
+    +@id: hi
 ```
 then
 ```bash
@@ -357,7 +357,7 @@ Given a sample.yml file of:
 a:
   cool:
     foo: bar
-    +id: hi
+    +@id: hi
 ```
 then
 ```bash
@@ -375,7 +375,7 @@ Given a sample.yml file of:
 a:
   cool:
     foo: bar
-    +id: hi
+    +@id: hi
 ```
 then
 ```bash
diff --git a/operators/slice-array.md b/operators/slice-array.md
index b9a6a844..29d0dafe 100644
--- a/operators/slice-array.md
+++ b/operators/slice-array.md
@@ -80,3 +80,26 @@ will output
 - frog
 ```
 
+## Inserting into the middle of an array
+using an expression to find the index
+
+Given a sample.yml file of:
+```yaml
+- cat
+- dog
+- frog
+- cow
+```
+then
+```bash
+yq '(.[] | select(. == "dog") | key + 1) as $pos | .[0:($pos)] + ["rabbit"] + .[$pos:]' sample.yml
+```
+will output
+```yaml
+- cat
+- dog
+- rabbit
+- frog
+- cow
+```
+
diff --git a/operators/sort.md b/operators/sort.md
index 54111e8d..51c79e4a 100644
--- a/operators/sort.md
+++ b/operators/sort.md
@@ -135,6 +135,24 @@ will output
 - a: 100
 ```
 
+## Sort by custom date field
+Given a sample.yml file of:
+```yaml
+- a: 12-Jun-2011
+- a: 23-Dec-2010
+- a: 10-Aug-2011
+```
+then
+```bash
+yq 'with_dtf("02-Jan-2006"; sort_by(.a))' sample.yml
+```
+will output
+```yaml
+- a: 23-Dec-2010
+- a: 12-Jun-2011
+- a: 10-Aug-2011
+```
+
 ## Sort, nulls come first
 Given a sample.yml file of:
 ```yaml
diff --git a/usage/properties.md b/usage/properties.md
index 4e21e08b..f3d01235 100644
--- a/usage/properties.md
+++ b/usage/properties.md
@@ -149,6 +149,23 @@ person:
         - pizza
 ```
 
+## Decode properties - array should be a map
+If you have a numeric map key in your property files, use array_to_map to convert them to maps.
+
+Given a sample.properties file of:
+```properties
+things.10 = mike
+```
+then
+```bash
+yq -p=props '.things |= array_to_map' sample.properties
+```
+will output
+```yaml
+things:
+    10: mike
+```
+
 ## Roundtrip
 Given a sample.properties file of:
 ```properties
diff --git a/usage/xml.md b/usage/xml.md
index a1d535b1..11c4193e 100644
--- a/usage/xml.md
+++ b/usage/xml.md
@@ -128,7 +128,7 @@ will output
 ```yaml
 +p_xml: version="1.0" encoding="UTF-8"
 cat:
-  +legs: "4"
+  +@legs: "4"
   legs: "7"
 ```
 
@@ -149,7 +149,7 @@ will output
 +p_xml: version="1.0" encoding="UTF-8"
 cat:
   +content: meow
-  +legs: "4"
+  +@legs: "4"
 ```
 
 ## Parse xml: custom dtd
@@ -347,7 +347,7 @@ Fields with the matching xml-attribute-prefix are assumed to be attributes.
 Given a sample.yml file of:
 ```yaml
 cat:
-  +name: tiger
+  +@name: tiger
   meows: true
 
 ```
@@ -368,7 +368,7 @@ Fields with the matching xml-content-name is assumed to be content.
 Given a sample.yml file of:
 ```yaml
 cat:
-  +name: tiger
+  +@name: tiger
   +content: cool
 
 ```