I6 Template Layer

KOV Support.

See the BlockValues.i6t segment for the specification of the following routines.

Creation.

Lists are by default created empty but in a block-value with enough capacity to hold 25 items, this being what's left in a 32-word block once all overheads are taken care of: 4 words are consumed by the header, then 2 more by the list metadata entries below.

Destruction.

If the list items are themselves block-values, they must all be freed before the list itself can be freed.

Copying.

Again, if the list contains block-values then they must be duplicated rather than bitwise copied as pointers.

Note that we use the pre-copy stage to remember the kind of value stored in the list. Type-checking will make sure this isn't abused: cases where it's important include copying the empty list into a list of rooms (it should not as a result acquire the kind "list of values"), or copying a list of people into a list of things (which should remain a list of things.)

Comparison.

Lists of a given kind of value are always grouped together, in this comparison: but the effect of that is unlikely to be noticed since NI's type-checker will probably prevent comparisons of lists of differing items in any case. The next criterion is length: a short list precedes a long one. Beyond that, we use the list's own preferred comparison function to judge the items in turn, stopping as soon as a pair of corresponding items differs: thus we sort lists of equal size in lexicographic order.

Since the comparison function depends only on the KOV, it may seem wasteful of a word of memory to store it in the list, given that we are already storing the KOV in any case. But we do this because comparisons have to be fast: we don't want to incur the overhead of translating KOV to comparison function.

Hashing.

Printing.

Unusually, this function can print the value in one of several formats: 0 for a comma-separated list; 1 for a braced, set-notation list; 2 for a comma-separated list with definite articles, which only makes sense if the list contains objects; 3 for a comma-separated list with indefinite articles. Note that a list in this sense is not printed using the ListWriter.i6t code for elaborate lists of objects, and it doesn't use the "listing contents of..." activity in any circumstances.

List From Description.

That completes the compulsory services required for this KOV to function: from here on, the remaining routines provide definitions of stored action-related phrases in the Standard Rules.

Given a description D which applies to some objects and not others – say, "lighted rooms adjacent to the Transport Hub" – we can cast this into a list of all objects satisfying D with the following routine. Slightly wastefully of time, we have to iterate through the objects twice in order first to work out the length of list we will need, and then to transcribe them.

Find Item.

We test whether a list list includes a value equal to v or not. Equality here is in the sense of the list's comparison function: thus for texts or other lists, say, deep comparisons rather than simple pointer comparisons are performed. In other words, one copy of "Alert" is equal to another.

Insert Item.

The following routine inserts an item into the list. If this would break the size of the current block-value, then we extend by at least enough room to hold at least another 16 entries.

In the call LIST_OF_TY_InsertItem(list, v, posnflag, posn, nodups), only the first two arguments are compulsory. (a) If nodups is set, and an item equal to v is already present in the list, we return and do nothing. (nodups means "no duplicates".) (b) Otherwise, if posnflag is false, we append a new entry v at the back of the given list. (c) Otherwise, when posnflag is true, posn indicates the insertion position, from 1 (before the current first item) to N+1 (after the last), where N is the number of items in the list at present.

Append List.

Instead of adjoining a single value, we adjoin an entire second list, which must be of a compatible kind of value (something which NI's type-checking machinery polices for us). Except that we have a list more rather than a value v to insert, the specification is the same as for LIST_OF_TY_InsertItem.

Remove Value.

We remove every instance of the value v from the given list. If the optional flag forgive is set, then we make no complaint if no value of v was present in the first place: otherwise, we issue a run-time problem.

Note that if the list contains block-values then the value must be properly destroyed with BlkValueFree before being overwritten as the items shuffle down.

Remove Item Range.

We excise items from to to from the given list, which numbers its items upwards from 1. If the optional flag forgive is set, then we truncate a range overspilling the actual list, and we make no complaint if it turns out that there is then nothing to be done: otherwise, in either event, we issue a run-time problem.

Once again, we destroy any block-values whose pointers will be overwritten as the list shuffles down to fill the void.

Remove List.

We excise all values from the removal list rlist, wherever they occur in list. Inevitably, given that we haven't sorted these lists and can spare neither time nor storage to do so, this is an expensive process with a running time proportional to the product of the two list sizes: we accept that as an overhead because in practice the rlist is almost always small in real-world use.

If the initial lists were disjoint, so that no removals occur, we always forgive the user: the request was not necessarily a foolish one, it only happened in this situation to be unhelpful.

Get Length.

Set Length.

This is rather harder: it might lengthen the list, in which case we have to pad out with the default value for the kind of value stored – padding a list of numbers with 0s, a list of texts with copies of the empty text, and so on – creating such block-values as might be needed; or else it might shorten the list, in which case we must cut items, destroying them properly if they were block-values.

LIST_OF_TY_SetLength(list, newsize, this_way_only, truncation_end) alters the length of the given list to newsize. If this_way_only is 1, the list is only allowed to grow, and nothing happens if we have asked to shrink it; if it is -1, the list is only allowed to shrink; if it is 0, the list is allowed either to grow or shrink. In the event that the list does have to shrink, entries must be removed, and we remove from the end if truncation_end is 1, or from the start if it is -1.

Get Item.

Write Item.

The slightly odd name for this function comes about because our usual way to convert an rvalue such as LIST_OF_TY_GetItem(L, 4) is to prefix Write, so that it becomes WriteLIST_OF_TY_GetItem(L, 4).

Put Item.

Higher-level code should not use Write_LIST_OF_TY_GetItem, because it does not properly keep track of block-value copying: the following should be used instead.

Multiple Object List.

The parser uses one data structure which is really a list: but which can't be represented as such because the heap might not exist. This is the multiple object list, which is used to handle commands like TAKE ALL by firing off a sequence of actions with one of the objects taken from entries in turn of the list. The following converts it to a list structure.

Reversing.

Reversing a list is, happily, a very efficient operation when the list contains block-values: because the pointers are rearranged but none is duplicated or destroyed, we can for once ignore the fact that they are pointers to block-values and simply move them around like any other data.

Rotation.

The same is true of rotation. Here, "forwards" rotation means towards the end of the list, "backwards" means towards the start.

Sorting.

And the same, again, is true of sorting: but we do have to take note of block values when it comes to performing comparisons, because we can only compare items in the list by looking at their contents, not the pointers to their contents.

LIST_OF_TY_Sort(list, dir, prop) sorts the given list in ascending order if dir is 1, in descending order if dir is -1, or in random order if dir is 2. The comparison used is the one for the kind of value stored in the list, unless the optional argument prop is supplied, in which case we sort based not on the item values but on their values for the property prop. (This only makes sense if the list contains objects.)