# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1245019225 -7200
# Node ID f6f367f0005e0f727097946175cba75780543f2d
# Parent  2f452a4c223043198f404f388f16cbe8f3f02825
Added notes about list and tuple representations.

diff -r 2f452a4c2230 -r f6f367f0005e docs/concepts.txt
--- a/docs/concepts.txt	Sun Jun 14 23:17:22 2009 +0200
+++ b/docs/concepts.txt	Mon Jun 15 00:40:25 2009 +0200
@@ -10,6 +10,7 @@
   * Parameters and lookups
   * Instantiation
   * Register usage
+  * List and tuple representations
 
 Namespaces and Attribute Definition
 ===================================
@@ -498,3 +499,34 @@
 storage locations are typically employed. However, optimisations may reduce
 the need to use such temporary storage where instructions which provide the
 "active value" can be re-executed and will produce the same result.
+
+List and Tuple Representations
+==============================
+
+Since tuples have a fixed size, the representation of a tuple instance is
+merely a header describing the size of the entire object, together with a
+sequence of references to the object "stored" at each position in the
+structure. Such references consist of the usual context and reference pair.
+
+Lists, however, have a variable size and must be accessible via an unchanging
+location even as more memory is allocated elsewhere to accommodate the
+contents of the list. Consequently, the representation must resemble the
+following:
+
+    Structure header for list (size == header plus special attribute)
+    Special attribute referencing the underlying sequence
+
+The underlying sequence has a fixed size, like a tuple, but may contain fewer
+elements than the size of the sequence permits:
+
+    Special header indicating the current size and allocated size
+    Element
+    ...             <-- current size
+    (Unused space)
+    ...             <-- allocated size
+
+This representation permits the allocation of a new sequence when space is
+exhausted in an existing sequence, with the new sequence address stored in the
+main list structure. Since access to the contents of the list must go through
+the main list structure, underlying allocation activities may take place
+without the users of a list having to be aware of such activities.