Update docs for in operator and negative ranges

Author: nicklockwood

docs/ios/expressions.md

@@ -197,6 +197,16 @@ for i in loops {
 }
 ```
 
+You can also use the `in` operator to check if a range contains a particular value:
+
+```swift
+define range 1 to 5
+
+if 2.5 in range {
+    print "range contains 2.5"
+}
+```
+
 **Note:** Ranges are inclusive of both the start and end values, so a loop from `0 to 5` would loop *6* times and not 5 as you might expect.
 
 Range values can be fractional and/or negative:
@@ -245,6 +255,17 @@ for i in 5 to 1 step -1 {
 }
 ```
 
+For stepped ranges, `in` will only return true for values that align with the steps:
+
+```swift
+define range 1 to 5 step 2
+
+print 1 in range // prints true
+print 2 in range // prints false
+print 2.5 in range // prints false
+print 3 in range // prints true
+```
+
 ## Members
 
 Compound values like [vectors and tuples](literals.md#vectors-and-tuples) and [objects](literals.md#objects) can be decomposed by using the *dot* operator to access individual components or *members*:
@@ -349,7 +370,25 @@ for i in 0 to foo.count - 1 {
 }
 ```
 
-Trying to access elements outside the range `0 to count - 1` will result in an error.
+To access elements relative to the end of the tuple, you can use negative indices. An index of `-1` is shorthand for `count - 1`:
+
+
+```swift
+define foo 1 2 3 4
+
+print foo[-1] // prints 4
+print foo[-2] // prints 3
+```
+
+Trying to access tuple elements outside the range `-count to count - 1` will result in an error, as will attempting to access a named member that does not exist. To avoid the error you can check if a given member exists by using the `in` operator, as follows:
+
+```swift
+define purple 0.6 0 1
+
+if "red" in purple {
+    print "the red value of purple is " purple["red"] // prints 0.6
+}
+```
 
 ---
 [Index](index.md) | Next: [Functions](functions.md)

docs/ios/literals.md

@@ -70,6 +70,35 @@ define size 1 2 3
 define myTuple2 "hello" 5.3 size
 ```
 
+Tuple values can be accessed by index using [ordinal members](expressions.md#members) or [subscripting](expressions.md#subscripting):
+
+```swift
+define size 1 2 3
+
+print size.second // prints 2
+print size[0] // prints 1
+```
+
+To check if a tuple contains a particular value, you can use the `in` operator:
+
+```swift
+define values 1 2 3
+
+if 2 in values {
+    print "values includes the number 2"
+}
+```
+
+You can also enumerate the values in a tuple using a [for loop](control-flow.md#looping-over-values):
+
+```swift
+define values 1 2 3
+
+for value in values {
+    print value // prints 1 2 3
+}
+```
+
 ## Structured Data
 
 As well as simple values like numbers and text, it can sometimes be useful to group together sets of related data. Tuples can be nested arbitrarily to create complex data structures:
@@ -213,11 +242,16 @@ define data object {
     height 10
     depth 15
 }
+```
+
+To access the members of an object you can either use the [dot operator](expressions.md#members) or [subscripting](expressions.md#subscripting):
 
+```swift
 print data.height // prints 10
+print data["height"] // also prints 10
 ```
 
-Objects can also be nested:
+Objects can be nested inside each other:
 
 ```swift
 define data object {
@@ -231,6 +265,21 @@ define data object {
 }
 
 print data.dimensions.height // prints 10
+print data["dimensions"]["height"] // also prints 10
+```
+
+Attempting to access a non-existent member of an object will cause an error. To check if an object contains a particular member before you try to access it, you can use the `in` operator:
+
+```swift
+define axes object {
+    x (1 0 0)
+    y (0 1 0)
+    z (0 0 1)
+}
+
+if "x" in axes {
+    print "axes object contains an x component"
+}
 ```
 
 To enumerate all the members of an object, you can use a [for loop](control-flow.md#looping-over-values). Each member is returned as a tuple of the key (member name) and value:
@@ -241,7 +290,7 @@ for row in data {
 }
 ```
 
-**Note:** object members are *unordered*, meaning that the order in which they are defined has no special significance. When looping through members of an object, the order will be alphabetical rather than the order in which the members were defined.
+**Note:** object members are *unordered*, meaning that the order in which they are defined has no special significance. When looping through members of an object, the order will be alphabetical rather than reflecting the order in which the members were defined.
 
 ---
 [Index](index.md) | Next: [Symbols](symbols.md)

docs/mac/expressions.md

@@ -197,6 +197,16 @@ for i in loops {
 }
 ```
 
+You can also use the `in` operator to check if a range contains a particular value:
+
+```swift
+define range 1 to 5
+
+if 2.5 in range {
+    print "range contains 2.5"
+}
+```
+
 **Note:** Ranges are inclusive of both the start and end values, so a loop from `0 to 5` would loop *6* times and not 5 as you might expect.
 
 Range values can be fractional and/or negative:
@@ -245,6 +255,17 @@ for i in 5 to 1 step -1 {
 }
 ```
 
+For stepped ranges, `in` will only return true for values that align with the steps:
+
+```swift
+define range 1 to 5 step 2
+
+print 1 in range // prints true
+print 2 in range // prints false
+print 2.5 in range // prints false
+print 3 in range // prints true
+```
+
 ## Members
 
 Compound values like [vectors and tuples](literals.md#vectors-and-tuples) and [objects](literals.md#objects) can be decomposed by using the *dot* operator to access individual components or *members*:
@@ -349,7 +370,25 @@ for i in 0 to foo.count - 1 {
 }
 ```
 
-Trying to access elements outside the range `0 to count - 1` will result in an error.
+To access elements relative to the end of the tuple, you can use negative indices. An index of `-1` is shorthand for `count - 1`:
+
+
+```swift
+define foo 1 2 3 4
+
+print foo[-1] // prints 4
+print foo[-2] // prints 3
+```
+
+Trying to access tuple elements outside the range `-count to count - 1` will result in an error, as will attempting to access a named member that does not exist. To avoid the error you can check if a given member exists by using the `in` operator, as follows:
+
+```swift
+define purple 0.6 0 1
+
+if "red" in purple {
+    print "the red value of purple is " purple["red"] // prints 0.6
+}
+```
 
 ---
 [Index](index.md) | Next: [Functions](functions.md)

docs/mac/literals.md

@@ -70,6 +70,35 @@ define size 1 2 3
 define myTuple2 "hello" 5.3 size
 ```
 
+Tuple values can be accessed by index using [ordinal members](expressions.md#members) or [subscripting](expressions.md#subscripting):
+
+```swift
+define size 1 2 3
+
+print size.second // prints 2
+print size[0] // prints 1
+```
+
+To check if a tuple contains a particular value, you can use the `in` operator:
+
+```swift
+define values 1 2 3
+
+if 2 in values {
+    print "values includes the number 2"
+}
+```
+
+You can also enumerate the values in a tuple using a [for loop](control-flow.md#looping-over-values):
+
+```swift
+define values 1 2 3
+
+for value in values {
+    print value // prints 1 2 3
+}
+```
+
 ## Structured Data
 
 As well as simple values like numbers and text, it can sometimes be useful to group together sets of related data. Tuples can be nested arbitrarily to create complex data structures:
@@ -213,11 +242,16 @@ define data object {
     height 10
     depth 15
 }
+```
+
+To access the members of an object you can either use the [dot operator](expressions.md#members) or [subscripting](expressions.md#subscripting):
 
+```swift
 print data.height // prints 10
+print data["height"] // also prints 10
 ```
 
-Objects can also be nested:
+Objects can be nested inside each other:
 
 ```swift
 define data object {
@@ -231,6 +265,21 @@ define data object {
 }
 
 print data.dimensions.height // prints 10
+print data["dimensions"]["height"] // also prints 10
+```
+
+Attempting to access a non-existent member of an object will cause an error. To check if an object contains a particular member before you try to access it, you can use the `in` operator:
+
+```swift
+define axes object {
+    x (1 0 0)
+    y (0 1 0)
+    z (0 0 1)
+}
+
+if "x" in axes {
+    print "axes object contains an x component"
+}
 ```
 
 To enumerate all the members of an object, you can use a [for loop](control-flow.md#looping-over-values). Each member is returned as a tuple of the key (member name) and value:
@@ -241,7 +290,7 @@ for row in data {
 }
 ```
 
-**Note:** object members are *unordered*, meaning that the order in which they are defined has no special significance. When looping through members of an object, the order will be alphabetical rather than the order in which the members were defined.
+**Note:** object members are *unordered*, meaning that the order in which they are defined has no special significance. When looping through members of an object, the order will be alphabetical rather than reflecting the order in which the members were defined.
 
 ---
 [Index](index.md) | Next: [Symbols](symbols.md)

docs/src/expressions.md

@@ -197,6 +197,16 @@ for i in loops {
 }
 ```
 
+You can also use the `in` operator to check if a range contains a particular value:
+
+```swift
+define range 1 to 5
+
+if 2.5 in range {
+    print "range contains 2.5"
+}
+```
+
 **Note:** Ranges are inclusive of both the start and end values, so a loop from `0 to 5` would loop *6* times and not 5 as you might expect.
 
 Range values can be fractional and/or negative:
@@ -245,6 +255,17 @@ for i in 5 to 1 step -1 {
 }
 ```
 
+For stepped ranges, `in` will only return true for values that align with the steps:
+
+```swift
+define range 1 to 5 step 2
+
+print 1 in range // prints true
+print 2 in range // prints false
+print 2.5 in range // prints false
+print 3 in range // prints true
+```
+
 ## Members
 
 Compound values like [vectors and tuples](literals.md#vectors-and-tuples) and [objects](literals.md#objects) can be decomposed by using the *dot* operator to access individual components or *members*:
@@ -349,7 +370,25 @@ for i in 0 to foo.count - 1 {
 }
 ```
 
-Trying to access elements outside the range `0 to count - 1` will result in an error.
+To access elements relative to the end of the tuple, you can use negative indices. An index of `-1` is shorthand for `count - 1`:
+
+
+```swift
+define foo 1 2 3 4
+
+print foo[-1] // prints 4
+print foo[-2] // prints 3
+```
+
+Trying to access tuple elements outside the range `-count to count - 1` will result in an error, as will attempting to access a named member that does not exist. To avoid the error you can check if a given member exists by using the `in` operator, as follows:
+
+```swift
+define purple 0.6 0 1
+
+if "red" in purple {
+    print "the red value of purple is " purple["red"] // prints 0.6
+}
+```
 
 ---
 [Index](index.md) | Next: [Functions](functions.md)