Index: doc/theses/mike_brooks_MMath/intro.tex
===================================================================
--- doc/theses/mike_brooks_MMath/intro.tex	(revision 12c4a5f72577b69d5e787a6ca7f1d2676aa5d014)
+++ doc/theses/mike_brooks_MMath/intro.tex	(revision 14c31ebd26aa18f5709bd1a20cc22b7424779f1c)
@@ -3,5 +3,5 @@
 All modern programming languages provide three high-level containers (collections): array, linked-list, and string.
 Often array is part of the programming language, while linked-list is built from (recursive) pointer types, and string from a combination of array and linked-list.
-For all three types, languages supply varying degrees of high-level mechanism for manipulating these objects at the bulk level and at the component level, such as array copy, slicing and iterating using subscripting.
+For all three types, languages and/or their libraries supply varying degrees of high-level mechanisms for manipulating these objects at the bulk and component level, such as copying, slicing, extracting, and iterating among elements.
 
 This work looks at extending these three foundational container types in the programming language \CFA, which is a new dialect of the C programming language.
@@ -10,43 +10,58 @@
 An equally important goal is balancing good performance with safety.
 
+The thesis describes improvements made to the \CFA language design, both syntax and semantics, to support the container features, and the source code created within the \CFA compiler, libraries, and runtime system to implement these features.
+This work leverages preexisting work within the compiler's type and runtime systems generated by prior graduate students working on the \CFA project.
+
 
 \section{Array}
+\label{s:ArrayIntro}
 
 An array provides a homogeneous container with $O(1)$ access to elements using subscripting.
-Higher-level operations like array slicing (single or multidimensional) may have significantly higher cost, but provides a better programmer experience.
+Higher-level operations like array slicing (single or multidimensional) may have significantly higher cost, but provide a better programmer experience.
 The array size can be static, dynamic but fixed after creation, or dynamic and variable after creation.
 For static and dynamic-fixed, an array can be stack allocated, while dynamic-variable requires the heap.
 Because array layout has contiguous components, subscripting is a computation (some form of pointer arithmetic).
 
-C provides an array as a language feature.
+C provides a simple array type as a language feature.
+However, it adopts the controversial language position of treating pointer and array as duals, leading to multiple problems.
+
 
 \section{Linked list}
 
 A linked-list provides a homogeneous container often with $O(log N)$ or $O(N)$ access to elements using successor and predecessor operations that normally involve pointer chasing.
-Subscripting by value is sometimes available, \eg hash table.
-Linked types are normally dynamically sized by adding/removing nodes using link fields internal or external to the elements (nodes).
-If a programming language allows pointer to stack storage, linked-list types can be allocated on the stack;
-otherwise, elements are heap allocated with explicitly/implicitly managed.
+Subscripting by value (rather than position or location as for array) is sometimes available, \eg hash table.
+Linked types are normally dynamically sized by adding and removing nodes using link fields internal or external to the elements (nodes).
+If a programming language allows pointers to stack storage, linked-list nodes can be allocated on the stack and connected with stack addresses (pointers);
+otherwise, elements are heap allocated with internal or external link fields.
 
-C does not provide a linked-list, either as an obvious commonly-accepted library, nor as an outright language feature.
-C programmers commonly build linked-list behaviours into their bespoke data structures, directly using its language feature of pointers.
+C provides a few simple, polymorphic, library data-structures (@glibc@):
+\begin{itemize}
+\item
+singly-linked lists, singly-linked tail queues, lists, and tail queues (@<sys/queue.h>@) \see{\VRef{s:PreexistingLinked-ListLibraries}}
+\item
+hash search table consisting of a key (string) with associated data (@<search.h>@)
+\end{itemize}
+Because these libraries are simple, awkward to use, and unsafe, C programmers commonly build linked-list behaviours into their bespoke data structures.
+
 
 \section{String}
 
 A string provides a dynamic array of homogeneous elements, where the elements are (often) some form of human-readable characters.
