PCE version 4C man_modulenamespaceid_tablemodified current_idOIxN class/chainN referenceC hash_tablerefersizeOIxNbothI5sNM.chain.S.beforeCman_method_card identifiermodule last_modifiednamesummary descriptionsee_alsoinherit diagnosticsdefaultsbugsOIxNM.chain.S.beforeRICdateOIx,}E“NbeforenCstringOIxƒSucceeds if the first occurrence of the first argument is before the first occurrence of the second argument. See `chain ->after'.CchainsizeOIxIeNM.chain.S.move_beforeENM.chain.S.afterXnnnnsNM.chain.S.move_beforeOIxNM.chain.S.move_beforeRIOIx- šN move_beforenOI xRMove the first member of the chain to be just before the second. Fails if either of the elements is not a ->member or they are equal. To move an element to the start of the chain, you may use either of: ?- ignore(send(Ch, move_before, Element, Ch?head)). ?- send(Ch, move_after, Element). See also ->move_after, ->before and ->after.OI xIeNM.chain.S.inserteNM.chain.S.beforeeNM.chain.S.insert_afterENM.chain.S.move_afterXnOI xAFails silently if either argument is not a ->member of the chain.nnsNM.chain.S.insert_afterOI xNM.chain.S.insert_afterRIOI x+&·N insert_afternnOIxIENM.chain.S.move_beforeXnnnnsNM.chain.S.afterOIxNM.chain.S.afterRIOIx,}E”NafternOIx"Succeeds if the first occurrence of the first argument is after the first occurrence of the second argument. Example: ?- new(@ch, chain(aap, noot, mies)). ?- send(@ch, after, noot, aap) --> yes ?- send(@ch, after, aap, mies) --> no Fails if one of the arguments is not in the chain.OIxIENM.chain.S.beforeXnnnnsNM.chain.S.initialiseOIxNM.chain.S.initialiseRIOIx,0*†N initialisenOIx0Create a chain from an initial list of elements.nnnnnsNM.chain.S.for_someOIxNM.chain.S.for_someRIOIx8Øfor_all', but continues the iteration even if code fails to execute for some element. Always succeeds. Forwarded arguments: @arg1 element @arg2 1-based index of elementOIxIeNM.chain.S.for_allXnnnnsN V.chain.headCman_variable_card identifiermodule last_modifiednamesummary descriptionsee_alsoinheritdefaultsOIxN V.chain.headRIOIx(¯ÑúNheadnOIxEFirst cell of the chain. When the chain is empty, its value is @nil.nnnsNM.chain.S.delete_headOIxNM.chain.S.delete_headRIOIx?T~¿N delete_headnOIxJDelete the first element of the chain. See also <-head and <-delete_head.nnOI xFails if the chain is empty.nnsNM.chain.G.currentOI!xNM.chain.G.currentRIOI"x?T\GNcurrentnOI#x}Get the value of the `current' cell. Use of the `current' field of chains is discouraged as it makes the code non-reentrant.OI$xIEN $topics$146XnnnnsNM.chain.G.complete_nameOI%xNM.chain.G.complete_nameRIOI&x,}E•N complete_namenOI'xÝSupport the implementation of automatic completion as found with class text_item. The chain is a chain of elements from which one has to be chosen by means of completion. `Prefix' is the string typed so far. `Extract_name' is a function to extract the name from the each element. Its values are: @nil Use default conversion to text. @default Use `object <-print_name'. Function Use this function, @arg1 is the element. The return value is a tuple object. The `tuple <-first' contains a new chain holding all elements of the receiving string whose name start with the given `prefix'. The `tuple <-second' contains a new string object holding the largest common prefix of all matches. If no element of the chain matches prefix, this method fails. Example: ?- get(chain(gnu, foo, gnats, bar), complete_name, 'g', tuple(Matches, string(Common))), object(Matches, Chain). Common = gn Chain = chain(gnu, gnats) Matches = @854357/chain See also `text_item ->complete'.nnnnnsN M.chain.G.mapOI(xN M.chain.G.mapRIOI)x8×ùNmapnOI*xíExecutes obtainer or block for each element of the chain. Returns a new chain holding the resulting values of executing the code. All elements for which the execution fails are omitted. Argument forwarding: @arg1 Element tested @arg2 1-based index of the element The example below returns a chain with names holding the names of all graphical objects on the graphical device. graphical_names(Device, Names) :- get(Device, graphicals, Chain), get(Chain, map, @arg1?name, Names).nnnnnsNM.chain.S.subtractOI+xNM.chain.S.subtractRIOI,x:¯qNsubtractnOI-xTDelete all elements in the argument from the receiving chain. See also ->delete_all.nnnnnsNM.chain.S.insert_beforeOI.xNM.chain.S.insert_beforeRIOI/x<Ù VN insert_beforenOI0xˆInsert first before second object. If the second object is not a <-member of the chain, value is ->append'ed. See also ->insert_after.nnnnnsNM.chain.G.nth1OI1xNM.chain.G.nth1RIOI2x*§‚çNnth1nnOI3xIENM.chain.S.current_noXnnnnsNM.chain.S._appendOI4xNM.chain.S._appendRIOI5x,.ù›N_appendnOI6xyAppend that allows for appending function objects (@arg1, @event, @receiver, class ?) to a chain without evaluating them.OI7xIENM.chain.S.appendXnnnnsN M.chain.S.addOI8xN M.chain.S.addRIOI9x*§~5NaddnOI:x=->append object to chain if it is not already a member of it.OI;xIeNM.chain.S.memberENM.chain.S.appendXnnnnsNM.chain.S.sortOIxSort the elements in the chain. Two elements are compared by examining the return status of the code object. Both @arg1 and @arg2 are bound to some element of the chain. Execution of the code is supposed to succeed if @arg1 must be before @arg2 in the sorted chain. If `code' is a function object, the return status is interpreted as follows: # integer smaller then 0 or the atom `smaller' @arg1 must be before @arg2 # 0 or the atom `equal' Both elements are equal (neither is deleted, but their order is undefined). # anything else @arg1 must be after @arg2 Common code objects to use are the arithmetic comparison objects and messages invoking a string comparison method. Examples: Sort a chain of integers, lowest first: send(Chain, sort, @arg1 < @arg2). Sort a chain of char_array objects, alphabetically lowest first: send(Chain, sort, ?(@arg1, compare, @arg2)). If `compare' code is omitted, the contents of the chain is sorted on alphabetically on their <-print_name. If `unique' equals @on, duplicates (i.e. pairs of objects for which executing the comparison yields `equal') will be removed. Default is not to remove duplicates. See also `chain ->unique'. NOTE: When sorting with a non-function, the result of comparing two element is a boolean and cannot express `equal'. ->sort yields an undefined result if the chain contains two or more element for which `code ->forward: A, B' *and* `code ->forward: B, A' yield the same result. This undefined behaviour can include a fatal error.OI?xIeN($class/char_array$M.char_array.G.compareeN($class/char_array$M.char_array.S.smallereN'$class/char_array$M.char_array.S.largereN*$class/binary_condition$C.binary_conditionEN$class/vector$M.vector.S.sortXnnnnsNM.chain.S.delete_allOI@xNM.chain.S.delete_allRIOIAx4×!mN delete_allnOIBxfDelete all elements of the chain that are equal to the argument. Always succeeds. See also ->delete.OICxIENM.chain.S.deleteXnnnnsNM.chain.S.cell_valueOIDxNM.chain.S.cell_valueRIOIEx*§€ÝN cell_valuenOIFx«Set the value of specified cell. The first argument is the reference returned by `chain <-head_cell' or `chain <-next_cell'. One should try to avoid using this function.OIGxIeNM.chain.G.cell_valueeNM.chain.G.head_cellENM.chain.G.next_cellXnnnnsNM.chain.S.emptyOIHxNM.chain.S.emptyRIOIIx*§†ÍNemptynOIJxBSucceeds if the chain has no elements. Intended as a test method.nnnnnsNM.chain.G.next_cellOIKxNM.chain.G.next_cellRIOILx*§€bN next_cellnnOIMxIeNM.chain.G.cell_valueENM.chain.S.cell_valueXnnnnsNM.chain.G.indexOINxNM.chain.G.indexRIOIOx*§‚ÔNindexnnOIPxIENM.chain.G.current_noXnnnnsNM.chain.S.currentOIQxNM.chain.S.currentRIOIRx*§‚5NcurrentnOISx:Replace the value of the `current' cell with the argument.OITxIEN $topics$146XnnnnsNV.chain.currentOIUxNV.chain.currentRIOIVx,}E•NcurrentnOIWxTAlien reference to `current cell' of the chain. The notion of `current' was introduced a long time ago in PCE, while methods only had one argument. Methods needing a second often used `current' for this purpose. Now that PCE methods may have any number of arguments there is little use for `current'. It is advised not to use `current'.OIXxIEN $topics$146XnnsNM.chain.S.current_noOIYxNM.chain.S.current_noRIOIZx*§‚¹N current_nonOI[xWMake the nth (1-based) cell current. When the argument is 0, there is no current cell.OI\xIeN $topics$146ENM.chain.G.nth1XnOI]xJFails without modifiying the current element if the index is out of range.nnsNM.chain.G._arityOI^xNM.chain.G._arityRIOI_x*§~N_aritynnOI`xIEN$class/object$M.object.G._arityXnnnnsNM.chain.G.previousOIaxNM.chain.G.previousRIOIbx4»> NpreviousnOIcx6Returns the element right before the given argument. If the argument is not in the chain or the argument is the first member of the chain, this method fails. If the argument occurs multiple times in the chain, the element before the first appearance is returned. See also <-next, <-nth1, <-head and <-tail.nnnnnsNM.chain.G.head_cellOIdxNM.chain.G.head_cellRIOIex*§€fN head_cellnnOIfxIeNM.chain.G.cell_valueENM.chain.S.cell_valueXnnnnsN V.chain.sizeOIgxN V.chain.sizeRIOIhx(¯ÒNsizenOIixXNumber of elements in the chain. Maintained by the various methods manipulating chains.nnnsNM.chain.S.uniqueOIjxNM.chain.S.uniqueRIOIkx6œ¼TNuniquenOIlxqRemove all duplicates from chain. Objects are compared by reference. See also `chain ->sort' and `chain ->add'.nnnnnsN M.chain.G.subOImxN M.chain.G.subRIOInx:NsubnOIoxÍGet new sub-chain from 0-based start and end. End defaults to <-size. The object at <-end is not included. Example: ?- get_object(chain(0,1,2,3), sub, 1, 2, X). X = chain(1) See also `string<-sub'.nnnnnsN V.chain.tailOIpxN V.chain.tailRIOIqx2>NtailnOIrxbLast cell of the chain. When the chain is empty, the slot has value is @nil and the method fails.nnnsNM.chain.S.deleteOIsxNM.chain.S.deleteRIOItx:¯qpNdeletenOIuxnDelete the first occurrence of `object' from the chain. Fails if there is no such object. Note that objects are compared by their object identity; not by their contents. Hence, the following fails because the second point is a different instance. ?- new(@ch, chain(point(6,6))). Yes ?- send(@ch, delete, point(6,6)). No See also ->delete_all and ->subtract.OIvxIENM.chain.S.delete_allXnnnnsNM.chain.G._argOIwxNM.chain.G._argRIOIxx*§}ÿN_argnnOIyxIEN$class/object$M.object.G._argXnnnnsNM.chain.G.nextOIzxNM.chain.G.nextRIOI{x0µÃ¿NnextnOI|x²Returns the element right after the given argument. If the argument is not in the chain or the argument is the last member of the chain, this method fails. If the argument occurs multiple times in the chain, the next of the first appearance is returned. For backward compatibility only, if no argument is provided, <-current is returned and <-current is moved to the next element. See also <-previous, <-nth1, <-head and <-tail.OI}xIEN $topics$146XnnnnsNM.chain.S.delete_tailOI~xNM.chain.S.delete_tailRIOIx*§†|N delete_tailnOI€xŽDelete the last element of the chain. Note that chains are single linked lists and thus deleting the last implies traversing the entire list.nnOIxFails if the chain is empty.nnsNM.chain.G.current_noOI‚xNM.chain.G.current_noRIOIƒx>ð3;N current_nonOI„x[Get index of the current cell. Fails if the chain has no current cell. See also ->currentOI…xIeN $topics$146ENM.chain.G.indexXnnnnsNM.chain.S.delete_currentOI†xNM.chain.S.delete_currentRIOI‡x*§ƒ WNchainnOIŒxA chain is a linear single-linked list of objects. Chains form the common way to represent collections of objects in PCE. Chains are also used to represent multiple-valued slots. Examples are `device <-graphicals', `class <-sub_classes', etc. PCE chains form the natural counterpart of Prolog lists. For this reason the PCE/Prolog interface defines predicates to transform Prolog lists to PCE chains and visa-versa. Note however that in many cases it is not necessary to convert a PCE chain to a Prolog list; PCE defines many operations on chains. Before you consider converting a PCE chain to a Prolog list, first check whether it is not easier to do the job inside PCE. Notably look at ->member, ->empty,. ->for_all, ->for_some, <-find, <-find_all and <-map.OIxIEN$class/vector$C.vectoreN$class/table$C.tableeN$class/hash_table$C.hash_tableXnnnsNM.chain.G.cell_valueOIŽxNM.chain.G.cell_valueRIOIx*§N cell_valuenOIx-Value associated with a cell. Use with care.OI‘xIeNM.chain.G.next_celleNM.chain.G.head_cellENM.chain.S.cell_valueXnnnnsNM.chain.S.memberOI’xNM.chain.S.memberRIOI“x*§~JNmembernnOI”xIEN M.chain.S.addXnnnnsNM.chain.S.unlinkOI•xNM.chain.S.unlinkRIOI–x,0+NunlinknOI—x*First invokes ->clear to remove the cells.nnnnnsNM.chain.G.copyOI˜xNM.chain.G.copyRIOI™x*§‚NcopynOIšx>Creates a copy of the chain holding the same elements in the same order. When the receiver is a subclass of chain, the resulting chain will be an instance of the same (sub)class: an instance of this subclass is created with no arguments, after which the append behaviour of class chain is used to append the elements.nnnnOI›x-Creating copies of subclasses is ill-defined.sNM.chain.G.convertOIœxNM.chain.G.convertRIOIx5¢NconvertnOIžxConvert a vector object (array) into a linked list (chain object). Because a Prolog list is translated into a code_vector object, any method requiring a chain argument can be passed a Prolog list. For example: send(new(B, browser), open), send(B, members, [gnu, gnat, gnome]).nnnnnsNM.chain.S.clearOIŸxNM.chain.S.clearRIOI x*§FNclearnOI¡xžRemove all elements from the chain. Note that this implies that elements that have no further references are destroyed. The other elements are not affected.nnnnnsNM.chain.S.appendOI¢xNM.chain.S.appendRIOI£x,}E”NappendnOI¤xÓAppend argument at the end of the chain. Although chains are represented as single linked lists, append is efficient because chains maintain a pointer to the last cell. Note that chains may contain duplicates.OI¥xIeN M.chain.S.addENM.chain.S._appendXnnnnsNM.chain.S.findOI¦xNM.chain.S.findRIOI§x8×ÃNfindnOI¨x!Successively executes code on all elements of the chain. Succeeds, setting `<-current' if code is executed with success. Fails otherwise. Arguments: @arg1 The (current) element @arg2 1-based index of element New code should consider using <-find, which avoids the usage of <-current.OI©xIeNM.chain.S.for_allENM.chain.G.findXnnnnsNM.chain.S.for_allOIªxNM.chain.S.for_allRIOI«x8ÕaNfor_allnOI¬xƒThis method invokes its argument code object on all elements of the chain. During the execution the following argument is bound: @arg1 Current element. @arg2 Index of the element (1-based) The iteration stops with failure if the execution of `code' fails for some element of the chain. In the example below we print the elements of a chain on the terminal: ?- new(@ch, chain(hello, world)). ?- send(@ch, for_all, message(@pce, write_ln, @arg1)). hello world If the `safe' argument is @on (default), the elements of the chain are first copied to a local array and existence of the objects in the elements is tested prior to executing the code object. This implies that the chain may be modified by the execution of the method and new elements will not be seen. If this argument is @off this method iterates over the chain itself. In this case it is *not* allowed to modify the chain.OI­xIeNM.chain.G.find_alleNM.chain.G.findeNM.chain.S.findeNM.chain.S.for_someeN($class/hash_table$M.hash_table.S.for_alleN $class/device$M.device.S.for_alleN $examples$8XnnOI®x7By default this operation is caried-out `safe' (= @on).nsNM.chain.S.move_afterOI¯xNM.chain.S.move_afterRIOI°x- ™çN move_afternOI±xŠMove 1st object just after second. If the second object is omitted, the `value' is made the <-head of the chain. See also ->move_before.OI²xIENM.chain.S.move_beforeeN$class/node$M.node.S.move_afterXnnnnsNM.chain.G.findOI³xNM.chain.G.findRIOI´x8׊NfindnOIµx«Successively executes code on the elements. Returns the first element for which code succeeds or fails. Arguments: @arg1 Element tested @arg2 1-based index of elementOI¶xIeNM.chain.S.for_alleNM.chain.G.find_alleNM.chain.S.findeN)$class/hash_table$M.hash_table.G.find_keyEN $examples$7XnnnnsNM.chain.S.insertOI·xNM.chain.S.insertRIOI¸x?T[ÒNinsertnOI¹xtInsert argument before <-current. Use of <-current is discouraged and new code must consider using ->insert_before.OIºxIeNM.chain.S.move_beforeEN $topics$146XnnnnsNM.chain.G.find_allOI»xNM.chain.G.find_allRIOI¼x8ØNfind_allnOI½xPReturns a new chain holding all elements for which the execution of code succeeds. Arguments: @arg1 Element tested @arg2 1-based index of element The following example finds all inverted graphicals on the graphical device `Dev': ?- get(Dev?graphicals, find_all, @arg1?inverted == @on, Inverted). See also `chain ->for_all'.OI¾xIeNM.chain.S.for_allENM.chain.G.findXnnnnsNM.chain.S.equalOI¿xNM.chain.S.equalRIOIÀx,|8NequalnOIÁxWSucceeds if both chains have the same elements. For convenience reasons, the type is defined the include @default and @nil and thus this method fails silently when a chain is compared to one of these constants and fails with a type-error if the argument is neither one of these constants, nor an instance of class chain or a subclass thereof.nnnnnXaCnumber O IÂxx