util : IndexToc

TEKlib / Utility module reference manual

By Timm S. Müller - Copyright © 2005 TEK neoscientists. All rights reserved.

System information
TIsBigEndian Get host endianness
TGetModules Scan available modules
Lists and sorting
TSeekNode Seek in a list
TInsertSorted Insert node into a sorted list
TFindSorted Find node in a sorted list
THeapSort Sort via references
TQSort Sort an array
Arguments
TGetArgC Get argument count
TGetArgV Get argument array
TGetArgs Get argument string
TSetRetVal Set return value
TParseArgV Parse an argument vector
TParseArgs Parse an argument string
Number functions
TGetRand Get random number
TGetUniqueID Get unique ID
TStrToI Convert string to 32bit integer
TStrToD Convert string to decimal number
TBSwap16 Byte-swap 16bit integer
TBSwap32 Byte-swap 32bit integer
THToNL Swap 32bit integer on little-endian architecture
THToNS Swap 16bit integer on little-endian architecture
String functions
TStrCpy Copy string
TStrCat Append string
TStrNCpy Copy string, length-limited
TStrNCat Append string, length-limited
TStrCmp Compare strings
TStrNCmp Compare strings, length-limited
TStrCaseCmp Compare strings, case-insensitive
TStrNCaseCmp Dito, length-limited
TStrLen Return length of a string
TStrDup Create duplicate of a string
TStrNDup Create duplicate of a string, length-limited
TStrStr Find substring
TStrChr Find character
TStrRChr Find character, reverse

util : TGetArgsToc

NAME
TGetArgs - Get argument string

SYNOPSIS
args = TUtilGetArgs(TUtilBase)
TSTRPTR             TAPTR

args = TGetArgs()
TSTRPTR         TVOID

FUNCTION
Return an application's argument vector (argv) in a single string, with the individual items being seperated with spaces.

RESULTS
args application arguments

SEE ALSO


util : TParseArgsToc

NAME
TParseArgs - Parse an argument string

SYNOPSIS
handle = TUtilParseArgs(TUtilBase, template, argstring, argarray)
TAPTR                   TAPTR      TSTRPTR   TSTRPTR    TTAG*

handle = TParseArgs(template, argstring, argarray)
TAPTR               TSTRPTR   TSTRPTR    TTAG*

FUNCTION
Parse an argument string into an arguments array, according to a format template.
The template string specifies the expected format. Options in the template are separated with commas. Each argument consists of a name, an optional alias, and an optional set of qualifiers.
If parsing is successful, then this function returns a handle. When you are finished processing the arguments, this handle must be passed to teklib:TDestroy for freeing all associated memory.
See TParseArgV for a detailed description of the format template.

INPUTS
template Format string
argv Array of string pointers to be parsed
args Pointer to an array of tags to be filled

RESULTS
handle Argument handle, or TNULL if parsing failed

SEE ALSO


util : TStrStrToc

NAME
TStrStr - Find substring

SYNOPSIS
subptr = TUtilStrStr(TUtilBase, str,    substr)
TSTRPTR              TAPTR      TSTRPTR TSTRPTR

subptr = TStrStr(str,    substr)
TSTRPTR          TSTRPTR TSTRPTR

FUNCTION
Find substring substr in string str, and return a pointer to its first occurence in str.
  • If substr is not found, TNULL is returned.
  • If str is TNULL, TNULL is returned.
  • If substr is TNULL, str is returned.

INPUTS
str String to search
substr Substring to find

RESULTS
subptr Ptr to the first character of substr in str, or TNULL

SEE ALSO


util : TSeekNodeToc

NAME
TSeekNode - Seek in a list

SYNOPSIS
newnode = TUtilSeekNode(TUtilBase, node,  steps)
TNODE*              TAPTR          TNODE* TINT

newnode = TSeekNode(node,  steps)
TNODE*              TNODE* TINT

FUNCTION
Seek in a doubly linked list by a given number of steps either forward (steps > 0) or backward (steps < 0), and return the node reached, or TNULL if seeked past end or before start of the list. If steps is zero, node is returned.

INPUTS
node Starting node
steps Number of steps to seek

RESULTS
newnode Node reached, or TNULL


util : TGetRandToc

NAME
TGetRand - Get random number (v4)

SYNOPSIS
num = TUtilGetRand(TUtilBase, seed)
TINT    TAPTR                 TINT

num = TGetRand(seed)
TINT           TINT

