&ldel(4)

NAME

&ldel, &lfind, &lget, &linsert, &lset - List manipulation functions

SYNOPSIS

&ldel list index
&lfind list value
&lget list index
&linsert list index value
&llength list
&lset list index value

DESCRIPTION

The list manipulation functions perform operations on specially formatted strings called lists. A list is defined as:

"|value1|value2|.....|valueN|" 

Where '|' is the dividing character, this is not fixed to a '|', but is defined by the first character of the string. Following are all valid lists.

"|1|2|3|4|5|"
"X1X2X3X4X5X"
"\CAHello\CAWorld\CA"
"??"

The functions may all be abbreviated to their three letter abbreviation (i.e. &linsert may be expressed as &lin). In all cases the first argument is completely evaluated before the second or third argument.

&ldel list index


Creates a new list from deleting item index from list. If index is out of list's range (0 < index <= # items in list) then list is returned unchanged.

&lfind list value


Returns the index whose item is the same as value in list. If value is not found in list then "0" is returned.

&lget list index


Returns the value of item index in list. If index is out of list's range (0 < index <= # items in list) then an empty string is returned.

&linsert list index value


Creates a new list from inserting value into list at point index, thereby pushing item index to index+1 etc.

If index is 0, value is inserted at the beginning of the list.

If index is -2, value is inserted alphabetically (case sensitively) into the list.

If index is -3, value is inserted alphabetically (case insensitively) into the list.

Otherwise, if index is -1 or greater that the number of items in list then value is inserted at the end of the list.

&llength list


Returns the list length, i.e. the number of items in the given list.

&lset list index value


Creates a new list from setting index of list to value. If index is out of list's range (0 < index <= # items in list) then &lset behaves like &linsert and inserts alphabetically or at the end of the list.

EXAMPLE

The following example moves item 4 in a list to position 2:

set-variable #l0 &lget %list 4 
set-variable #l1 &ldel %list 4 
set-variable %list &lins #l1 2 #l0 

The following example is taken from vm.emf, it firstly checks where the user has entered a vm command, if not then the key is execute as normal, otherwise the appropriate vm command is executed.

define-macro vm-input 
    set-variable #l2 @cck 
    set-variable #l3 @cc 
    !if &not &set #l0 &lfi "|esc h|delete|space|return|A|a|C|c|....|z|" #l2 
        !if &not &seq #l3 "ERROR" 
            execute-line &spr "!nma %s %s" &cond @? @# "" #l3 
            !return 
        !endif 
        ml-write &spr "[Key \"%s\" not bound - \"esc h\" to view help]" #l2 
        !abort 
    !endif 
    set-variable #l1 &lget "|%osd-vm-help osd|vm-del-windows|scroll-down|.... 
                       ....vm-goto-list|vm-Archive-box|vm-archive-box|.... 
                       vm-cut-all-data|0 vm-extract-data|...|vm-forward|" #l0 
    execute-line #l1 
!emacro 

NOTES

An error will be thrown if a list function is given an empty sting as the list, this is because the character \x00 cannot be used as the separator char.

SEE ALSO

Variable Functions, &mid(4), &cat(4).

Ref: &ldel(4) File: m4fil029.4 Date: 2024/08/22

(c) Copyright JASSPA 2026