Changeset 80018f5 for doc

Timestamp:

Dec 16, 2024, 5:59:04 PM (41 hours ago)

Author:

Andrew Beach <ajbeach@…>

Branches:

master

Children:

262a864

Parents:

4167afa

Message:

Attempted to inject some examples (and some other pieces I had missed) into the enum proposal.

File:

• doc/proposals/enums.md (modified) (6 diffs)

doc/proposals/enums.md

@@ -8 +8 @@
 --------------
 Because Cforall enumerations are encoded using their position, it can be
-difficult to give them a stable encoding. The
+difficult to give them a stable encoding, this is important in seperate
+compilation.
 
 The example (provided by Gregor Richards), is a system header that defines
@@ -42 +43 @@
 (instead of a subset of int) is used in the index operation.
 
+```cfa
+enum() Colour {
+  Red,
+  Violet,
+  Blue,
+  Green
+  Yellow,
+  Orange,
+};
+
+// Declare an array with an index of an enumeration:
+int jarsOfPaint[Colour] = {0};
+
+// Index the array:
+printf("I have %d jars of blue paint.\n", jarsOfPaint[Blue]);
+jarsOfPaint[Green] = 3;
+jarsOfPaint[Red] += 1;
+
+// Use the function for higher order programming:
+int (*lookup)(int collection[Colour], Colour key) = ?[?];
+
+// ERROR! Use the enumeration index for safety:
+jarsOfPaint[0] = 0;
+```
+
 Although described differently, this is actually a generalization of typed
 enumerations, as it can be used to safely represent a constant of any type
@@ -80 +106 @@
 Or one of the new safer Cforall arrays, as the features could be combined.
 
-(Previously, a compined declaration to declare both an enumeration and
+(Previously, a combined declaration to declare both an enumeration and
 an enumerated array was proposed. That only covers the simple case that
 typed enumerations already cover.)
@@ -90 +116 @@
 generalized to work with the other features of ranges, such as going over
 just part of the enumeration (see Ranges in doc/proposals/iterators.md).
+
+This will work best with some alias labels that mark out the beginning of
+ranges. That is the ranges within the enum will often have to be an
+intended part of the interface.
+
+```cfa
+for ( kind : DataKind.BeginIntegers +~ DataKind.EndIntegers ) { ... }
+```
+
+Writing the declaration is a bit tricker, because of the lack of aliasing,
+but this should echo a common C pattern.
 
 Flag Set Enumerations
@@ -111 +148 @@
 ```
 
+Some example usages:
+```cfa
+// If it is exactly Up/Upwards, then set exactly Down
+if ( Upwards == dirs ) {
+  dirs = Down
+// Otherwise, if a vertical is set, unset them:
+} else if ( Vertical & dirs ) {
+  dirs = dirs & ~Vertical;
+// Otherwise, if any direction is set then also set Up:
+} else if ( dirs ) {
+  dirs |= Up;
+}
+```
+
 Uses the existing enumeration syntax, except that all initializers must be
 bitwise expressions, using only the operators |, & and ~ and, as leaf values,
@@ -132 +183 @@
 
 Note: Scoping rules are also waiting on the namespacing and module system.
+
+Feature (and Storage) Control
+-----------------------------
+Right now features are very coursely grouped. You have exactly three options
+for your enumeration. However since there are more than two features this
+means there are some combinations you cannot have.
+
+For instance, labels (which are mostly useful for generating debug output)
+are not available for C style enum, but for both of the new Cforall enums,
+opaque and typed. However, there is no innate connection between the
+additional type safety of the opaque enum or the associated values/payloads
+of the typed enums.
+
+Enumerations do interact with on feature that shows this orthagonality,
+and that is the scoping "no export" marker, that can be applied to any
+enumeration to change the visibility rules of the enumeration and does not
+change anything else.
+
+This is not urgent, just not using the features you don't want is almost as
+clear and the compile-time, binary-size and runtime costs are all good enough
+for now (and some day all of those may have to be improved even when the
+feature is being used). Isolating independent features is just good design.