Looking at the Glulx specification section 2.16 Searching, it mentions that search opcodes can sometimes use options, one of which is ReturnIndex:
ReturnIndex (0x04): This flag indicates that search should return the array index of the structure that it finds, or -1 (0xFFFFFFFF) for failure. If this flag is not used, the search returns the address of the structure that it finds, or 0 for failure.
The specification for the @linkedsearch opcode says:
linkedsearch L1 L2 L3 L4 L5 L6 S1
L1: Key
L2: KeySize
L3: Start
L4: KeyOffset
L5: NextOffset
L6: Options
S1: Result
The structures need not be consecutive; they may be anywhere in memory, in any order. They are linked by a four-byte address field, which is found in each struct at position NextOffset. If this field contains zero, it indicates the end of the linked list.
The KeyIndirect and ZeroKeyTerminates options may be used.
The ReturnIndex flag is specifically not listed; I assume that this is intentional. Is there some technical reason that this option is omitted for @linkedsearch?
As best I can reconstruct my thinking, an index number would be useless because there’s no array to index into. You always want the structure address.
I think I understand. However, I was thinking in terms of “index” meaning “ordinal number of the entry in the linked list” and not “offset from Start parameter to locate the entry”, so I’m not sure that I understand.
In the case of @linearsearch and @binarysearch, both of which allow ReturnIndex to be used, what is the meaning of the return value in those cases? In other words, if R is the return value when ReturnIndex is used, is the idea that you would go on to use R via
Start+R
because R means the offset from Start, or
Start+((R-1)*StructSize)
because R means the 1-indexed ordinal position of the entry?
(Instead of either of the above, one could just omit ReturnIndex to get the target address in the first place, but I’m asking because I want to make sure that I understand what the return result is supposed to mean.)