-What differentiates a string from other types in that many of its operations work on groups of elements for scanning and changing, \eg @index@ and @substr@;
-subscripting individual elements is usually available, too.
-Therefore, the cost of a string operation is usually less important than the power of the operation to accomplish complex text manipulation, \eg search, analysing, composing, and decomposing.
+What differentiates a string from other types in that many of its operations work on groups of elements for scanning and changing, \eg @index@ and @substr@.
+While subscripting individual elements is usually available, working at the individual character level is considered poor practise, \ie underutilizing the powerful string operations.
+Therefore, the cost of a string operation is usually less important than the power of the operation to accomplish complex text manipulation, \eg search, analysing, composing, and decomposing string text.
 The dynamic nature of a string means storage is normally heap allocated but often implicitly managed, even in unmanaged languages.
 In some cases, string management is separate from heap management, \ie strings roll their own heap.
 
-The C string type is a user-managed allocation of the language-provided character array,
-plus the convention of marking its (variable) length by placing the 0-valued control character at the end (``null-terminated'').
-The C standard library includes many operations for working on this representation.
+The C string type requires user storage-management of a language-provided character array.
+The character array uses the convention of marking its (variable) array length by placing the 0-valued control character at the end (null-terminated).
+The C standard library includes a number of high-level operations for working with this representation.
+
 
 \section{Iterator}
 
-As a side issue to working with complex structured types is iterating through them.
-Some thought has been given to \emph{general} versus specific iteration capabilities as part of of this work, but the general iteration work is only a sketch for others as future work.
+As a side issue to complex structured-types is iterating through them.
+Some thought has been given to \emph{general} versus specific iteration capabilities as part of of this work.
+However, the general iteration work is only a sketch for others as future work.
 Nevertheless, sufficed work was done to write out the ideas that developed and how they should apply in the main context of this work. 
 
@@ -61,5 +76,5 @@
 \item
 These three aspects of C cause the greatest safety issues because there are few or no safe guards when a programmer misunderstands or misuses these features~\cite{Elliott18, Blache19, Ruef19, Oorschot23}.
-Estimates suggest 50\%~\cite{Mendio24} of total reported open-source vulnerabilities occur in C resulting from errors using these facilities (memory errors), providing the major hacker attack-vectors.
+Estimates suggest 50\%~\cite{Mendio24} of total reported open-source vulnerabilities occurring in C result from errors using these facilities (memory errors), providing the major hacker attack-vectors.
 \end{enumerate}
 Both White House~\cite{WhiteHouse24} and DARPA~\cite{DARPA24} recently released a recommendation to move away from C and \CC, because of cybersecurity threats exploiting vulnerabilities in these older languages.
@@ -68,6 +83,6 @@
 
 While multiple new languages purport to be systems languages replacing C, the reality is that rewriting massive C code-bases is impractical and a non-starter if the new runtime uses garage collection.
-Furthermore, these languages must still interact with the underlying C operating system through fragile, type-unsafe, interlanguage-communication.
-Switching to \CC is equally impractical as its complex and interdependent type-system (\eg objects, inheritance, templates) means idiomatic \CC code is difficult to use from C, and C programmers must expend significant effort learning \CC.
+Furthermore, new languages must still interact with the underlying C operating system through fragile, type-unsafe, interlanguage-communication.
+Switching to \CC is equally impractical as its complex and interdependent type-system (\eg objects, overloading, inheritance, templates) means idiomatic \CC code is difficult to use from C, and C programmers must expend significant effort learning \CC.
 Hence, rewriting and retraining costs for these languages can be prohibitive for companies with a large C software-base (Google, Apple, Microsoft, Amazon, AMD, Nvidia).
 
@@ -79,82 +94,70 @@
 When it comes to explaining how C works, the definitive source is the @gcc@ compiler, which is mimicked by other C compilers, such as Clang~\cite{clang}.
 Often other C compilers must mimic @gcc@ because a large part of the C library (runtime) system (@glibc@ on Linux) contains @gcc@ features.
-While some key aspects of C need to be explained and understood by quoting from the language reference manual, to illustrate actual program semantics, this thesis uses constructs a program whose behaviour exercises a particular point and then confirms the behaviour by running the program.
+Some key aspects of C need to be explained and understood by quoting from the language reference manual.
+However, to illustrate actual program semantics, this thesis constructs multiple small programs whose behaviour exercises a particular point and then confirms the behaviour by running the program using multiple @gcc@ compilers.
 These example programs show
