home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / FileMover / HF-OM1.DMS / in.adf / OpusSDK.lha / SDK / docs / lists.doc < prev    next >
Encoding:
Text File  |  1996-12-26  |  17.2 KB  |  613 lines
  1. dopus5.library/AddSorted                             dopus5.library/AddSorted
  2.  
  3.     NAME
  4.         AddSorted - add a node to a list in alphabetical order
  5.  
  6.     SYNOPSIS
  7.         AddSorted(list, node)
  8.                    A0    A1
  9.  
  10.         void AddSorted(struct List *, struct Node *);
  11.  
  12.     FUNCTION
  13.         This function adds a Node to a List, in alphabetical order based on
  14.         ln_Name.
  15.  
  16.     INPUTS
  17.         list - List to add Node to
  18.         node - Node to add
  19.  
  20.     RESULT
  21.         The node is inserted in the list in its alphabetical position.
  22.         ALL the nodes in the list must have a valid ln_Name, or this routine
  23.         will cause enforcer hits.
  24.  
  25.     NOTES
  26.         This routine uses a simple insertion sort based on strcmpi(). As such,
  27.         it is neither terrible efficient, or locale-sensitive.
  28.  
  29.     SEE ALSO
  30.         exec.library/Insert()
  31.  
  32. dopus5.library/Att_ChangeNodeName           dopus5.library/Att_ChangeNodeName
  33.  
  34.     NAME
  35.         Att_ChangeNodeName - change the name of a node
  36.  
  37.     SYNOPSIS
  38.         Att_ChangeNodeName(node, name)
  39.                             A0    A1
  40.  
  41.         void Att_ChangeNodeName(Att_Node *, char *);
  42.  
  43.     FUNCTION
  44.         Frees the old name of the node and copies the new name.
  45.  
  46.     INPUTS
  47.         node - Att_Node to change name for
  48.         name - new name of the node
  49.  
  50.     RESULT
  51.         The new name is copied and installed.
  52.  
  53.     SEE ALSO
  54.         Att_NewNode()
  55.  
  56. dopus5.library/Att_FindNode                       dopus5.library/Att_FindNode
  57.  
  58.     NAME
  59.         Att_FindNode - find a node by number
  60.  
  61.     SYNOPSIS
  62.         Att_FindNode(list, number)
  63.                       A0     D0
  64.  
  65.         Att_Node *Att_FindNode(Att_List *, long);
  66.  
  67.     FUNCTION
  68.         This routine finds the specified node in the list and returns a
  69.         pointer to it.
  70.  
  71.     INPUTS
  72.         list - list to search
  73.         number - cardinal number of the node to find
  74.  
  75.     RESULT
  76.         Returns the specified Att_Node or NULL if not found.
  77.  
  78.     NOTES
  79.         This routine can also work on normal Lists with proper type-casting.
  80.  
  81.     SEE ALSO
  82.         Att_NewNode(), Att_NodeName()
  83.  
  84. dopus5.library/Att_FindNodeData               dopus5.library/Att_FindNodeData
  85.  
  86.     NAME
  87.         Att_FindNodeData - find a node by its data
  88.  
  89.     SYNOPSIS
  90.         Att_FindNodeData(list, data)
  91.                           A0    D0
  92.  
  93.         Att_Node *Att_FindNodeData(Att_List *, ULONG);
  94.  
  95.     FUNCTION
  96.         This function searches the list for a node with data that matches
  97.         the supplied ULONG value (the data is specified with the Att_NewNode()
  98.         function).
  99.  
  100.     INPUTS
  101.         list - list to search
  102.         data - data to look for
  103.  
  104.     RESULT
  105.         Returns the Att_Node if found, otherwise NULL.
  106.  
  107.     SEE ALSO
  108.         Att_NewNode()
  109.  
  110. dopus5.library/Att_FindNodeNumber           dopus5.library/Att_FindNodeNumber
  111.  
  112.     NAME
  113.         Att_FindNodeNumber - find cardinal number of a node
  114.  
  115.     SYNOPSIS
  116.         Att_FindNodeNumber(list, node)
  117.                             A0    A1
  118.  
  119.         long Att_FindNodeNumber(Att_List *, Att_Node *);
  120.  
  121.     FUNCTION
  122.         This routine searches the list for the specified node, and returns
  123.         the offset from the beginning of the list.
  124.  
  125.     INPUTS
  126.         list - list to search
  127.         node - node to look for
  128.  
  129.     RESULT
  130.         Returns the cardinal number of the node or -1 if not found.
  131.  
  132.     NOTES
  133.         This routine can also work on normal Lists with proper type-casting.
  134.  
  135.     SEE ALSO
  136.         Att_NewNode()
  137.  
  138. dopus5.library/Att_NewList                         dopus5.library/Att_NewList
  139.  
  140.     NAME
  141.         Att_NewList - create a new list
  142.  
  143.     SYNOPSIS
  144.         Att_NewList(flags)
  145.                      D0
  146.  
  147.         Att_List *Att_NewList(ULONG);
  148.  
  149.     FUNCTION
  150.         Creates a new Att_List structure, which you use in conjunction with
  151.         Att_Nodes. These functions provide a convenient way of dynamically
  152.         allocating members of lists and performing searches and sorts on them.
  153.  
  154.     INPUTS
  155.         flags - control flags. Currently valid values are :
  156.  
  157.                     LISTF_LOCK  - list is to be shared and requires locking
  158.                     LISTF_POOL  - use memory pooling for nodes and names
  159.  
  160.                 If you specify LISTF_LOCK, a semaphore will be initialised for
  161.                 this list. Any of the list management functions in the 
  162.                 dopus5.library will lock the semaphore before accessing the
  163.                 list.
  164.  
  165.                 If you specify LISTF_POOL, a small memory pool will be used
  166.                 to allocate list nodes and node names, which can result in
  167.                 greater speed and less memory fragmentation.
  168.  
  169.     RESULT
  170.         Returns pointer to an Att_List structure or NULL for failure.
  171.  
  172.     SEE ALSO
  173.         Att_RemList(), exec.library/NewList()
  174.  
  175. dopus5.library/Att_NewNode                         dopus5.library/Att_NewNode
  176.  
  177.     NAME
  178.         Att_NewNode - add a new node to a list
  179.  
  180.     SYNOPSIS
  181.         Att_NewNode(list, name, data, flags)
  182.                      A0    A1    D0    D1
  183.  
  184.         Att_Node *Att_NewNode(Att_List *, char *, ULONG, ULONG);
  185.  
  186.     FUNCTION
  187.         This routine allocates a new node and adds it to the specified list.
  188.         It can also allocate and copy a name for the node, and store
  189.         user-defined data with it. The new node can be added to the list
  190.         sorted in several ways.
  191.  
  192.     INPUTS
  193.         list - list to add node to
  194.         name - name for the node (will be copied)
  195.         data - user-defined data for the node
  196.         flags - control flags. Currently valid flags are:
  197.  
  198.                     ADDNODEF_SORT       - sort names alphabetically
  199.  
  200.                     ADDNODEF_EXCLUSIVE  - name must be exclusive; if a node
  201.                                           already exists with this name, the
  202.                                           call will fail. Only works in
  203.                                           conjunction with ADDNODEF_SORT.
  204.  
  205.                     ADDNODEF_NUMSORT    - the node name is taken to be an
  206.                                           ascii string containing a number,
  207.                                           and the sort is based on numerical
  208.                                           order rather than ascii order (so
  209.                                           that 10 would come after 1 rather
  210.                                           than before).
  211.  
  212.                     ADDNODEF_PRI        - sort is based on priority. If you
  213.                                           specify this flag, the 'data'
  214.                                           parameter is taken to be the node's
  215.                                           priority.
  216.  
  217.                 If no sorting flags are specified, the node is added to the
  218.                 end of the list.
  219.  
  220.     RESULT
  221.         If successful, the new Att_Node is returned.
  222.  
  223.     SEE ALSO
  224.         Att_NewList(), Att_RemNode()
  225.  
  226. dopus5.library/Att_NodeCount                     dopus5.library/Att_NodeCount
  227.  
  228.     NAME
  229.         Att_NodeCount - count the nodes in a list
  230.  
  231.     SYNOPSIS
  232.         Att_NodeCount(list)
  233.                        A0
  234.  
  235.         long Att_NodeCount(Att_List *);
  236.  
  237.     FUNCTION
  238.         Returns the number of nodes in the list.
  239.  
  240.     INPUTS
  241.         list - list to count
  242.  
  243.     NOTES
  244.         This routine can also work on normal Lists with proper type-casting.
  245.  
  246.     SEE ALSO
  247.         Att_NewNode()
  248.  
  249. dopus5.library/Att_NodeDataNumber           dopus5.library/Att_NodeDataNumber
  250.  
  251.     NAME
  252.         Att_NodeDataNumber - find cardinal number of a node
  253.  
  254.     SYNOPSIS
  255.         Att_NodeDataNumber(list, data)
  256.                             A0    D0
  257.  
  258.         long Att_NodeDataNumber(Att_List *, ULONG);
  259.  
  260.     FUNCTION
  261.         This routine is similar to Att_FindNodeNumber(), except that it takes
  262.         a ULONG value and searches the list for a node with that value as
  263.         it's 'data' (the data specified in the call to Att_NewNode).
  264.  
  265.     INPUTS
  266.         list - list to search
  267.         data - node data to look for
  268.  
  269.     RESULT
  270.         Returns the Att_Node if found, or NULL.
  271.  
  272.     SEE ALSO
  273.         Att_NewNode(), Att_FindNodeNumber()
  274.  
  275. dopus5.library/Att_NodeName                       dopus5.library/Att_NodeName
  276.  
  277.     NAME
  278.         Att_NodeName - find a node name by number
  279.  
  280.     SYNOPSIS
  281.         Att_NodeName(list, number)
  282.                       A0     D0
  283.  
  284.         char *Att_NodeName(Att_List *, long);
  285.  
  286.     FUNCTION
  287.         This routine is similar to Att_FindNode() except that it returns
  288.         a pointer to the node's name rather than the node itself.
  289.  
  290.     INPUTS
  291.         list - list to search
  292.         number - cardinal number of the node to find
  293.  
  294.     RESULT
  295.         Returns a pointer to the node's name, or NULL if not found.
  296.  
  297.     NOTES
  298.         This routine can also work on normal Lists with proper type-casting.
  299.  
  300.     SEE ALSO
  301.         Att_NewNode(), Att_FindNode()
  302.  
  303. dopus5.library/Att_NodeNumber                    dopus5.libary/Att_NodeNumber
  304.  
  305.     NAME
  306.         Att_NodeNumber - find cardinal number of node by name
  307.  
  308.     SYNOPSIS
  309.         Att_NodeNumber(list, name)
  310.                         A0    A1
  311.  
  312.         long Att_NodeNumber(Att_List *, char *);
  313.  
  314.     FUNCTION
  315.         This routine is similar to Att_FindNodeNumber(), except that you
  316.         specify a name to search for rather than a node pointer.
  317.  
  318.     INPUTS
  319.         list - list to search
  320.         name - name of node to search for
  321.  
  322.     RESULT
  323.         Returns the cardinal number of the node or -1 if not found.
  324.  
  325.     NOTES
  326.         This routine can also work on normal Lists with proper type-casting.
  327.         The search is not case-sensitive.
  328.  
  329.     SEE ALSO
  330.         Att_NewNode(), Att_FindNodeNumber()
  331.  
  332. dopus5.library/Att_PosNode                         dopus5.library/Att_PosNode
  333.  
  334.     NAME
  335.         Att_PosNode - reposition an Att_Node in an Att_List
  336.  
  337.     SYNOPSIS
  338.         Att_PosNode(list, node, before)
  339.                      A0    A1    A2
  340.  
  341.         void Att_PosNode(Att_List *, Att_Node *, Att_Node *);
  342.  
  343.     FUNCTION
  344.         This routine removes an Att_Node from its current position and
  345.         re-inserts it in the list in a new position.
  346.  
  347.     INPUTS
  348.         list - Att_List containing node
  349.         node - Att_Node to reposition
  350.         before - Att_Node to re-insert the node before
  351.  
  352.     RESULT
  353.         The node is inserted in the list before the supplied node.
  354.  
  355.     SEE ALSO
  356.         Att_NewNode()
  357.  
  358. dopus5.library/Att_RemList                         dopus5.library/Att_RemList
  359.  
  360.     NAME
  361.         Att_RemList - free an entire Att_List
  362.  
  363.     SYNOPSIS
  364.         Att_RemList(list, flags)
  365.                      A0     D0
  366.  
  367.         void Att_RemList(Att_List *, long);
  368.  
  369.     FUNCTION
  370.         This function releases all the memory used by an Att_List, including
  371.         freeing all of the Att_Nodes attached to it.
  372.  
  373.     INPUTS
  374.         list - Att_List to free
  375.         flags - control flags. Current flag values are :
  376.  
  377.                     REMLISTF_FREEDATA  - If you specify this flag, the data
  378.                                          pointers of each of the nodes will
  379.                                          be automatically freed with FreeVec().
  380.                                          Therefore, if you use this feature,
  381.                                          the data you supply to Att_NewNode()
  382.                                          MUST have been allocated with
  383.                                          AllocVec().
  384.  
  385.                     REMLISTF_FREEMEMH  - Specify this in conjunction with
  386.                                          REMLISTF_FREEDATA and the data will
  387.                                          be freed using FreeMemH() instead of
  388.                                          FreeVec().
  389.  
  390.                     REMLISTF_SAVELIST  - If you specify this flag, only the
  391.                                          nodes of the list will be freed. The
  392.                                          Att_List itself will be reinitialised,
  393.                                          ready for use.
  394.  
  395.     RESULT
  396.         The list nodes and optionally the list itself is freed.
  397.  
  398.     SEE ALSO
  399.         Att_NewList(), Att_NewNode(), Att_RemNode()
  400.  
  401. dopus5.library/Att_RemNode                         dopus5.library/Att_RemNode
  402.  
  403.     NAME
  404.         Att_RemNode - remove a node from a list
  405.  
  406.     SYNOPSIS
  407.         Att_RemNode(node)
  408.                      A0
  409.  
  410.         void Att_RemNode(Att_Node *);
  411.  
  412.     FUNCTION
  413.         This function removes the specified node from its list, and frees
  414.         the name copy and node structure.
  415.  
  416.     INPUTS
  417.         node - node to free
  418.  
  419.     RESULT
  420.         The node is removed and freed. The node data is NOT freed by this
  421.         routine.
  422.  
  423.     SEE ALSO
  424.         Att_NewNode(), Att_RemList()
  425.  
  426. dopus5.library/FindNameI                             dopus5.library/FindNameI
  427.  
  428.     NAME
  429.         FindNameI - find a node by name
  430.  
  431.     SYNOPSIS
  432.         FindNameI(list, name)
  433.                    A0    A1
  434.  
  435.         struct Node *FindNameI(struct List *, char *);
  436.  
  437.     FUNCTION
  438.         This routine is similar to the exec.library/FindName routine, except
  439.         that the comparison used in FindNameI() is not case-sensitive.
  440.  
  441.     INPUTS
  442.         list - list to search
  443.         name - name to search for
  444.  
  445.     RESULT
  446.         Returns pointer to the node if found, otherwise NULL.
  447.  
  448.     SEE ALSO
  449.         exec.library/FindName()
  450.  
  451. dopus5.library/GetSemaphore                       dopus5.library/GetSemaphore
  452.  
  453.     NAME
  454.         GetSemaphore - lock a semaphore
  455.  
  456.     SYNOPSIS
  457.         GetSemaphore(semaphore, flags, unused)
  458.                         A0       D0      A1
  459.  
  460.         long GetSemaphore(struct SignalSemaphore *, long, APTR);
  461.  
  462.     FUNCTION
  463.         This routine locks or attempts to lock the given Semaphore. This
  464.         routine fixes some bugs that the exec.library Semaphore routines
  465.         have under some versions of the OS.
  466.  
  467.     INPUTS
  468.         semaphore - Semaphore to lock
  469.         flags - control flags. Valid flags are :
  470.  
  471.                     SEMF_SHARED     - lock in shared mode
  472.                     SEMF_EXCLUSIVE  - lock in exclusive mode
  473.                     SEMF_ATTEMPT    - only attempt to lock
  474.  
  475.         unused - must be NULL
  476.  
  477.     RESULT
  478.         Returns TRUE if the Semaphore was successfully locked. If SEMF_ATTEMPT
  479.         is not specified, this routine will block until the Semaphore is
  480.         available, and will always return TRUE.
  481.  
  482.     NOTES
  483.         To unlock a Semaphore locked with this function, use the standard
  484.         exec.library ReleaseSemaphore() call.
  485.  
  486.     SEE ALSO
  487.         exec.library/ObtainSemaphore(), exec.library/ObtainSemaphoreShared(),
  488.         exec.library/AttemptSemaphore(), exec.library/AttemptSemaphoreShared(),
  489.         exec.library/ReleaseSemaphore()
  490.  
  491. dopus5.library/InitListLock                       dopus5.library/InitListLock
  492.  
  493.     NAME
  494.         InitListLock - initialise a list/lock pair
  495.  
  496.     SYNOPSIS
  497.         InitListLock(ll, unused)
  498.                      A0     A1
  499.  
  500.         void InitListLock(struct ListLock *, APTR);
  501.  
  502.     FUNCTION
  503.         A ListLock is a convenient structure that ties a List to a Semaphore.
  504.         This routine initialises both with the one call.
  505.  
  506.     INPUTS
  507.         ll - ListLock to initialised
  508.         unused - must be NULL
  509.  
  510.     RESULT
  511.         The List and the Semaphore in the ListLock are initialised.
  512.  
  513.     SEE ALSO
  514.         exec.library/NewList(), exec.library/InitSemaphore()
  515.  
  516. dopus5.library/IsListLockEmpty                 dopus5.library/IsListLockEmpty
  517.  
  518.     NAME
  519.         IsListLockEmpty - see if a list is empty
  520.  
  521.     SYNOPSIS
  522.         IsListLockEmpty(ll)
  523.                         A0
  524.  
  525.         BOOL IsListLockEmpty(struct ListLock *);
  526.  
  527.     FUNCTION
  528.         This routine is equivalent to the IsListEmpty() macro, except that
  529.         it locks the list in shared mode before accessing it.
  530.  
  531.     INPUTS
  532.         ll - ListLock to test
  533.  
  534.     RESULT
  535.         Returns TRUE if the list is empty.
  536.  
  537.     SEE ALSO
  538.         InitListLock(), exec.library/IsListEmpty()
  539.  
  540. dopus5.library/LockAttList                         dopus5.library/LockAttList
  541.  
  542.     NAME
  543.         LockAttList - lock an Att_List
  544.  
  545.     SYNOPSIS
  546.         LockAttList(list, exclusive)
  547.                      A0      D0
  548.  
  549.         void LockAttList(Att_List *, BOOL);
  550.  
  551.     FUNCTION
  552.         If an Att_List was created with the LISTF_LOCK flag, this routine can
  553.         be used to lock the list.
  554.  
  555.     INPUTS
  556.         list - Att_List to lock
  557.         exclusive - set to TRUE if you want exclusive access
  558.  
  559.     RESULT
  560.         This routine will block until the list can be locked, and then return.
  561.         You must call UnlockAttList() to unlock the list when you have
  562.         finished with it.
  563.  
  564.     SEE ALSO
  565.         Att_NewList(), UnlockAttList()
  566.  
  567. dopus5.library/SwapListNodes                     dopus5.library/SwapListNodes
  568.  
  569.     NAME
  570.         SwapListNodes - swap two nodes in a list around
  571.  
  572.     SYNOPSIS
  573.         SwapListNodes(list, node1, node2);
  574.                        A0     A1     A2
  575.  
  576.         void SwapListNodes(struct List *, struct Node *, struct Node *);
  577.  
  578.     FUNCTION
  579.         This routine exchanges the positions of two nodes in a list.
  580.  
  581.     INPUTS
  582.         list - List containing the nodes
  583.         node1 - first node to swap
  584.         node2 - second node to swap
  585.  
  586.     RESULT
  587.         The nodes' positions will be exchanged.
  588.  
  589. dopus5.library/UnlockAttList                     dopus5.library/UnlockAttList
  590.  
  591.     NAME
  592.         UnlockAttList - unlock an Att_List
  593.  
  594.     SYNOPSIS
  595.         UnlockAttList(list)
  596.                        A0
  597.  
  598.         void UnlockAttList(Att_List *);
  599.  
  600.     FUNCTION
  601.         This routine unlocks an Att_List that was locked with LockAttList().
  602.  
  603.     INPUTS
  604.         list - list to unlock
  605.  
  606.     RESULT
  607.         The list is unlocked. Calls to LockAttList() are nested, so you must
  608.         unlock the list as many times as you locked it.
  609.  
  610.     SEE ALSO
  611.         LockAttList()
  612.  
  613.