FUNCTION
From a seed value, generate a pseudo random number in the range from 0 to 2147483647 (hexadecimal 0x7fffffff).

EXAMPLES
TTIME t;
TINT seed;

TQueryTime(timereq, &t);
seed = t.ttm_USec;

/* Get a pseudo random number in the range from 0 to 99999 */
TINT i = (seed = TGetRand(seed)) % 100000;

/* Get a pseudo random number in the range from 0 to 1023 */
TINT j = (seed = TGetRand(seed)) & 0x3ff;

/* Get a pseudo random number in the range from -1.0 to 1.0 */
TFLOAT f = (seed = TGetRand(seed));
f /= 0x3fffffff;
f -= 1;

RESULTS
num Pseudo random number

BUGS
Up to v3, this function operated on a seed value which was internal to the Utility module. Such is wrong in a multitasking environment, and the API was changed in v4. The old function vectors remain in place and are now called TGetRandObs and TSetRandObs.

SEE ALSO


util : THeapSortToc

NAME
THeapSort - Sort an array via references

SYNOPSIS
success = TUtilHeapSort(TUtilBase, data, refarray, length, cmpfunc)
TBOOL                   TAPTR      TAPTR TTAG*     TUINT   TCMPFUNC

success = THeapSort(data, refarray, length, cmpfunc)
TBOOL               TAPTR TTAG*     TUINT   TCMPFUNC

FUNCTION
Using the Heapsort algorithm, sort data of a given length, via a reference array and comparison function. This layout allows you to sort any kind of data structure, including arrays of any type, and even lists.
The data argument will be passed to the user-supplied comparison function only, and is unused by the sorting algorithm. The reference array will usually contain indices or pointers.

INPUTS
data Userdata to be passed to the comparison function
refarray Array of references, i.e. indices or pointers
length Number of entries to be sorted
cmpfunc Comparison function
The comparison functions accords to this prototype:
TCALLBACK TINT (*)(TAPTR data, TAPTR ref1, TAPTR ref2)
The comparison function must return a value less than zero indicating "ref1 less than ref2", a value greater zero indicating "ref1 greater than ref2", and zero for "ref1 equal to ref2".

EXAMPLES
/* Sort a list of named nodes */

TCALLBACK TINT
cmpn(TAPTR util, struct mynode *ref1, struct mynode *ref2)
{
    return TStrCmp(util, ref1->name, ref2->name);
}

TTAG refarray[NUMNODES], *rp;
TNODE *nextnode, *node = list->head;
rp = refarray;

/* Setup reference array */
while ((nextnode = node->succ))
{
    *rp++ = (TTAG) node;
    node = nextnode;
}

THeapSort(util, util, refarray, numnodes, (TCMPFUNC) cmpn);

/* The list could be accessed in sorted order now, using the
reference array. It can be actually reordered also: */

for (i = 0; i < NUMNODES; ++i)
{
    TRemove((TNODE *) refarray[i]);
    TAddTail(list, (TNODE *) refarray[i]);
}

RESULTS
success Boolean
Possible reasons for failure are: No comparison function or reference array given or less than two entries to sort.

NOTES
The Heapsort algorithm is slower than Quicksort, but it has no stack impact, and its performance is insensitive to the initial array order.

SEE ALSO


util : TQSortToc

NAME
TQSort - Sort an array

SYNOPSIS
success = TUtilQSort(TUtilBase, array, num, size, compar,  userdata)
TBOOL                TAPTR      TAPTR  TINT TINT  TCMPFUNC TAPTR

success = TQSort(array, num, size, compar,  userdata)
TBOOL            TAPTR  TINT TINT  TCMPFUNC TAPTR

FUNCTION
Sort num elements of an array according to a comparison function. Individual elements in the array are of the given size in bytes. A userdata pointer is passed to the comparison function and remains invisible to the sorting algorith.
This function implements the Quicksort algorithm.

INPUTS
array Data to sort
num number of elements to compare
size byte size of a single array element
compar Comparison function
userdata Userdata to be passed to the comparison function
The comparison function is according to this declaration:
TCALLBACK TINT(*)(TAPTR udata, TAPTR arg1, TAPTR arg2).
The comparison function has to return a value less than zero indicating "arg1 less than arg2", a value greater zero indicating "arg1 greater than arg2", and zero if "arg1 equal to arg2".

RESULTS
success Boolean
Reasons for failure are: No comparison function or reference array, less than two entries to sort, size of a single element is zero, or allocation of an internal temporary element failed.

