fieldIndex (schema itemName -- ordinal)

Builtins

Name introduction, declaration modifiers, and module binding: NAME: ...;, codeRef, def, exportFunction, importFunction, importVariable, overload, private, static, use, and virtual.
Struct construction forms: (...), {...}, and array.
Selection forms: source-text selection with NAME and .NAME, read-only source-text selection with @NAME and .@NAME, and ordinal or known-name data-input selection with @, callField, and fieldRead.
Writing forms: source-text selection with !NAME and .!NAME, ordinal selection with ! and fieldWrite, and already-selected destination replacement with set.
Calling and control flow: call, if, loop, ucall, and uif.
Text operations: &, LF, attribute, textSize, and textSplit.
Condition constants, value comparison, and logical operators: <, =, >, DEBUG, FALSE, TRUE, and, is, lshift, or, rshift, xor, and ~.
Arithmetic and numeric transforms: *, +, -, /, ^, cast, ceil, cos, floor, log, log10, mod, neg, sin, and sqrt.
Reference, creation, and value-state operations: const, dynamic, isConst, isDirty, isDynamic, isRef, isStatic, known?, new, newVarOfTheSameType, stable?, unconst, and unknownStable?.
Schema and struct introspection: code?, codeRef?, fieldCount, fieldIndex, fieldIsRef, fieldIsVirtual, fieldName, has, isCombined, managed?, same, schemaName, and virtual?.
Storage and manual lifetime operations: addressToReference, alignment, manuallyDestroyVariable, manuallyInitVariable, storageAddress, and storageSize.
Diagnostics and compile-time failure: failCompilation, getCallTrace, printCompilerMessage, printStack, printStackTrace, and raiseStaticError.

fieldIndex (schema itemName -- ordinal)

Inputs

schema: Value or Ref whose dereferenced schema is Struct and whose item names are searched by itemName.

itemName: Known non-NIL Text item name used for selection.

Outputs

ordinal: Known Int32 ordinal of the selected item.

Returns the selected item ordinal for a known, non-NIL Text item name in the dereferenced Struct schema.

Only the schema participates. Current value contents do not participate.

fieldIndex follows last-match name-selection rules. It therefore returns one selected ordinal, not every matching ordinal. A successful result is always a valid selected-item ordinal in the range 0 through itemCount - 1.

For Dict, that selected ordinal matches the same last-match field rule used by name-based field selection. Use fieldName to preserve the exact stored name at one ordinal and has for presence-only testing.

Behavior

For Dict, the last item whose name matches itemName is selected.

For Dict, the empty name "" also matches unnamed items and selects the last unnamed item when one is present.

For List and Tuple, only the empty name "" is valid, and it selects the last item.

For an empty List or Tuple, no name is valid, including "".

Repeated names and empty names may correspond to multiple ordinals, but the builtin always selects only one ordinal: the last matching item.

If no matching item exists, the builtin raises a compilation error.

Example

{} 0 {} [ mixed: { 1 "" def 2 "" def 3 "x" def 4 "x" def }; "-- fieldIndex returns the last match --" printCompilerMessage virtual emptyKey: mixed "" fieldIndex; emptyKey printStack _:; mixed emptyKey fieldName printStack _:; virtual xKey: mixed "x" fieldIndex; xKey printStack _:; mixed xKey fieldName printStack _:; "-- earlier matches still exist --" printCompilerMessage mixed fieldCount printStack _:; mixed 0 fieldName printStack _:; mixed 2 fieldName printStack _:; "-- Tuple unnamed item --" printCompilerMessage virtual tupleKey: (1 FALSE) "" fieldIndex; tupleKey printStack _:; (1 FALSE) tupleKey fieldName printStack _:; 0 ] "main" exportFunction

Expected Output During Compilation

-- fieldIndex returns the last match -- 1 "" 3 "x" -- earlier matches still exist -- 4 "" "x" -- Tuple unnamed item -- 1 ""