-\begin{itemize}[leftmargin=*]
+\begin{itemize}
 	\item if the compiler accepts or rejects certain syntax,
 	\item prints output to buttress a behavioural claim,
 	\item or executes without triggering any embedded assertions testing pre/post-assertions or invariants.
 \end{itemize}
-This work has been tested across @gcc@ versions 8--14 and clang versions 10--14 running on ARM, AMD, and Intel architectures.
-Any discovered anomalies among compilers or versions is discussed.
-In all case, it is never clear whether the \emph{truth} lies in the compiler(s) or the C standard.
+These programs are tested across @gcc@ versions 8--14 and clang versions 10--14 running on ARM, AMD, and Intel architectures.
+Any discovered anomalies among compilers, versions, or architectures is discussed.
+In general, it is never clear whether the \emph{truth} lies in the C standard or the compiler(s), which may be true for other programming languages.
 
 
 \section{Contributions}
 
-This work has produced significant syntactic and semantic improvements to C's arrays, linked-lists and string types.
+Overall, this work has produced significant syntactic and semantic improvements to C's arrays, linked-lists and string types.
 As well, a strong plan for general iteration has been sketched out.
+The following are the detailed contributions, where performance and safety were always the motivating factors.
 
-This thesis mainly describes improvements made to the source code of the \CFA compiler and runtime system,
-available at TODO.
+\subsection{Array}
 
-This work often leverages preexisting    xxxxxxxxxx
+This work's array improvements are:
+\begin{enumerate}[leftmargin=*]
+\item
+Introduce a small number of subtle changes to the typing rules for the C array, while still achieving significant backwards compatibility
+\item
+Create a new polymorphic mechanism into the \CFA @forall@ clause for specifying array dimension values, similar to a fixed-typed parameter in a \CC \lstinline[language=C++]{template}.
+\item
+Construct a new standard-library array-type, available through @#include <array.hfa>@.
+\end{enumerate}
+The new array type, enabled by prior features, defines an array with guaranteed runtime bound checks (often optimizer-removable) and implicit (guaranteed accurate) inter-function length communication.
+Leveraging the preexisting \CFA type-system to achieve this length-related type checking is an original contribution.
+Furthermore, the new array incorporates multidimensional capabilities typical of scientific/machine-learning languages, made to coexist with the C raw-memory-aware tradition in a novel way.
+The thesis includes a performance evaluation that shows \CFA arrays perform comparably with C arrays in many programming cases.
+
 
 \subsection{Linked list}
 
-The linked list is a new runtime library, available as @#include <dlist.hfa>@.
-The library offers a novel combination of the preexisting \CFA features of:
-references, inline inheritance, polymorphism and declaration scoping.
-A programmer's experience of the list datatype within the type system is novel.
-The list's runtime representation follows the established design pattern of intrusion.
-This thesis includes a performance evaluation that shows
-the list performing comparably with other C-family intrusive lists,
-and notably better than the \CC standard list.
+The linked list is a new runtime library, available through @#include <dlist.hfa>@.
+The library offers a novel combination of the preexisting \CFA features: references, inline inheritance, polymorphism, and declaration scoping.
+A programmer's experience using the list data-types within the type system is novel.
+The list's runtime representation follows the established design pattern of intrusive link-fields for performance reasons, especially in concurrent programs.
+The thesis includes a performance evaluation that shows the list performing comparably with other C-family intrusive lists, and notably better than the \CC standard list.
 
-\subsection{Array}
-
-This work's array improvements are
-\begin{enumerate}[leftmargin=*]
-\item
-subtle changes to the typing rules for the C array,
-\item
-a new \CFA language construct for a type-system managed array length, and
-\item
-a new standard-library array type, available as @#include <array.hfa>@.
-\end{enumerate}
-The new array type, enabled by the earlier features, defines an array with
-guaranteed runtime bound checks (often optimizer-removable) and
-implicit (guaranteed accurate) inter-function length communication.
-Leveraging the preexisting \CFA type system to achieve
-this length-related type checking is an original contribution.
-
-Furthermore, the new array incorporates multidimensional capabilities
-typical of scientific/machine-learning languages,
-made to coexist with the C ``raw-memory-aware'' tradition in a novel way.
 
 \subsection{String}
 