NOTES
The Quicksort algorithm is generally faster than Heapsort, but it has some stack impact depending on the number of elements to sort. Its performance is not completely insensitive to the initial array order.

SEE ALSO


util : TStrCmpToc

NAME
TStrCmp - Compare strings

SYNOPSIS
result = TUtilStrCmp(TUtilBase, string1, string2)
TINT                 TAPTR      TSTRPTR  TSTRPTR

result = TStrCmp(string1, string2)
TINT             TSTRPTR  TSTRPTR

FUNCTION
Compare strings, case-sensitive.
The return value will be less than zero if string1 is less than string2, zero if both strings are equal, or greater than zero, if string1 is greater than string2.
Either or both of the strings may be TNULL pointers. A TNULL string is 'less than' a non-TNULL string.

INPUTS
string1 String to be compared, may be TNULL
string2 String to be compared, may be TNULL

RESULTS
result result of comparison

SEE ALSO


util : TStrNCmpToc

NAME
TStrNCmp - Compare strings, length-limited

SYNOPSIS
result = TUtilStrCmp(TUtilBase, string1, string2, maxlen)
TINT                 TAPTR      TSTRPTR  TSTRPTR  TINT

result = TStrCmp(string1, string2, maxlen)
TINT             TSTRPTR  TSTRPTR  TINT

FUNCTION
Compare strings, case-sensitive. Comparison is limited to a maximum of maxlen characters.
The return value will be less than zero if string1 is less than string2, zero if both strings are equal, or greater than zero, if string1 is greater than string2.
Either or both of the strings may be TNULL pointers. A TNULL string is 'less than' a non-TNULL string.

INPUTS
string1 String to be compared, may be TNULL
string2 String to be compared, may be TNULL
maxlen Maximum number of characters to test

RESULTS
result result of comparison

SEE ALSO


util : TStrLenToc

NAME
TStrLen - Return length of a string

SYNOPSIS
len = TUtilStrLen(TUtilBase, string)
TINT              TAPTR      TSTRPTR

len = TStrLen(string)
TINT          TSTRPTR

FUNCTION
Return length of a string, in number of characters, not including the trailing zero-byte. Passing a TNULL string is valid, in which case zero will be returned.

INPUTS
string String to be evaluated

RESULTS
len Number of characters in string, or zero.

SEE ALSO


util : TStrDupToc

NAME
TStrDup - Create duplicate of a string

SYNOPSIS
dup = TUtilStrDup(TUtilBase, mmu,   string)
TSTRPTR           TAPTR      TAPTR TSTRPTR

dup = TStrDup(mmu,  string)
TSTRPTR       TAPTR TSTRPTR

FUNCTION
Allocate memory for, copy, and return a pointer to a duplicate of a string. If string is TNULL, a string will be allocated containing only a string's trailing zero-byte.

INPUTS
mmu Memory manager to allocate from, or TNULL
string String to be duplicated

RESULTS
dup A copy of the string, or TNULL if out of memory.

NOTES
The resulting string must be freed using exec:TFree.

SEE ALSO


util : TStrChrToc

NAME
TStrChr - Find character

SYNOPSIS
strptr = TUtilStrChr(TUtilBase, string, character)
TSTRPTR              TAPTR      TSTRPTR TINT8

strptr = TStrChr(string, character)
TSTRPTR          TSTRPTR TINT8

FUNCTION
This function returns a pointer to the first occurance of a character in the given string. If the character is not contained in the string, TNULL is returned.

INPUTS
string String to be scanned
character Character to be located

RESULTS
strptr Pointer to first occurance, or TNULL

SEE ALSO


util : TStrRChrToc

NAME
TStrRChr - Find character, reverse

SYNOPSIS
strptr = TUtilStrRChr(TUtilBase, string, character)
TSTRPTR               TAPTR      TSTRPTR TINT8

strptr = TStrRChr(string, character)
TSTRPTR           TSTRPTR TINT8

FUNCTION
This function returns a pointer to the last occurance of a character in the given string. If the character is not contained in the string, TNULL is returned.

INPUTS
string String to be scanned
character Character to be located

RESULTS
strptr Pointer to first occurance, or TNULL

SEE ALSO


util : TStrCaseCmpToc

NAME
TStrCaseCmp - Compare strings, case-insensitive

SYNOPSIS
result = TUtilStrCaseCmp(TUtilBase, string1, string2)
TINT                     TAPTR      TSTRPTR  TSTRPTR

result = TStrCaseCmp(string1, string2)
TINT                 TSTRPTR  TSTRPTR

