Utility Library - Revision history

Steven Solie: /* Utility Library */

2014-03-26T21:28:24Z

Utility Library

← Older revision		Revision as of 21:28, 26 March 2014
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, ~~and~~ ~~some~~ ~~generic~~ ~~32-bit math functions, all discussed~~ ~~below~~.		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:
			* [[Tags]]
			* [[Callback Hooks]]
			* [[String Functions]]
			* [[Date Functions]]
			* [[Named Objects]]
			* [[Data Structures]]

Steven Solie: /* Function Reference */

2014-03-26T21:24:45Z

Function Reference

← Older revision		Revision as of 21:24, 26 March 2014
Line 3:		Line 3:

	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, and some generic 32-bit math functions, all discussed below.		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, and some generic 32-bit math functions, all discussed below.

	== Function Reference ==

	The tables which follow contain brief descriptions of the functions inside the utility library. See the SDK for details on each function call.

	=== 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.
	\|}

Steven Solie: /* International String Function Reference */

2014-03-26T21:23:00Z

International String Function Reference

← Older revision		Revision as of 21:23, 26 March 2014
Line 7:		Line 7:

	The tables which follow contain brief descriptions of the functions inside the utility library. See the SDK for details on each function call.		The tables which follow contain brief descriptions of the functions inside the utility library. See the SDK for details on each function call.

	=== 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 ===		=== Date Function Reference ===

Steven Solie: /* Function Reference */

2014-03-26T21:22:07Z

Function Reference

@@ Line 6: / Line 6: @@
 == 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.
+The tables which follow contain brief descriptions of the functions inside the utility library. See the SDK for details on each function call.
 === International String Function Reference ===

Steven Solie: /* Data Structures */

2014-03-26T21:12:21Z

Data Structures

← Older revision		Revision as of 21:12, 26 March 2014
Line 3:		Line 3:

	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, and some generic 32-bit math functions, all discussed below.		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, and some generic 32-bit math functions, all discussed below.

	== 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 ==		== Function Reference ==

Steven Solie: /* Named Objects */

2014-03-26T21:11:28Z

Named Objects

← Older revision		Revision as of 21:11, 26 March 2014
Line 3:		Line 3:

	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, and some generic 32-bit math functions, all discussed below.		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, and some generic 32-bit math functions, all discussed below.

	== Named Objects ==

	{\| class="wikitable"
	\| AddNamedObject() \|\| Add a named object to a namespace.
	\|-
	\| AllocNamedObject() \|\| Allocate a named object.
	\|-
	\| 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 ==		== Data Structures ==

Steven Solie: /* Date Functions */

2014-03-26T21:11:00Z

Date Functions

← Older revision		Revision as of 21:11, 26 March 2014
Line 3:		Line 3:

	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, and some generic 32-bit math functions, all discussed below.		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, and some generic 32-bit math functions, all discussed below.

	== Date Functions ==

	To ease date-related calculations, the utility library has some functions to convert a date, specified in a ClockData structure, in the number of seconds since 00:00:00 01-Jan-78 and vice versa.

	To indicate the date, the ClockData structure (in <utility/date.h>) is used.

	<syntaxhighlight>
	struct ClockData
	{
	UWORD sec; /* seconds (0 - 59) */
	UWORD min; /* minutes (0 - 59) */
	UWORD hour; /* hour (0 - 23) */
	UWORD mday; /* day of the month (1 - 31) */
	UWORD month; /* month of the year (1 - 12) */
	UWORD year; /* 1978 - */
	UWORD wday; /* day of the week (0 - 6, where 0 is Sunday) */
	};
	</syntaxhighlight>

	The following functions are available to operate on ClockData:

	{\| class="wikitable"
	\|+ Utility Library Date Functions
	\| Amiga2Date() \|\| Calculate the date from the specified timestamp (in seconds).
	\|-
	\| CheckDate() \|\| Check the legality of a date.
	\|-
	\| Date2Amiga() \|\| Calculate the timestamp from the specified date.
	\|}

	Amiga2Date() takes a number of seconds from 01-Jan-78 as argument and fills in the supplied ClockData structure with the date and time.

	CheckDate() checks if the supplied ClockData structure is valid, and returns the number of seconds from 01-Jan-78 if it is. Note that this function currently does not take the supplied day of the week in account.

	Date2Amiga() takes a ClockData structure as argument and returns the number of seconds since 01-Jan-78. The supplied ClockData structure ''must'' be valid, since no checking is done.

	The following example shows various uses of the utility library date functions.

	<syntaxhighlight>
	// a2d.c
	#include <exec/types.h>
	#include <exec/memory.h>
	#include <dos/datetime.h>
	#include <devices/timer.h>

	// Note these three libraries are opened by newlib startup code.
	#include <proto/exec.h>
	#include <proto/dos.h>
	#include <proto/utility.h>

	#include <proto/timer.h>

	struct TimerIFace *ITimer = NULL;

	int main()
	{
	struct timerequest *tr = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
	ASOIOR_Size, sizeof(struct TimeRequest),
	ASOIOR_ReplyPort, NULL,
	TAG_END);

	if (tr != NULL)
	{
	if (!(IExec->OpenDevice("timer.device", UNIT_VBLANK, (struct IORequest *)tr, 0) ))
	{
	struct Library *TimerBase = tr->tr_node.io_Device;
	ITimer = (struct TimerIFace*)IExec->GetInterface(TimerBase, "main", 1, NULL);

	if (ITimer != NULL)
	{
	struct TimeVal tv;
	ITimer->GetSysTime(&tv);

	IDOS->Printf("GetSysTime():\t%d %d\n", tv.Seconds, tv.Microseconds);

	struct ClockData clockdata;
	IUtility->Amiga2Date(tv.Seconds, &clockdata);

	IDOS->Printf("Amiga2Date(): sec %d min %d hour %d\n",
	clockdata.sec, clockdata.min, clockdata.hour);

	IDOS->Printf(" mday %d month %d year %d wday %d\n",
	clockdata.mday, clockdata.month, clockdata.year, clockdata.wday);

	int32 seconds = IUtility->CheckDate(&clockdata);

	IDOS->Printf("CheckDate():\t%ld\n", seconds);

	seconds = IUtility->Date2Amiga(&clockdata);

	IDOS->Printf("Date2Amiga():\t%ld\n", seconds);

	IEXec->DropInterface((struct Interface*)ITimer);
	}

	IExec->CloseDevice((struct IORequest *)tr);
	}

	IExec->FreeSysObject(ASOT_IOREQUEST, tr);
	}

	return RETURN_OK;
	}
	</syntaxhighlight>

	== Named Objects ==		== Named Objects ==