-The string is a new runtime library, available as @#include <string.hfa>@.
-The library offers a type whose basic usage is comparable to the \CC @string@ type,
-including analogous coexistence with raw character pointers.
-Its implementation, however, follows different princliples,
-enabling programs to work with strings by value, without incurring excessive copying.
+The string is a new runtime library, available through @#include <string.hfa>@.
+The library offers a type where basic usage is comparable to the \CC @string@ type, including analogous coexistence with raw-character pointers.
+Its implementation, however, follows different principles, enabling programs to work with strings by value, without incurring excessive copying.
 Mutability is retained.
 Substrings are supported, including the ability for overlapping ranges to share edits transparently.
-Ultimately, this implementation is a case of strings rolling their own heap.
+Ultimately, the implementation is a set of strings rolled into their own specialized heap.
 
-The string library includes writing and reading strings via the preexsiting \CFA I/O stream library.
-Enabling transparent reading (of unknown length into a managed allocation) included revision of
-the stream libarary's existing handling of character arrays.
+The string library includes writing and reading strings via the preexisting \CFA I/O stream library.
+Enabling transparent reading (of unknown length into a managed allocation) included revision of the stream library's existing handling of character arrays.
+All reasonable stream manipulators are supported, \eg width, justification (left/right), printing characters as their numeric values, and complex input scanning to isolate strings.
+
 
 \subsection{Iterator}
 
-Some prototyping, available in the \CFA standard library,
-addresses the infamous \CC bug source of iterator invalidation.
-A family of iterator styles is presented, with cheap iterators that resist being misused,
-plus full-featured iterators that observe modifications without becoming invalid.
+Some advanced iterator prototyping now exists, available in the \CFA standard library.
+Specifically, a family of iterator styles is provided, with cheap iterators that are robust to being misused, plus full-featured iterators that observe structural modifications without becoming invalid.
+Hence, the infamous \CC bug of iterator invalidation, where structural changes cause legitimate operations to fail, \eg iterator over a list and deleting each element.
 
-Further design within this thesis presents a home for Liskov-style iterators in \CFA.
-This design extends a preexisting proposal to adapt the \CFA for-each style loop to be more user-pluggable.
-It also builds upon preexisting \CFA coroutines.
-It simplifies the work a programmer must do to leverage the suspended-state abstraction.
+Further design provides a home for Liskov-style iterators in \CFA.
+This design extends a preexisting proposal to adapt the \CFA (fixed) for-each loop to be more user-pluggable, and builds upon preexisting \CFA coroutines.
+Overall, it simplifies the work a programmer must do to leverage the suspended-state abstraction during iteration.
Index: doc/theses/mike_brooks_MMath/programs/bkgd-carray-arrty.c
===================================================================
--- doc/theses/mike_brooks_MMath/programs/bkgd-carray-arrty.c	(revision 12c4a5f72577b69d5e787a6ca7f1d2676aa5d014)
+++ doc/theses/mike_brooks_MMath/programs/bkgd-carray-arrty.c	(revision 14c31ebd26aa18f5709bd1a20cc22b7424779f1c)
@@ -57,11 +57,11 @@
 	f( &ar );
 
-	float fs[] = {3.14, 1.77};
-	char cs[] = "hello";
+	float fs@[]@ = {3.14, 1.77};
+	char cs@[]@ = "hello";    // shorthand for 'h', 'e', 'l', 'l', 'o', '\0'
 	static_assert( sizeof(fs) == 2 * sizeof(float) );
 	static_assert( sizeof(cs) == 6 * sizeof(char) );  $\C{// 5 letters + 1 null terminator}$
 
-	float fm[][2] = { {3.14, 1.77}, {12.4, 0.01}, {7.8, 1.23} };  $\C{// brackets define structuring}$
-	char cm[][sizeof("hello")] = { "hello", "hello", "hello" };
+	float fm[]@[2]@ = { {3.14, 1.77}, {12.4, 0.01}, {7.8, 1.23} };  $\C{// brackets define structuring}$
+	char cm[]@[sizeof("hello")]@ = { "hello", "hello", "hello" };
 	static_assert( sizeof(fm) == 3 * 2 * sizeof(float) );
 	static_assert( sizeof(cm) == 3 * 6 * sizeof(char) );