FUNCTION
Compare strings, case-insensitive.
The return value will be less than zero if string1 is less than string2, zero if both strings are equal, or greater than zero, if string1 is greater than string2.
Either or both of the strings may be TNULL pointers. A TNULL string is 'less than' a non-TNULL string.

INPUTS
string1 String to be compared
string2 String to be compared

RESULTS
result result of comparison

SEE ALSO


util : TStrNCaseCmpToc

NAME
TStrNCaseCmp - Compare strings, case-insensitive, limited

SYNOPSIS
result = TUtilStrNCaseCmp(TUtilBase, string1, string2, count)
TINT                      TAPTR      TSTRPTR  TSTRPTR  TINT

result = TStrNCaseCmp(string1, string2, count)
TINT                  TSTRPTR  TSTRPTR  TINT

FUNCTION
Compare strings, case-insensitive. Comparison is limited to a maximum of count characters.
The return value will be less than zero if string1 is less than string2, zero if both strings are equal, or greater than zero, if string1 is greater than string2.
Either or both of the strings may be TNULL pointers. A TNULL string is 'less than' a non-TNULL string.

INPUTS
string1 - String to be compared string2 - String to be compared count - Maximum number of characters to be tested

RESULTS
result - Result of comparison

SEE ALSO


util : TGetArgCToc

NAME
TGetArgC - Get application's argument count

SYNOPSIS
argc = TUtilGetArgC(TUtilBase)
TINT                TAPTR

argc = TGetArgC()
TINT            TVOID

FUNCTION
Return application's argument count, if supported by the application's entrypoint.

RESULTS
argc Number of arguments passd to the application
The result will be zero if an argument vector is unsupported by the application startup.

SEE ALSO


util : TGetArgVToc

NAME
TGetArgV - Get application's argument vector

SYNOPSIS
argv = TGetArgV(TUtilBase)
TSTRPTR*        TAPTR

FUNCTION
Return an application's array of arguments, if supported by the application's entrypoint.

RESULTS
argv Pointer to an array of strings
The argument vector contains the arguments supplied to the application, or TNULL if an argument vector is unsupported by the application startup.

NOTES
If an argv vector is available, then it will always be terminated with an additional array element containing TNULL.

SEE ALSO


util : TSetRetValToc

NAME
TSetRetVal - Set application's return value

SYNOPSIS
success = TUtilSetRetVal(TUtilBase, value)
TBOOL                    TAPTR      TUINT

success = TSetRetVal(value)
TBOOL                TUINT

FUNCTION
Set an application-wide return value. If supported by the application's entry point, the value will be returned to the hosting environment.
By convention, the return value should indicate
0 success
5 warn
10 error
20 failure

INPUTS
value Return value to set in the application

RESULTS
success TTRUE if setting the return value succeeded.

SEE ALSO


util : TInsertSortedToc

NAME
TInsertSorted - Insert sorted into a sorted list

SYNOPSIS
TUtilInsertSorted(TUtilBase, list,  numentries, newnode, cmpfunc, data)
                  TAPTR      TLIST* TUINT       TNODE*   TCMPFUNC TAPTR

TInsertSorted(list,  numentries, newnode, cmpfunc, data)
              TLIST* TUINT       TNODE*   TCMPFUNC TAPTR

FUNCTION
Insert a new node into a list, sorted. The list is assumed to contain numentries nodes, and it is assumed to be in sorted state already, according to the same sorting scheme as implemented by the supplied comparison function.
The data argument will be passed to the comparison function only and remains unused by TInsertSorted.

INPUTS
list Pointer to a list header
numentries Number of entries expected in the list
newnode Node to be inserted
cmpfunc Comparison function
data Userdata passed to cmpfunc
The comparison functions accords to this prototype:
TCALLBACK TINT (*)(TAPTR data, TAPTR ref1, TAPTR ref2)
The comparison function must return a value less than zero indicating "ref1 less than ref2", a value greater zero indicating "ref1 greater than ref2", and zero for "ref1 equal to ref2".

NOTES
Sorting is implemented with binary search, which requires no additional resources, but this algorithm is probably too naive for advanced uses. See the Hash module for an alternative.

SEE ALSO


util : TFindSortedToc

NAME
TFindSorted - Find a node in a sorted list

SYNOPSIS
node = TUtilFindSorted(TUtilBase, list,  numentries, findfunc, data)
TNODE*                 TAPTR      TLIST* TUINT       TFINDFUNC TAPTR

