.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "ici::doc::pod3::sdrlist 3" .TH ici::doc::pod3::sdrlist 3 "2016-07-07" "perl v5.24.1" "ICI library functions" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" sdrlist \- Simple Data Recorder list management functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include "sdr.h" \& \& typedef int (*SdrListCompareFn)(Sdr sdr, Address eltData, void *argData); \& typedef void (*SdrListDeleteFn)(Sdr sdr, Object elt, void *argument); \& \& [see description for available functions] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1SDR\s0 list management functions manage doubly-linked lists in managed \&\s-1SDR\s0 heap space. The functions manage two kinds of objects: lists and list elements. A list knows how many elements it contains and what its start and end elements are. An element knows what list it belongs to and the elements before and after it in the list. An element also knows its content, which is normally the \s-1SDR\s0 Address of some object in the \s-1SDR\s0 heap. A list may be sorted, which speeds the process of searching for a particular element. .IP "Object sdr_list_create(Sdr sdr)" 4 .IX Item "Object sdr_list_create(Sdr sdr)" Creates a new list object in the \s-1SDR\s0; the new list object initially contains no list elements. Returns the address of the new list, or zero on any error. .IP "void sdr_list_destroy(Sdr sdr, Object list, SdrListDeleteFn fn, void *arg)" 4 .IX Item "void sdr_list_destroy(Sdr sdr, Object list, SdrListDeleteFn fn, void *arg)" Destroys a list, freeing all elements of list. If \fIfn\fR is non-NULL, that function is called once for each freed element; when called, \fIfn\fR is passed the Address that is the element's data and the \fIargument\fR pointer passed to \fIsdr_list_destroy()\fR. .Sp Do not use \fIsdr_free\fR to destroy an \s-1SDR\s0 list, as this would leave the elements of the list allocated yet unreferenced. .IP "int sdr_list_length(Sdr sdr, Object list)" 4 .IX Item "int sdr_list_length(Sdr sdr, Object list)" Returns the number of elements in the list, or \-1 on any error. .IP "void sdr_list_user_data_set(Sdr sdr, Object list, Address userData)" 4 .IX Item "void sdr_list_user_data_set(Sdr sdr, Object list, Address userData)" Sets the \*(L"user data\*(R" word of \fIlist\fR to \fIuserData\fR. Note that \&\fIuserData\fR is nominally an Address but can in fact be any value that occupies a single word. It is typically used to point to an \s-1SDR\s0 object that somehow characterizes the list as a whole, such as a name. .IP "Address sdr_list_user_data(Sdr sdr, Object list)" 4 .IX Item "Address sdr_list_user_data(Sdr sdr, Object list)" Returns the value of the \*(L"user data\*(R" word of \fIlist\fR, or zero on any error. .IP "Object sdr_list_insert(Sdr sdr, Object list, Address data, SdrListCompareFn fn, void *dataBuffer)" 4 .IX Item "Object sdr_list_insert(Sdr sdr, Object list, Address data, SdrListCompareFn fn, void *dataBuffer)" Creates a new list element whose data value is \fIdata\fR and inserts that element into the list. If \fIfn\fR is \s-1NULL,\s0 the new list element is simply appended to the list; otherwise, the new list element is inserted after the last element in the list whose data value is \&\*(L"less than or equal to\*(R" the data value of the new element (in dataBuffer) according to the collating sequence established by \fIfn\fR. Returns the address of the newly created element, or zero on any error. .IP "Object sdr_list_insert_first(Sdr sdr, Object list, Address data)" 4 .IX Item "Object sdr_list_insert_first(Sdr sdr, Object list, Address data)" .PD 0 .IP "Object sdr_list_insert_last(Sdr sdr, Object list, Address data)" 4 .IX Item "Object sdr_list_insert_last(Sdr sdr, Object list, Address data)" .PD Creates a new element and inserts it at the front/end of the list. This function should not be used to insert a new element into any ordered list; use \fIsdr_list_insert()\fR instead. Returns the address of the newly created list element on success, or zero on any error. .IP "Object sdr_list_insert_before(Sdr sdr, Object elt, Address data)" 4 .IX Item "Object sdr_list_insert_before(Sdr sdr, Object elt, Address data)" .PD 0 .IP "Object sdr_list_insert_after(Sdr sdr, Object elt, Address data)" 4 .IX Item "Object sdr_list_insert_after(Sdr sdr, Object elt, Address data)" .PD Creates a new element and inserts it before/after the specified list element. This function should not be used to insert a new element into any ordered list; use \&\fIsdr_list_insert()\fR instead. Returns the address of the newly created list element, or zero on any error. .IP "void sdr_list_delete(Sdr sdr, Object elt, SdrListDeleteFn fn, void *arg)" 4 .IX Item "void sdr_list_delete(Sdr sdr, Object elt, SdrListDeleteFn fn, void *arg)" Delete \fIelt\fR from the list it is in. If \fIfn\fR is non-NULL, that function will be called upon deletion of \&\fIelt\fR; when called, that function is passed the Address that is the list element's data value and the \fIarg\fR pointer passed to \fIsdr_list_delete()\fR. .IP "Object sdr_list_first(Sdr sdr, Object list)" 4 .IX Item "Object sdr_list_first(Sdr sdr, Object list)" .PD 0 .IP "Object sdr_list_last(Sdr sdr, Object list)" 4 .IX Item "Object sdr_list_last(Sdr sdr, Object list)" .PD Returns the address of the first/last element of \fIlist\fR, or zero on any error. .IP "Object sdr_list_next(Sdr sdr, Object elt)" 4 .IX Item "Object sdr_list_next(Sdr sdr, Object elt)" .PD 0 .IP "Object sdr_list_prev(Sdr sdr, Object elt)" 4 .IX Item "Object sdr_list_prev(Sdr sdr, Object elt)" .PD Returns the address of the element following/preceding \fIelt\fR in that element's list, or zero on any error. .IP "Object sdr_list_search(Sdr sdr, Object elt, int reverse, SdrListCompareFn fn, void *dataBuffer);" 4 .IX Item "Object sdr_list_search(Sdr sdr, Object elt, int reverse, SdrListCompareFn fn, void *dataBuffer);" Search a list for an element whose data matches the data in \fIdataBuffer\fR, starting at the indicated initial list element. If the \fIcompare\fR function is non-NULL, the list is assumed to be sorted in the order implied by that function and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match and a value greater than zero indicates that the list contains no matching element); each time \fIcompare\fR is called it is passed the Address that is the element's data value and the \fIdataBuffer\fR value passed to \fIsm_list_search()\fR. If \fIreverse\fR is non-zero, then the list is searched in reverse order (starting at the indicated initial list element) and the search ends when \fIcompare\fR returns a value that is less than or equal to zero. If \&\fIcompare\fR is \s-1NULL,\s0 then the entire list is searched (in either forward or reverse order, as directed) until an element is located whose data value is equal to ((Address) \fIdataBuffer\fR). Returns the address of the matching element if one is found, 0 otherwise. .IP "Object sdr_list_list(Sdr sdr, Object elt)" 4 .IX Item "Object sdr_list_list(Sdr sdr, Object elt)" Returns the address of the list to which \fIelt\fR belongs, or 0 on any error. .IP "Address sdr_list_data(Sdr sdr, Object elt)" 4 .IX Item "Address sdr_list_data(Sdr sdr, Object elt)" Returns the Address that is the data value of \fIelt\fR, or 0 on any error. .IP "Address sdr_list_data_set(Sdr sdr, Object elt, Address data)" 4 .IX Item "Address sdr_list_data_set(Sdr sdr, Object elt, Address data)" Sets the data value for \fIelt\fR to \fIdata\fR, replacing the original value. Returns the original data value for \fIelt\fR, or 0 on any error. The original data value for \fIelt\fR may or may not have been the address of an object in heap data space; even if it was, that object was \s-1NOT\s0 deleted. .Sp Warning: changing the data value of an element of an ordered list may ruin the ordering of the list. .SH "USAGE" .IX Header "USAGE" When inserting elements or searching a list, the user may optionally provide a compare function of the form: .PP .Vb 1 \& int user_comp_name(Sdr sdr, Address eltData, void *dataBuffer); .Ve .PP When provided, this function is automatically called by the sdrlist function being invoked; when the function is called it is passed the content of a list element (\fIeltData\fR, nominally the Address of an item in the \s-1SDR\s0's heap space) and an argument, \fIdataBuffer\fR, which is nominally the address in local memory of some other item in the same format. The user-supplied function normally compares some key values of the two data items and returns 0 if they are equal, an integer less than 0 if \fIeltData\fR's key value is less than that of \fIdataBuffer\fR, and an integer greater than 0 if \fIeltData\fR's key value is greater than that of \&\fIdataBuffer\fR. These return values will produce a list in ascending order. If the user desires the list to be in descending order, the function must reverse the signs of these return values. .PP When deleting an element or destroying a list, the user may optionally provide a delete function of the form: .PP .Vb 1 \& void user_delete_name(Sdr sdr, Address eltData, void *argData) .Ve .PP When provided, this function is automatically called by the sdrlist function being invoked; when the function is called it is passed the content of a list element (\fIeltData\fR, nominally the Address of an item in the \s-1SDR\s0's heap space) and an argument, \fIargData\fR, which if non-NULL is normally the address in local memory of a data item providing context for the list element deletion. The user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other \s-1SDR\s0 heap space associated with the element. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIlyst\fR\|(3), \fIsdr\fR\|(3), \fIsdrstring\fR\|(3), \fIsdrtable\fR\|(3), \fIsmlist\fR\|(3)