v4.53.2

operators/slice-array.md

@@ -1,8 +1,8 @@
-# Slice/Splice Array
+# Slice Array or String
 
-The slice array operator takes an array as input and returns a subarray. Like the `jq` equivalent, `.[10:15]` will return an array of length 5, starting from index 10 inclusive, up to index 15 exclusive. Negative numbers count backwards from the end of the array.
+The slice operator works on both arrays and strings. Like the `jq` equivalent, `.[10:15]` will return a subarray (or substring) of length 5, starting from index 10 inclusive, up to index 15 exclusive. Negative numbers count backwards from the end of the array or string.
 
-You may leave out the first or second number, which will refer to the start or end of the array respectively.
+You may leave out the first or second number, which will refer to the start or end of the array or string respectively.
 
 ## Slicing arrays
 Given a sample.yml file of:
@@ -103,3 +103,81 @@ will output
 - cow
 ```
 
+## Slicing strings
+Given a sample.yml file of:
+```yaml
+country: Australia
+```
+then
+```bash
+yq '.country[0:5]' sample.yml
+```
+will output
+```yaml
+Austr
+```
+
+## Slicing strings - without the second number
+Finishes at the end of the string
+
+Given a sample.yml file of:
+```yaml
+country: Australia
+```
+then
+```bash
+yq '.country[5:]' sample.yml
+```
+will output
+```yaml
+alia
+```
+
+## Slicing strings - without the first number
+Starts from the start of the string
+
+Given a sample.yml file of:
+```yaml
+country: Australia
+```
+then
+```bash
+yq '.country[:5]' sample.yml
+```
+will output
+```yaml
+Austr
+```
+
+## Slicing strings - use negative numbers to count backwards from the end
+Negative indices count from the end of the string
+
+Given a sample.yml file of:
+```yaml
+country: Australia
+```
+then
+```bash
+yq '.country[-5:]' sample.yml
+```
+will output
+```yaml
+ralia
+```
+
+## Slicing strings - Unicode
+Indices are rune-based, so multi-byte characters are handled correctly
+
+Given a sample.yml file of:
+```yaml
+greeting: héllo
+```
+then
+```bash
+yq '.greeting[1:3]' sample.yml
+```
+will output
+```yaml
+él
+```
+