node = TFindSorted(list,  numentries, findfunc, data)
TNODE*             TLIST* TUINT       TFINDFUNC TAPTR

FUNCTION
Find a node in a sorted list. the list is assumed to contain numentries nodes, and it is assumed to be in sorted state already, according to the same sorting scheme as implemented by the supplied find function.
The data argument will be passed to the find function only and remains unused by TFindSorted.

INPUTS
list Pointer to a list header
numentries Number of entries expected in the list
findfunc Find function
data Userdata passed to findfunc
The find function is according to the declaration
TCALLBACK TINT (*)(TAPTR data, TAPTR ref)
The return value of this function must be <0 for indicating "ref less than", 0 for "ref equal", or >0 for "ref greater than" the searched item.

RESULTS
node Node found, or TNULL

NOTES
This function is implemented with binary search, which requires no additional resources, but this algorithm is probably too naive for advanced uses. See the Hash module for an alternative.

SEE ALSO


util : TStrNDupToc

NAME
TStrNDup - Create duplicate of a string, length-limited

SYNOPSIS
dup = TUtilStrNDup(TUtilBase, mmu,   string, maxlen)
TSTRPTR            TAPTR      TAPTR, TSTRPTR TINT

dup = TStrNDup(mmu,   string, maxlen)
TSTRPTR        TAPTR, TSTRPTR TINT

FUNCTION
Allocate memory for, copy, and return a pointer to a duplicate of a string. If string is TNULL, a duplicate will be allocated containing only a string's trailing zero-byte. The duplicate will be limited to a maximum of maxlen characters.

INPUTS
mmu Memory manager to allocate from, or TNULL
string String to be duplicated
maxlen Maximum length

RESULTS
dup A copy of the string, or TNULL if out of memory.

NOTES
The resulting string must be freed using exec:TFree.

SEE ALSO


util : TIsBigEndianToc

NAME
TIsBigEndian - Return host-endianness

SYNOPSIS
isbig = TUtilIsBigEndian(TUtilBase)
TBOOL                    TAPTR

isbig = TIsBigEndian()
TBOOL                TVOID

FUNCTION
Determine the host's endianness. If the host is a big endian architecture, a 32bit regisiter containing 0x11223344 stored in memory would yield the byte sequence 0x11, 0x22, 0x33, 0x44. On such an architecture, this function returns TTRUE. On a little endian architecture, the byte sequence would be 0x44, 0x33, 0x22, 0x11, and this function returned TFALSE.

INPUTS
util Util module base pointer

RESULTS
isbig Boolean. TTRUE if host is a big endian architecture.

SEE ALSO


util : TBSwap16Toc

NAME
TBSwap16 - Swap bytes in a 16bit integer

SYNOPSIS
TUtilBSwap16(TUtilBase, valp)
             TAPTR      TUINT16*

TBSwap16(valp)
         TUINT16*

FUNCTION
Reverse the order of the two bytes in memory to which valp points.

INPUTS
valp Pointer to a 16bit integer to swap

SEE ALSO


util : TBSwap32Toc

NAME
TBSwap32 - Swap bytes in a 32bit integer

SYNOPSIS
TUtilBSwap32(TUtilBase, valp)
             TAPTR      TUINT*

TBSwap32(valp)
         TUINT*

FUNCTION
Reverse the order of the four bytes in memory to which valp points.

INPUTS
valp Pointer to a 32bit integer to swap

SEE ALSO


util : TGetUniqueIDToc

NAME
TGetUniqueID - Get an unique ID

SYNOPSIS
value = TUtilGetUniqueID(TUtilBase, extended)
TUINT                    TAPTR      TAPTR

value = TGetUniqueID(extended)
TUINT                TAPTR

FUNCTION
Return a 32bit value that is relatively unique. Note, however, that it is unique only once per address space, and no longer unique after about 4.2 billion calls to this function.

INPUTS
extended Reserved. this must be TNULL for now.

RESULTS
value a relatively unique number


util : TStrCpyToc

NAME
TStrCpy - Copy a string

SYNOPSIS
p = TUtilStrCpy(TUtilBase, to,     from)
TSTRPTR         TAPTR      TSTRPTR TSTRPTR

p = TStrCpy(to,     from)
TSTRPTR     TSTRPTR TSTRPTR

FUNCTION
Copy the source string (from) to the destination string (to). Either or both of the strings may be TNULL, in which cass nothing will happen, and TNULL will be returned. If successful, a pointer to the destination string will be returned.