Steven Solie: /* String Functions */

2014-03-26T21:10:28Z

String Functions

← Older revision		Revision as of 21:10, 26 March 2014
Line 3:		Line 3:

	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, and some generic 32-bit math functions, all discussed below.		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, and some generic 32-bit math functions, all discussed below.

	== String Functions ==

	=== Regular String Functions ===

	These functions perform operations on strings with no regard for localization.

	Currently implemented are:

	{\| class="wikitable"
	\| Strlcat() \|\| Length limited string concatenation.
	\|-
	\| Strlcpy() \|\| Length limited string copy.
	\|-
	\| VASPrintf \|\| Formatted output conversion with result are stored in dynamically allocated buffer.
	\|-
	\| VSNPrintf \|\| Length limited formatted output conversion.
	\|}

	=== International String Functions ===

	When the localization library is opened, these functions will be replaced by ones which will take the locale as defined by the user into account. This means that the compare order may change according to the locale, so care should be taken not to rely on obtaining specific compare sequences.

	Currently implemented are:

	{\| class="wikitable"
	\| Stricmp() \|\| Compare string case-insensitive.
	\|-
	\| Strnicmp() \|\| Compare string case-insensitive, with a specified length.
	\|-
	\| ToLower() \|\| Convert a character to lower case.
	\|-
	\| ToUpper() \|\| Convert a character to upper case.
	\|}

	These functions operate in the same manner as their ANSI C equivalents, for the most part. For more information, see the "Utility Library" Autodocs in the SDK. Here is a simple example of the usage of the international string functions.

	<syntaxhighlight>
	/*
	** istr.c
	*/

	#include <exec/types.h>

	#include <proto/exec.h>
	#include <proto/utility.h>

	int main()
	{
	CONST_STRPTR butter = "Bøtervløøt";
	CONST_STRPTR bread = "Knåckerbrøt";

	int32 result = IUtility->Stricmp(butter, bread);

	IDOS->Printf("comparing %s with %s yields %ld\n", butter, bread, result );

	result = IUtility->Strnicmp(bread, butter, strlen(bread));

	IDOS->Printf("comparing (with length) %s with %s yields %ld\n", bread, butter, result );

	uint8 ch1 = IUtility->ToUpper(0xE6); /* ASCII character 230 ae ligature */
	uint8 ch2 = IUtility->ToLower(0xD0); /* ASCII character 208 Icelandic Eth */

	IDOS->Printf("Chars %lc %lc\n", ch1, ch2);

	return 0;
	}
	</syntaxhighlight>

	== Date Functions ==		== Date Functions ==

Steven Solie: /* Callback Hooks */

2014-03-26T21:09:44Z

Callback Hooks

Show changes

Steven Solie: /* Tags */

2014-03-26T21:09:05Z