# FreeBSD Manual Pages

List(3) OCamldoc List(3)NAMEList - List operations.ModuleModule ListDocumentationModuleList:sigendList operations. Some functions are flagged as not tail-recursive. A tail-recursive function uses constant stack space, while a non-tail-recursive function uses stack space proportional to the length of its list argument, which can be a problem with very long lists. When the function takes several list arguments, an approximate formula giving stack usage (in some un- specified constant unit) is shown in parentheses. The above considerations can usually be ignored if your lists are not longer than about 10000 elements.vallength:'alist->intReturn the length (number of elements) of the given list.valcompare_lengths:'alist->'blist->intCompare the lengths of two lists.compare_lengthsl1l2is equivalent tocompare(lengthl1)(lengthl2), except that the computation stops after itering on the shortest list.Since4.05.0valcompare_length_with:'alist->int->intCompare the length of a list to an integer.compare_length_withlnis equivalent tocompare(lengthl)n, except that the computation stops after at mostniterations on the list.Since4.05.0valcons:'a->'alist->'alistconsxxsisx::xsSince4.03.0valhd:'alist->'aReturn the first element of the given list. RaiseFailurehdif the list is empty.valtl:'alist->'alistReturn the given list without its first element. RaiseFailuretlif the list is empty.valnth:'alist->int->'aReturn then-th element of the given list. The first element (head of the list) is at position 0. RaiseFailurenthif the list is too short. RaiseInvalid_argumentList.nthifnis negative.valnth_opt:'alist->int->'aoptionReturn then-th element of the given list. The first element (head of the list) is at position 0. ReturnNoneif the list is too short. RaiseInvalid_argumentList.nthifnis negative.Since4.05valrev:'alist->'alistList reversal.valappend:'alist->'alist->'alistConcatenate two lists. Same as the infix operator@. Not tail-recur- sive (length of the first argument).valrev_append:'alist->'alist->'alistList.rev_appendl1l2reversesl1and concatenates it tol2. This is equivalent toList.revl1@l2, butrev_appendis tail-recursive and more efficient.valconcat:'alistlist->'alistConcatenate a list of lists. The elements of the argument are all con- catenated together (in the same order) to give the result. Not tail-recursive (length of the argument + length of the longest sub-list).valflatten:'alistlist->'alistAn alias forconcat.===Iterators===valiter:('a->unit)->'alist->unitList.iterf[a1;...;an]applies functionfin turn toa1;...;an. It is equivalent tobeginfa1;fa2;...;fan;()end.valiteri:(int->'a->unit)->'alist->unitSame asList.iter, but the function is applied to the index of the el- ement as first argument (counting from 0), and the element itself as second argument.Since4.00.0valmap:('a->'b)->'alist->'blistList.mapf[a1;...;an]applies functionftoa1,...,an, and builds the list[fa1;...;fan]with the results returned byf. Not tail-recursive.valmapi:(int->'a->'b)->'alist->'blistSame asList.map, but the function is applied to the index of the ele- ment as first argument (counting from 0), and the element itself as second argument. Not tail-recursive.Since4.00.0valrev_map:('a->'b)->'alist->'blistList.rev_mapflgives the same result asList.rev(List.mapfl), but is tail-recursive and more efficient.valfold_left:('a->'b->'a)->'a->'blist->'aList.fold_leftfa[b1;...;bn]isf(...(f(fab1)b2)...)bn.valfold_right:('a->'b->'b)->'alist->'b->'bList.fold_rightf[a1;...;an]bisfa1(fa2(...(fanb)...)). Not tail-recursive.===Iteratorsontwolists===valiter2:('a->'b->unit)->'alist->'blist->unitList.iter2f[a1;...;an][b1;...;bn]calls in turnfa1b1;...;fanbn. RaiseInvalid_argumentif the two lists are determined to have different lengths.valmap2:('a->'b->'c)->'alist->'blist->'clistList.map2f[a1;...;an][b1;...;bn]is[fa1b1;...;fanbn]. RaiseInvalid_argumentif the two lists are determined to have differ- ent lengths. Not tail-recursive.valrev_map2:('a->'b->'c)->'alist->'blist->'clistList.rev_map2fl1l2gives the same result asList.rev(List.map2fl1l2), but is tail-recursive and more efficient.valfold_left2:('a->'b->'c->'a)->'a->'blist->'clist->'aList.fold_left2fa[b1;...;bn][c1;...;cn]isf(...(f(fab1c1)b2c2)...)bncn. RaiseInvalid_argumentif the two lists are determined to have different lengths.valfold_right2:('a->'b->'c->'c)->'alist->'blist->'c->'cList.fold_right2f[a1;...;an][b1;...;bn]cisfa1b1(fa2b2(...(fanbnc)...)). RaiseInvalid_argumentif the two lists are determined to have different lengths. Not tail-recursive.===Listscanning===valfor_all:('a->bool)->'alist->boolfor_allp[a1;...;an]checks if all elements of the list satisfy the predicatep. That is, it returns(pa1)&&(pa2)&&...&&(pan).valexists:('a->bool)->'alist->boolexistsp[a1;...;an]checks if at least one element of the list sat- isfies the predicatep. That is, it returns(pa1)||(pa2)||...||(pan).valfor_all2:('a->'b->bool)->'alist->'blist->boolSame asList.for_all, but for a two-argument predicate. RaiseIn-valid_argumentif the two lists are determined to have different lengths.valexists2:('a->'b->bool)->'alist->'blist->boolSame asList.exists, but for a two-argument predicate. RaiseIn-valid_argumentif the two lists are determined to have different lengths.valmem:'a->'alist->boolmemalis true if and only ifais equal to an element ofl.valmemq:'a->'alist->boolSame asList.mem, but uses physical equality instead of structural equality to compare list elements.===Listsearching===valfind:('a->bool)->'alist->'afindplreturns the first element of the listlthat satisfies the predicatep. RaiseNot_foundif there is no value that satisfiespin the listl.valfind_opt:('a->bool)->'alist->'aoptionfind_optplreturns the first element of the listlthat satisfies the predicatep, orNoneif there is no value that satisfiespin the listl.Since4.05valfilter:('a->bool)->'alist->'alistfilterplreturns all the elements of the listlthat satisfy the predicatep. The order of the elements in the input list is pre- served.valfind_all:('a->bool)->'alist->'alistfind_allis another name forList.filter.valpartition:('a->bool)->'alist->'alist*'alistpartitionplreturns a pair of lists(l1,l2), wherel1is the list of all the elements oflthat satisfy the predicatep, andl2is the list of all the elements oflthat do not satisfyp. The order of the elements in the input list is preserved.===Associationlists===valassoc:'a->('a*'b)list->'bassocalreturns the value associated with keyain the list of pairsl. That is,assoca[...;(a,b);...]=bif(a,b)is the leftmost binding ofain listl. RaiseNot_foundif there is no value associ- ated withain the listl.valassoc_opt:'a->('a*'b)list->'boptionassoc_optalreturns the value associated with keyain the list of pairsl. That is,assoc_opta[...;(a,b);...]=bif(a,b)is the leftmost binding ofain listl. ReturnsNoneif there is no value associated withain the listl.Since4.05valassq:'a->('a*'b)list->'bSame asList.assoc, but uses physical equality instead of structural equality to compare keys.valassq_opt:'a->('a*'b)list->'boptionSame asList.assoc_opt, but uses physical equality instead of struc- tural equality to compare keys.Since4.05valmem_assoc:'a->('a*'b)list->boolSame asList.assoc, but simply return true if a binding exists, and false if no bindings exist for the given key.valmem_assq:'a->('a*'b)list->boolSame asList.mem_assoc, but uses physical equality instead of struc- tural equality to compare keys.valremove_assoc:'a->('a*'b)list->('a*'b)listremove_assocalreturns the list of pairslwithout the first pair with keya, if any. Not tail-recursive.valremove_assq:'a->('a*'b)list->('a*'b)listSame asList.remove_assoc, but uses physical equality instead of structural equality to compare keys. Not tail-recursive.===Listsofpairs===valsplit:('a*'b)list->'alist*'blistTransform a list of pairs into a pair of lists:split[(a1,b1);...;(an,bn)]is([a1;...;an],[b1;...;bn]). Not tail-recursive.valcombine:'alist->'blist->('a*'b)listTransform a pair of lists into a list of pairs:combine[a1;...;an][b1;...;bn]is[(a1,b1);...;(an,bn)]. RaiseInvalid_argumentif the two lists have different lengths. Not tail-recursive.===Sorting===valsort:('a->'a->int)->'alist->'alistSort a list in increasing order according to a comparison function. The comparison function must return 0 if its arguments compare as equal, a positive integer if the first is greater, and a negative inte- ger if the first is smaller (see Array.sort for a complete specifica- tion). For example,Pervasives.compareis a suitable comparison func- tion. The resulting list is sorted in increasing order.List.sortis guaranteed to run in constant heap space (in addition to the size of the result list) and logarithmic stack space. The current implementation uses Merge Sort. It runs in constant heap space and logarithmic stack space.valstable_sort:('a->'a->int)->'alist->'alistSame asList.sort, but the sorting algorithm is guaranteed to be sta- ble (i.e. elements that compare equal are kept in their original order) . The current implementation uses Merge Sort. It runs in constant heap space and logarithmic stack space.valfast_sort:('a->'a->int)->'alist->'alistSame asList.sortorList.stable_sort, whichever is faster on typical input.valsort_uniq:('a->'a->int)->'alist->'alistSame asList.sort, but also remove duplicates.Since4.02.0valmerge:('a->'a->int)->'alist->'alist->'alistMerge two lists: Assuming thatl1andl2are sorted according to the comparison functioncmp,mergecmpl1l2will return a sorted list containting all the elements ofl1andl2. If several elements com- pare equal, the elements ofl1will be before the elements ofl2. Not tail-recursive (sum of the lengths of the arguments). 2020-08-11 source: List(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:

<https://www.freebsd.org/cgi/man.cgi?query=List&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>