INPUTS
to Destination string
from Source string

RESULTS
p Same as destination string, or TNULL if failed

SEE ALSO


util : TStrNCpyToc

NAME
TStrNCpy - Copy a string, length-limited

SYNOPSIS
p = TUtilStrNCpy(TUtilBase, to,     from,   len)
TSTRPTR          TAPTR      TSTRPTR TSTRPTR TINT

p = TStrNCpy(to,     from,   len)
TSTRPTR      TSTRPTR TSTRPTR TINT

FUNCTION
Copy the source string (from) to the destination string (to). Either or both of the strings may be TNULL, in which case nothing will happen, and TNULL will be returned. If successful, a pointer to the destination string will be returned.
This operation always writes exactly len characters to the destination. If it reaches the zero-byte terminator before len characters are written, the destination is padded with zero-bytes.
Warning: If the source string contains more than len characters, the destination will not be zero-terminated when this function returns.

INPUTS
to Destination string
from Source string
len Number of characters to write to destination

RESULTS
p Same as destination string, or TNULL if failed

SEE ALSO


util : TStrCatToc

NAME
TStrCat - Concatenate strings

SYNOPSIS
p = TUtilStrCat(TUtilBase, string, addstr)
TSTRPTR         TAPTR      TSTRPTR TSTRPTR

p = TStrCat(string, addstr)
TSTRPTR     TSTRPTR TSTRPTR

FUNCTION
Append addstr to the tail of string. Either or both of the strings may be TNULL, in which case nothing will happen, and TNULL will be returnedd. If successful, the destination string will be returned.

INPUTS
string Destination
addstr String to be appended

RESULTS
p Same as destination string, or TNULL if failed

SEE ALSO


util : TStrNCatToc

NAME
TStrNCat - Concatenate strings, length-limited

SYNOPSIS
p = TUtilStrNCat(TUtilBase, string, addstr, maxlen)
TSTRPTR          TAPTR      TSTRPTR TSTRPTR TINT

p = TStrNCat(string, addstr, maxlen)
TSTRPTR      TSTRPTR TSTRPTR TINT

FUNCTION
Append addstr to the tail of string. Either or both of the strings may be TNULL, in which case nothing will happen, and TNULL will be returned. If successful, the destination string will be returned. No more than maxlen characters are copied to the destination. A terminating zero-byte character is placed at the end of the destination string in any case.

INPUTS
string Destination
addstr String to append
maxlen Maximum number of characters to copy

RESULTS
p Same as destination string, or TNULL if failed

SEE ALSO


util : TParseArgVToc

NAME
TParseArgV - Parse an argument vector

SYNOPSIS
handle = TUtilParseArgV(TUtilBase, template, argv,    args)
TAPTR                   TAPTR      TSTRPTR   TSTRPTR* TTAG*

handle = TParseArgV(template, argv,    args)
TAPTR               TSTRPTR   TSTRPTR* TTAG*

FUNCTION
Parse an array of string pointers into an arguments array, according to a format template.
The array of string pointers is here referred to as 'argv', because a typical use of this function is to parse an application's commandline arguments. Note, however, that it can be applied to any other TNULL-terminated array of string pointers as well.
The template string specifies the expected format. Options in the template are separated with commas. Each argument consists of a name, an optional alias, and an optional set of qualifiers. Example:
-s=SOURCE/A/M,-d=DEST/A/K
This format would require one or more source arguments and a single destination argument. Neither can be omitted. The SOURCE keyword (or its alias -s) does not need to appear in the command line. The DEST keyword (or its alias -d) would have to be part of the commandline to be valid. This is how the template would be interpreted:
SOURCE one two three DEST foo Valid
DEST foo -s one Valid
DEST foo Rejected - source missing
one two three foo Rejected - keyword missing
one two dest foo Valid - keywords are not case-sensitive
one two three -d foo four Valid - "four" would be added to SOURCE
An option without qualifiers represents a string argument. If present, a pointer to the string will be placed into the respective entry in the args array. Qualifiers are:
/S - Switch. This is considered a boolean variable. When this option is present, the value TTRUE will be written into the respective entry in the args array.
/N - This argument is considered an integer in decimal notation. When present, a pointer to a 32bit signed integer will be placed into the respective entry in the args array. A pointer to the number is inserted (not the number itself) so that the caller can determine whether the argument was specified.
/K - Keyword. The option will not be accepted unless the keyword appears in the argv vector.
/A - Required. This argument cannot be omitted. If not present, an error is returned.
/M - Multiple strings. Any number of strings will be accepted for this option. Not more than one /M modifier should appear in a template. Any arguments that cannot be assigned to other options will be added to this option. The respective entry in the args array will be a pointer to a TNULL-terminated array of string pointers.
If parsing is successful, this function returns a handle. When you are finished processing the arguments, this handle must be passed to teklib:TDestroy to free all associated memory.

