Copyright (c) Hyperion Entertainment and contributors.
Difference between revisions of "Utility Library"
Jump to navigation
Jump to search
Steven Solie (talk | contribs) |
Steven Solie (talk | contribs) |
||
| (5 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
== Utility Library == |
== Utility Library == |
||
| − | Utility library is the home for all the OS functions which don't fit in the other libraries. Among the calls in utility library are calls to manage tags and tag lists, callback hooks, |
+ | Utility library is the home for all the OS functions which don't fit in the other libraries. Among the calls in utility library are calls to manage tags and tag lists, callback hooks, strings, data structures and more. |
| + | The various functions are grouped into several sections: |
||
| − | == Named Objects == |
||
| + | * [[Tags]] |
||
| − | |||
| + | * [[Callback Hooks]] |
||
| − | {| class="wikitable" |
||
| + | * [[String Functions]] |
||
| − | | AddNamedObject() || Add a named object to a namespace. |
||
| + | * [[Date Functions]] |
||
| − | |- |
||
| + | * [[Named Objects]] |
||
| − | | AllocNamedObject() || Allocate a named object. |
||
| + | * [[Data Structures]] |
||
| − | |- |
||
| − | | AttemptRemNamedObject() || Attempt to remove a named object. |
||
| − | |- |
||
| − | | FindNamedObject() || Find the next named object (case sensitive). |
||
| − | |- |
||
| − | | FreeNamedObject() || Frees a named object. |
||
| − | |- |
||
| − | | NamedObjectName() || Return the name of a named object. |
||
| − | |- |
||
| − | | ReleaseNamedObject() || Release usage of a named object. |
||
| − | |- |
||
| − | | RemNamedObject() || Remove a named object from any namespace. |
||
| − | |- |
||
| − | |} |
||
| − | |||
| − | Insert documentation here. |
||
| − | |||
| − | == Data Structures == |
||
| − | |||
| − | === Splay Trees === |
||
| − | |||
| − | Splay trees are a form of binary tree which organizes itself in response to insertions and searches. Whenever a search finds a specific tree node, that node is "pulled up" into the tree root, and the tree is subsequently reorganized. This reorganization is called "splaying" and has the effect of making the tree flatter, shortening the distances between the root and leaf nodes. Also, more frequently-used nodes will move more closely to the root of the tree during each splay operation. The more splay operations are performed, the more closely the tree will represent the frequency of the node accesses, and will eventually place the most frequently-used nodes close to the root of the tree. This self-organization makes splay trees well-suited for use in caches or dictionaries. Because search operations will modify the splay tree, you should always use an arbitration mechanism such as a [[Exec_Mutexes|Mutex]] if you share the same splay tree with several Tasks or Processes. |
||
| − | |||
| − | See Wikipedia for more generic information [http://en.wikipedia.org/wiki/Splay_tree about splay trees]. |
||
| − | |||
| − | {| class="wikitable" |
||
| − | | CreateSplayTree() || Allocate a splay tree data structure. |
||
| − | |- |
||
| − | | DeleteSplayTree() || Free a splay tree and all its nodes. |
||
| − | |- |
||
| − | | FindSplayNode() || Search for a key in a splay tree. |
||
| − | |- |
||
| − | | InsertSplayNode() || Insert a new key into a splay tree. |
||
| − | |- |
||
| − | | RemoveSplayNode() || Remove a node from a splay tree. |
||
| − | |} |
||
| − | |||
| − | === Skip Lists === |
||
| − | |||
| − | Skip lists combine linked lists with a look-ahead data structure which makes search and insertion operations efficient. You can add data in any particular order to the skip list, and the list will always take care of keeping that data stored in a specific order. The effort spent to maintain this order is small and grows slowly the more list items are added. Traversing the list is very fast and will always return the list items in sorted order. Retrieving specific list items is very efficient, too. Skip lists are useful if you need to be able to retrieve list items in a sorted order at any time while you are building the list. The drawback of skip lists is that the amount of memory required to maintain the list grows faster than the number of list items added. |
||
| − | |||
| − | See Wikipedia for more generic information [http://en.wikipedia.org/wiki/Skip_list about skip lists]. |
||
| − | |||
| − | {| class="wikitable" |
||
| − | | CreateSkipList() || Allocate a skip list data structure. |
||
| − | |- |
||
| − | | DeleteSkipList() || Free a skip list and all its nodes. |
||
| − | |- |
||
| − | | FindSkipNode() || Search for a key in a skip list. |
||
| − | |- |
||
| − | | GetFirstSkipNode() || Get a pointer to the first node of a skip list. |
||
| − | |- |
||
| − | | GetNextSkipNode() || Get a pointer to the following node in a skip list. |
||
| − | |- |
||
| − | | InsertSkipNode() || Insert a new key into a skip list. |
||
| − | |- |
||
| − | | RemoveSkipNode() || Remove a node from a skip list. |
||
| − | |} |
||
| − | |||
| − | == Function Reference == |
||
| − | |||
| − | The tables which follow contain breif descriptions of the functions inside the utility library. See the SDK for details on each function call. |
||
| − | |||
| − | === Tag Function Reference === |
||
| − | |||
| − | The following are brief descriptions of the utility library functions which pertain to tags and tag lusts. |
||
| − | |||
| − | {| class="wikitable" |
||
| − | ! Function |
||
| − | ! Description |
||
| − | |- |
||
| − | | AllocSysObjectTags(ASOT_TAGLIST) |
||
| − | | Allocate a TagItem array (or chain). |
||
| − | |- |
||
| − | | FreeSysObject(ASOT_TAGLIST) |
||
| − | | Frees allocated TagItem lists. |
||
| − | |- |
||
| − | | CloneTagItems() |
||
| − | | Copies a TagItem list. |
||
| − | |- |
||
| − | | RefreshTagItemClone() |
||
| − | | Rejuvenates a clone from the original. |
||
| − | |- |
||
| − | | FindTagItem() |
||
| − | | Scans TagItem list for a tag. |
||
| − | |- |
||
| − | | GetTagData() |
||
| − | | Obtain data corresponding to tag. |
||
| − | |- |
||
| − | | NextTagItem() |
||
| − | | Iterate TagItem lists. |
||
| − | |- |
||
| − | | TagInArray() |
||
| − | | Check if a tag value appears in a Tag array. |
||
| − | |- |
||
| − | | FilterTagChanges() |
||
| − | | Eliminate TagItems which specify no change. |
||
| − | |- |
||
| − | | FilterTagItems() |
||
| − | | Remove selected items from a TagItem list. |
||
| − | |- |
||
| − | | MapTags() |
||
| − | | Convert ti_Tag values in a list via map pairing. |
||
| − | |- |
||
| − | | PackBoolTags() |
||
| − | | Builds a "Flag" word from a TagItem list. |
||
| − | |} |
||
| − | |||
| − | === Callback Hook Function Reference === |
||
| − | |||
| − | The following are brief descriptions of the utility library functions which pertain to callback hooks. |
||
| − | |||
| − | {| class="wikitable" |
||
| − | ! Function |
||
| − | ! Description |
||
| − | |- |
||
| − | | CallHookPkt() |
||
| − | | Call a standard callback Hook function. |
||
| − | |} |
||
| − | |||
| − | === International String Function Reference === |
||
| − | |||
| − | The following are brief descriptions of the utility library functions which pertain to string operations using the international ASCII character set. |
||
| − | |||
| − | {| class="wikitable" |
||
| − | ! Function |
||
| − | ! Description |
||
| − | |- |
||
| − | | Stricmp() |
||
| − | | Compare strings, case-insensitive. |
||
| − | |- |
||
| − | | Strnicmp() |
||
| − | | Compare strings, case-insensitive, with specified length. |
||
| − | |- |
||
| − | | ToLower() |
||
| − | | Convert a character to lower case. |
||
| − | |- |
||
| − | | ToUpper() |
||
| − | | Convert a character to upper case. |
||
| − | |} |
||
| − | |||
| − | === Date Function Reference === |
||
| − | |||
| − | The following are brief descriptions of the utility library functions which pertain to date conversion. |
||
| − | |||
| − | {| class="wikitable" |
||
| − | ! Function |
||
| − | ! Description |
||
| − | |- |
||
| − | | CheckDate() |
||
| − | | Check the legality of a date. |
||
| − | |- |
||
| − | | Amiga2Date() |
||
| − | | Calculate the date from a specified timestamp. |
||
| − | |- |
||
| − | | Date2Amiga() |
||
| − | | Calculate the timestamp from a specified date. |
||
| − | |} |
||
Latest revision as of 22:28, 26 March 2014
|
This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally. |
Utility Library
Utility library is the home for all the OS functions which don't fit in the other libraries. Among the calls in utility library are calls to manage tags and tag lists, callback hooks, strings, data structures and more.
The various functions are grouped into several sections:
