Add array_end() built-in (#1266)

Author: Akuli

compiler/ast.jou

@@ -255,7 +255,8 @@ enum AstExpressionKind:
     EnumCount
     # unary operators
     SizeOf          # sizeof(x)
-    ArrayCount      # array_count x
+    ArrayCount      # array_count(x)
+    ArrayEnd        # array_end(x)
     EmbedFile       # embed_file("./foo.bar")
     AddressOf       # &x
     Dereference     # *x
@@ -368,6 +369,8 @@ class AstExpression:
                 printf("embed_file\n")
             case AstExpressionKind.ArrayCount:
                 printf("array_count\n")
+            case AstExpressionKind.ArrayEnd:
+                printf("array_end\n")
             case AstExpressionKind.AddressOf:
                 printf("address of\n")
             case AstExpressionKind.Dereference:
@@ -466,6 +469,7 @@ class AstExpression:
                 AstExpressionKind.SizeOf
                 | AstExpressionKind.EmbedFile
                 | AstExpressionKind.ArrayCount
+                | AstExpressionKind.ArrayEnd
                 | AstExpressionKind.AddressOf
                 | AstExpressionKind.Dereference
                 | AstExpressionKind.Negate

compiler/builders/ast_to_builder.jou

@@ -487,6 +487,13 @@ class AstToBuilder:
                 array_type = expr.operands[0].types.implicit_cast_type
                 assert array_type.kind == TypeKind.Array
                 return self.builder.integer(int_type(32), array_type.array.count)
+            case AstExpressionKind.ArrayEnd:
+                array_type = expr.operands[0].types.implicit_cast_type
+                assert array_type.kind == TypeKind.Array
+                ptr_to_array = self.build_address_of_expression(&expr.operands[0])
+                ptr_to_start = self.builder.cast(ptr_to_array, array_type.array.item_type.pointer_type())
+                count = self.builder.integer(int_type(64), array_type.array.count)
+                return self.builder.indexed_pointer(ptr_to_start, count)
             case AstExpressionKind.AddressOf:
                 return self.build_address_of_expression(&expr.operands[0])
             case AstExpressionKind.Dereference:

compiler/parser.jou

@@ -688,12 +688,15 @@ class Parser:
             case "array_count":
                 expr.kind = AstExpressionKind.ArrayCount
                 error = "value after array_count must be in parentheses, e.g. array_count(foo)"
-            case "enum_count":
-                expr.kind = AstExpressionKind.EnumCount
-                error = "enum type after enum_count must be in parentheses, e.g. enum_count(Foo)"
+            case "array_end":
+                expr.kind = AstExpressionKind.ArrayEnd
+                error = "value after array_end must be in parentheses, e.g. array_end(foo)"
             case "embed_file":
                 expr.kind = AstExpressionKind.EmbedFile
                 error = "file name after embed_file must be in parentheses, e.g. embed_file(\"foo.txt\")"
+            case "enum_count":
+                expr.kind = AstExpressionKind.EnumCount
+                error = "enum type after enum_count must be in parentheses, e.g. enum_count(Foo)"
             case _:
                 assert False
 
@@ -767,6 +770,7 @@ class Parser:
                 elif (
                     self.tokens.is_keyword("sizeof")
                     or self.tokens.is_keyword("array_count")
+                    or self.tokens.is_keyword("array_end")
                     or self.tokens.is_keyword("embed_file")
                     or self.tokens.is_keyword("enum_count")
                 ):

compiler/tokenizer.jou

@@ -34,6 +34,7 @@ def is_keyword(word: byte*) -> bool:
                 or strcmp(word, "as") == 0
                 or strcmp(word, "assert") == 0
                 or strcmp(word, "array_count") == 0
+                or strcmp(word, "array_end") == 0
             )
         case 'b':
             return (

compiler/typecheck/step3_function_and_method_bodies.jou

@@ -60,6 +60,8 @@ def short_expression_description(expr: AstExpression*) -> byte[200]:
             return "a sizeof expression"
         case AstExpressionKind.ArrayCount:
             return "an array_count expression"
+        case AstExpressionKind.ArrayEnd:
+            return "an array_end expression"
         case AstExpressionKind.EmbedFile:
             return "an embed_file expression"
         case AstExpressionKind.EnumCount:
@@ -1178,6 +1180,13 @@ def typecheck_expression(state: State*, expr: AstExpression*, type_hint: Type*)
                 fail(expr.location, msg)
             result = int_type(32)
 
+        case AstExpressionKind.ArrayEnd:
+            array_type = typecheck_expression_not_void(state, &expr.operands[0], NULL)
+            if array_type.kind != TypeKind.Array:
+                snprintf(msg, sizeof(msg), "array_end must be called on an array, not %s", array_type.name)
+                fail(expr.location, msg)
+            result = array_type.array.item_type.pointer_type()
+
         case AstExpressionKind.Instantiate:
             result = typecheck_instantiation(state, &expr.instantiation, expr.location)
 

doc/keywords.md

@@ -43,6 +43,39 @@ def main() -> int:
 ```
 
 
+## `array_end`
+
+Use `array_end(array)` to get a pointer just beyond the last element of an array.
+This is same as `&array[array_count(array)]`.
+
+For example:
+
+```python
+import "stdlib/io.jou"
+
+def main() -> int:
+    array = [1, 2, 3, 4]
+    printf("%d\n", array_end(array)[-1])  # Output: 4
+    return 0
+```
+
+The most common use for `array_end()` is [looping through an array](loops.md#looping-through-an-array) with pointers:
+
+```python
+import "stdlib/io.jou"
+
+def main() -> int:
+    array = [1, 2, 3, 4]
+    # Output: 1
+    # Output: 2
+    # Output: 3
+    # Output: 4
+    for p = &array[0]; p < array_end(array); p++:
+        printf("%d\n", *p)
+    return 0
+```
+
+
 ## `as`
 
 The `as` keyword does an explicit cast. See [the documentation on casts](types.md#casts).

doc/loops.md

@@ -253,7 +253,7 @@ def main() -> int:
     return 0
 ```
 
-Looping through an array with pointers:
+Looping through an array with pointers (see [`array_end` documentation](keywords.md#array_end)):
 
 ```python
 import "stdlib/io.jou"
@@ -264,7 +264,7 @@ def main() -> int:
     # Output: 123
     # Output: 456
     # Output: 789
-    for p = &array[0]; p < &array[array_count(array)]; p++:
+    for p = &array[0]; p < array_end(array); p++:
         printf("%d\n", *p)
 
     return 0
@@ -304,6 +304,24 @@ def main() -> int:
     return 0
 ```
 
+Instead of `&array[array_count(array) - 1]`, you can also use `&array_end(array)[-1]`.
+This may be convenient, because you need to write `array` only once.
+
+```python
+import "stdlib/io.jou"
+
+def main() -> int:
+    array = [123, 456, 789]
+
+    # Output: 789
+    # Output: 456
+    # Output: 123
+    for p = &array_end(array)[-1]; p >= &array[0]; p--:
+        printf("%d\n", *p)
+
+    return 0
+```
+
 If you don't use all elements of the array, and you instead store the number of used elements in a variable,
 you can use that instead of `array_count(array)` above.
 For example:

tests/other_errors/assign_to_array_end.jou

@@ -0,0 +1,3 @@
+def blah() -> None:
+    x: int[10]
+    array_end(x) = &x[20]  # Error: cannot assign to an array_end expression

tests/should_succeed/array.jou

@@ -53,6 +53,24 @@ def main() -> int:
     increment(foo as int*)  # same cast explicitly
     printf("%d %d %d\n", foo[0], foo[1], foo[2])  # Output: 7 5 6
 
+    # Looping through array with indexes
+    # Output: 756
+    for i = 0; i < array_count(foo); i++:
+        printf("%d", foo[i])
+    printf("\n")
+
+    # Looping through array with pointers (old way)
+    # Output: 756
+    for p = &foo[0]; p < &foo[array_count(foo)]; p++:
+        printf("%d", *p)
+    printf("\n")
+
+    # Looping through array with pointers (new way)
+    # Output: 756
+    for p = &foo[0]; p < array_end(foo); p++:
+        printf("%d", *p)
+    printf("\n")
+
     # corner case: byte* <--> void* can be converted both ways, use byte*
     strings = ["hello", NULL, "world", NULL]
     printf("%s %s\n", strings[0], strings[2])  # Output: hello world

tests/should_succeed/math_test.jou

@@ -50,7 +50,7 @@ def main() -> int:
     # Output: 0 0 1
     # Output: 0 0 1
     # Output: 0 0 1
-    for d = &test_doubles[0]; d < &test_doubles[array_count(test_doubles)]; d++:
+    for d = &test_doubles[0]; d < array_end(test_doubles); d++:
         printf("%d %d %d\n", isfinite(*d), isinf(*d), isnan(*d))
 
     # Output: 1 0 0
@@ -65,7 +65,7 @@ def main() -> int:
     # Output: 0 0 1
     # Output: 0 0 1
     # Output: 0 0 1
-    for d = &test_doubles[0]; d < &test_doubles[array_count(test_doubles)]; d++:
+    for d = &test_doubles[0]; d < array_end(test_doubles); d++:
         printf("%d %d %d\n", isfinite(*d as float), isinf(*d as float), isnan(*d as float))
 
     printf("%d\n", abs(-1)) # Output: 1