INPUTS
template Format string
argv Array of string pointers to be parsed
args Pointer to an array of tags to be filled with arguments

RESULTS
handle argument handle
The argument handle will be TNULL if parsing failed. When the application has finished processing the arguments, the handle must be passed to teklib:TDestroy for freeing all associated memory.

EXAMPLE
/* Template string */
TSTRPTR template = "-f=FROM/A,-c=CONTEXT/K,-r=RECURSE/S,-h=?/S";

/* Initialize args array to defaults */
TTAG args[4] = {TNULL, (TTAG) "linux_gcc", TFALSE, TFALSE};

/* Get argv vector */
TSTRPTR *argv = TGetArgV();

/* Pass argv + 1 so the program name argv[0] is excluded */
TAPTR handle = TParseArgV(template, argv + 1, args);

if (handle && !args[3])
{
    /* Use the arguments here. Do not destroy the handle yet! */
}

else
{
    /* Either parsing failed or the "help" option was given */
    printusage();
}

/* Clean up */
TDestroy(handle);

BUGS
The args argument was of type TAPTR* in Util 1.0. This has been fixed in 2.0.


util : TStrToIToc

NAME
TStrToI - Convert a string to a signed integer

SYNOPSIS
numchars = TUtilStrToI(TUtilBase, string,  valp)
TINT                   TAPTR      TSTRPTR, TINT*

numchars = TStrToI(string,  valp)
TINT               TSTRPTR, TINT*

FUNCTION
Render the integer represented by the string to a variable being pointed to by valp. Returns the number of characters converted (including the number of whitespaces and plus/minus signs seeked over). In case of an error (overflow, or if no decimal digits were found), returns -1 and places 0 into the variable being pointed to.

INPUTS
string String to be converted
valp Pointer to a 32bit integer

RESULTS
numchars Number of characters processed, or -1 if an error occured

SEE ALSO


util : TStrToDToc

NAME
TStrToD - Convert a string to a decimal number

SYNOPSIS
numchars = TUtilStrToD(TUtilBase, string,  valp)
TINT                   TAPTR      TSTRPTR, TDOUBLE*

numchars = TStrToD(string,  valp)
TINT               TSTRPTR, TDOUBLE*

FUNCTION
Render the decimal number represented by the string to a variable being pointed to by valp. Returns the number of characters converted (including the number of whitespaces, decimal point and plus/minus sign seeked over). In case of an error (if no decimal digits were found), returns -1 and places 0 into the variable being pointed to.

INPUTS
string String to be converted
valp Pointer to a decimal

RESULTS
numchars Number of characters processed, or -1 if an error occured

SEE ALSO


util : TGetModulesToc

NAME
TGetModules - Scan available modules

SYNOPSIS
numentries = TUtilGetModules(TUtilBase, prefix, list,  tags)
TINT                         TAPTR      TSTRPTR TLIST* TTAGITEM*

numentries = TGetModules(prefix, list,  tags)
TINT                     TSTRPTR TLIST* TTAGITEM*

FUNCTION
List modules that would be available to exec:TOpenModule. All local and global module paths will be traversed. An application's internal module list (if present) will be included as well. When the prefix argument is given, return only modules whose names begin with this string.
Entries found will be nodes of the type struct TModuleEntry, and added to the tail of the supplied list. The list structure must be valid, i.e. it is expected to be initialized by the caller.
The entire list can be disposed with a call to teklib:TDestroyList. Individual nodes in the list can be freed using teklib:TDestroy.

INPUTS
prefix Module path prefix, or TNULL
list Pointer to a list header that will collect the entries
tags Pointer to an array of tag items

TAGS
None defined yet

RESULTS
numentries Number of nodes added to the tail of the list

EXAMPLE
/* Scan available datatype codecs */
struct TList modlist;
TInitList(&modlist);
if (TGetModules(util, "datatype_codec_", &modlist, TNULL) > 0)
{
    struct TNode *nnode, *node = modlist.tlh_Head;
    for (; (nnode = node->tln_Succ), node = nnode)
    {
        printf("module found: %s\n",
            ((struct TModuleEntry *) node)->tme_Handle.tmo_Name);
    }
    TDestroyList(&modlist);  /* clean up */
}

NOTES
The underscore may act as an imaginary path delimiter for the future organization of modules in the filesystem.

SEE ALSO


util : THToNLToc

NAME
THToNL - Convert a 32bit integer from/to network byte-order

SYNOPSIS
val = TUtilHToNL(TUtilBase, val)
TINT             TAPTR      TINT

val = THToNL(val)
TINT         TINT

FUNCTION
If the software is running on a little-endian architecture, then the value will be byte-swapped. Otherwise, the value will be returned unmodified.
This will, in essence, convert the specified value from/to network byte-order, which is big endian.

INPUTS
val 32bit integer

RESULTS
val 32bit integer, byte-swapped if running on little-endian

SEE ALSO


util : THToNSToc

NAME
THToNS - Convert a 16bit integer from/to network byte-order

SYNOPSIS
val = TUtilHToNS(TUtilBase, val)
TINT16           TAPTR      TINT16

val = THToNS(val)
TINT16       TINT16

FUNCTION
If the software is running on a little-endian architecture, then the value will be byte-swapped. Otherwise, the value will be returned unmodified.
This will, in essence, convert the specified value from/to network byte-order, which is big endian.

INPUTS
val 16bit integer

RESULTS
val 16bit integer, byte-swapped if running on little-endian

SEE ALSO


util : TGetRandObsToc

NAME
TGetRandObs - Get random number (obsolete as of v4)

SYNOPSIS
num = TUtilGetRandObs(TUtilBase)
TINT                  TAPTR

num = TGetRandObs()
TINT              TVOID

FUNCTION
Generate a pseudo random number in the range from 0 to 2147483647 (hexadecimal 0x7fffffff).

RESULTS
num Pseudo random number

NOTES
This function is obsolete as of v4. Use TGetRand.

SEE ALSO
TGetRand, TSetRandObs


util : TSetRandObsToc

NAME
TSetRandObs - Set random seed (obsolete as of v4)

SYNOPSIS
TUtilSetRandObs(TUtilBase, seed)
                TAPTR      TINT

TSetRandObs(seed)
            TINT

FUNCTION
Set the start value, also known as the 'seed' for random number generation. Setting the seed value and subsequently calling TGetRand results in a reproducable set of numbers that appear relatively random.
Initially, the util module initializes the seed value with a number generated from the system time.

INPUTS
seed Seed value for random number generation

NOTES
This function is obsolete as of v4.

SEE ALSO


util : ABOUTToc

SHORT
TEKlib Utility module API documentation
Util is a compagnion to the Exec module. It contains auxiliary functions.

VERSION
$Id: util.html,v 1.10 2005/10/07 14:15:38 tmueller Exp $
REVISION HISTORY
$Log: util.html,v $ Revision 1.10 2005/10/07 14:15:38 tmueller TParseArgV() example fixed Revision 1.3 2005/09/13 02:01:02 tmueller added non-inline calls to synopsis
Revision 1.2 2005/07/11 21:09:33 tmueller transferred to new markup, re-generated
Revision 1.1 2005/06/19 20:46:04 tmueller moved
Revision 1.7 2004/06/04 00:19:31 tmueller Minor fixes
Revision 1.6 2004/05/18 13:27:05 tmueller Added note for TParseArgV: Handle must be kept until args are read
Revision 1.5 2004/04/18 16:27:06 tmueller Added notes about API changes in Exec and Util between 1.0 and 2.0
Revision 1.4 2004/04/18 14:42:40 tmueller Docs reflect the changes to TGetTag, TParseArgv, TExecSet/GetAtomData
Revision 1.3 2004/01/13 02:12:32 tmueller Cosmetic
Revision 1.2 2003/12/14 18:01:19 tmueller Updated, fixed, added details, such as for TGetRand
Revision 1.1.1.1 2003/12/11 07:17:42 tmueller Krypton import
Revision 1.4 2003/10/30 20:07:09 dtrompetter added TQSort
Revision 1.3 2003/10/29 02:03:30 tmueller Autodocs share a common topology now: 0_ABOUT, 1_INDEX
Revision 1.2 2003/10/22 03:17:10 tmueller Removed Titoa and Tatoi, made Tstrol and TStrToD public, documented them, cleaned up util module documentation


util : Table of contents


Generated Fri Oct 7 15:13:16 2005 from util.doc