@DATABASE "utility.guide" @AUTHOR AmiS © 1998 @INDEX ".Index.guide/Main" @WORDWRAP @HELP help @$VER: utility.library 40.1 autodocs 1.1 @NODE Help "Copyright 1998 AmiS" @{fg shine}utility.library 40.1@{fg text} Version 1.1 This is a NewStyle Autodocs for Amiga Developer Community. Designed 1999 by @{fg shine}AmiS@{fg text} Send your bug report to @{fg fill}amis@cch.pmc.ru@{fg text} @ENDNODE @NODE Main "utility.library" @PREV Main @{jcenter}@{b} A @{ub}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}A@{ub}@{lindent 4} @{lindent 34}@{" AddNamedObject() " LINK "AddNamedObject"} - add a named object to the given namespace. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" AllocateTagItems() " LINK "AllocateTagItems"} - allocate a tag list. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" AllocNamedObjectA() " LINK "AllocNamedObjectA"} - allocate a named object. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" Amiga2Date() " LINK "Amiga2Date"} - fill in a ClockData structure based on a system time stamp @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" ApplyTagChanges() " LINK "ApplyTagChanges"} - change a tag list based on a second tag list. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" AttemptRemNamedObject() " LINK "AttemptRemNamedObject"} - attempt to remove a named object. @{fg shine}(V39)@{fg text} @ENDNODE @NODE MainC "utility.library" @{jcenter}@{" A " LINK Main 0}@{b} C @{ub}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}C@{ub}@{lindent 4} @{lindent 34}@{" CallHookPkt() " LINK "CallHookPkt"} - invoke a Hook function callback. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" CheckDate() " LINK "CheckDate"} - checks a ClockData structure for legal date. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" CloneTagItems() " LINK "CloneTagItems"} - copy a tag list. @{fg shine}(V36)@{fg text} @ENDNODE @NODE MainD "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{b} D @{ub}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}D@{ub}@{lindent 4} @{lindent 34}@{" Date2Amiga() " LINK "Date2Amiga"} - calculate seconds from 01-Jan-1978. @{fg shine}(V36)@{fg text} @ENDNODE @NODE MainF "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{b} F @{ub}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}F@{ub}@{lindent 4} @{lindent 34}@{" FilterTagChanges() " LINK "FilterTagChanges"} - eliminate tags which specify no change. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" FilterTagItems() " LINK "FilterTagItems"} - remove selected items from a tag list. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" FindNamedObject() " LINK "FindNamedObject"} - find the next object of a given name. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" FindTagItem() " LINK "FindTagItem"} - scan a tag list for a specific tag. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" FreeNamedObject() " LINK "FreeNamedObject"} - frees a name object. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" FreeTagItems() " LINK "FreeTagItems"} - free an allocated tag list. @{fg shine}(V36)@{fg text} @ENDNODE @NODE MainG "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{b} G @{ub}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}G@{ub}@{lindent 4} @{lindent 34}@{" GetTagData() " LINK "GetTagData"} - obtain the data corresponding to a tag. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" GetUniqueID() " LINK "GetUniqueID"} - return a relatively unique number. @{fg shine}(V39)@{fg text} @ENDNODE @NODE MainM "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{b} M @{ub}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}M@{ub}@{lindent 4} @{lindent 34}@{" MapTags() " LINK "MapTags"} - convert ti_Tag values in a list via map pairing. @{fg shine}(V36)@{fg text} @ENDNODE @NODE MainN "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{b} N @{ub}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}N@{ub}@{lindent 4} @{lindent 34}@{" NamedObjectName() " LINK "NamedObjectName"} - return the name of the object. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" NextTagItem() " LINK "NextTagItem"} - iterate through a tag list. @{fg shine}(V36)@{fg text} @ENDNODE @NODE MainP "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{b} P @{ub}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}P@{ub}@{lindent 4} @{lindent 34}@{" PackBoolTags() " LINK "PackBoolTags"} - builds a "flag" word from a tag list. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" PackStructureTags() " LINK "PackStructureTags"} - pack a structure with values from taglist. @{fg shine}(V39)@{fg text} @ENDNODE @NODE MainR "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{b} R @{ub}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}R@{ub}@{lindent 4} @{lindent 34}@{" RefreshTagItemClones() " LINK "RefreshTagItemClones"} - rejuvenate a clone from the original. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" ReleaseNamedObject() " LINK "ReleaseNamedObject"} - free a named object. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" RemNamedObject() " LINK "RemNamedObject"} - remove a named object. @{fg shine}(V39)@{fg text} @ENDNODE @NODE MainS "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{b} S @{ub}@{" T " LINK MainT 0}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}S@{ub}@{lindent 4} @{lindent 34}@{" SDivMod32() " LINK "SDivMod32"} - signed 32 by 32 bit division and modulus. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" SMult32() " LINK "SMult32"} - signed 32 by 32 bit multiply with 32 bit result. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" SMult64() " LINK "SMult64"} - signed 32 by 32 bit multiply with 64 bit result. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" Stricmp() " LINK "Stricmp"} - case-insensitive string comparison. @{fg shine}(V37)@{fg text}@{lindent 4} @{lindent 34}@{" Strnicmp() " LINK "Strnicmp"} - length-limited case-insensitive string compare. @{fg shine}(V37)@{fg text} @ENDNODE @NODE MainT "utility.library" @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{b} T @{ub}@{" U " LINK MainU 0} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}T@{ub}@{lindent 4} @{lindent 34}@{" TagInArray() " LINK "TagInArray"} - check if a tag value appears in an array of tag values. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" ToLower() " LINK "ToLower"} - convert a character to lower case. @{fg shine}(V37)@{fg text}@{lindent 4} @{lindent 34}@{" ToUpper() " LINK "ToUpper"} - convert a character to upper case. @{fg shine}(V37)@{fg text} @ENDNODE @NODE MainU "utility.library" @NEXT MainU @{jcenter}@{" A " LINK Main 0}@{" C " LINK MainC 0}@{" D " LINK MainD 0}@{" F " LINK MainF 0}@{" G " LINK MainG 0}@{" M " LINK MainM 0}@{" N " LINK MainN 0}@{" P " LINK MainP 0}@{" R " LINK MainR 0}@{" S " LINK MainS 0}@{" T " LINK MainT 0}@{b} U @{ub} @{jcenter} @{u}@{b}utility.library@{uu}@{ub} @{jleft}@{lindent 1} @{b}U@{ub}@{lindent 4} @{lindent 34}@{" UDivMod32() " LINK "UDivMod32"} - unsigned 32 by 32 bit division and modulus. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" UMult32() " LINK "UMult32"} - unsigned 32 by 32 bit multiply with 32 bit result. @{fg shine}(V36)@{fg text}@{lindent 4} @{lindent 34}@{" UMult64() " LINK "UMult64"} - unsigned 32 by 32 bit multiply with 64 bit result. @{fg shine}(V39)@{fg text}@{lindent 4} @{lindent 34}@{" UnpackStructureTags() " LINK "UnpackStructureTags"} - unpack a structure to values in taglist. @{fg shine}(V39)@{fg text} @ENDNODE @NODE "AddNamedObject" "utility.library/AddNamedObject()" @PREV AddNamedObject @{jcenter} @{u}@{b}AddNamedObject@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} AddNamedObject - add a named object to the given namespace. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} success = AddNamedObject(nameSpace, object); D0 A0 A1 BOOL AddNamedObject(struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *, struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Adds a new item to a NameSpace. If the NameSpace doesn't support duplicate names, a search for a duplicate will be made, and 0 (failure) will be returned. Otherwise, the entry will be @{"Enqueue()" LINK "exec.guide/Enqueue" 0}ed to the NameSpace. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} nameSpace - the name space to add to (NULL for root namespace) object - the object to add (If NULL, will return failure) @{lindent 4} @{fg shine}@{b}RESULT@{ub}@{fg text}@{lindent 8} success - whether the operation succeeded. Check this always! @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"AttemptRemNamedObject()" LINK "AttemptRemNamedObject" 0}, @{"RemNamedObject()" LINK "RemNamedObject" 0} @ENDNODE @NODE "AllocateTagItems" "utility.library/AllocateTagItems()" @{jcenter} @{u}@{b}AllocateTagItems@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} AllocateTagItems - allocate a tag list. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} tagList = AllocateTagItems(numTags); D0 D0 struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *AllocateTagItems(ULONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Allocates the specified number of usable TagItems slots. Note that to access the TagItems in 'tagList', you should use the function @{"NextTagItem()" LINK "NextTagItem" 0}. This will insure you respect any chaining (TAG_MORE) and secret hiding places (TAG_IGNORE) that this function might generate. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} numTags - the number of @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} slots you want to allocate. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 18}tagList - the allocated chain of @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} structures, or NULL if there was not enough memory. An allocated tag list must eventually be freed using @{"FreeTagItems()" LINK "FreeTagItems" 0}. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"FreeTagItems()" LINK "FreeTagItems" 0}, @{"CloneTagItems()" LINK "CloneTagItems" 0} @ENDNODE @NODE "AllocNamedObjectA" "utility.library/AllocNamedObjectA()" @{jcenter} @{u}@{b}AllocNamedObjectA@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} AllocNamedObjectA - allocate a named object. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} object = AllocNamedObjectA(name, tagList); D0 A0 A1 struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *AllocNamedObjectA(STRPTR, struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); object = AllocNamedObject(name, Tag1, ...); struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *AllocNamedObject(STRPTR, ULONG, ...); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Allocates a @{"NamedObject" LINK "utility/name.h/MAIN" 24} and initializes it as needed to the name given. This object can then be used as an object in the namespaces. Tags can be given to make an object contain a namespace such that nested namespaces can be built. When the object is allocated, it automatically has one use. If you later wish to release this object such that others may remove it from the namespace you must do a @{"ReleaseNamedObject()" LINK "ReleaseNamedObject" 0}. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} name - name for the object (must not be NULL) tagList - tags with additional information for the allocation or NULL @{lindent 4} @{fg shine}@{b}@{"TAGS" LINK "libraries/xpk.h/MAIN" 34}@{ub}@{fg text}@{lindent 8} @{lindent 24}ANO_NameSpace - BOOL tag, default FALSE. If this tag is TRUE, the named object will also have a name space attached to it.@{lindent 8} @{lindent 24}ANO_UserSpace - ULONG tag, default 0. If this tag is non-NULL it defines the size (in bytes) of the user space to be allocated with the named object and that will be pointed to by the no_Object pointer. This memory is long-word aligned. If no space is defined, no_Object will be NULL.@{lindent 8} @{lindent 24}ANO_Priority - BYTE tag, default 0. This tag lets you pick a priority for the named object for when it is placed into a name space.@{lindent 8} @{lindent 24}ANO_Flags - ULONG tag, default 0. This tag lets you set the flags of the NameSpace (if you allocated one) There currently are only TWO flags. Do *NOT* set *any* other bits as they are for future use!!! (You can't read them anyway) The flags are: NSF_NODUPS - Name space must be unique. NSF_CASE - Name space is case sensitive @{lindent 4} @{fg shine}@{b}RESULT@{ub}@{fg text}@{lindent 8} @{lindent 17}object - the object allocated, or NULL for failure. The object is defined as a pointer to a pointer. You can do what you wish with the pointer. (It may be NULL or contain a pointer to memory that you had asked for in the tags.) @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"FreeNamedObject()" LINK "FreeNamedObject" 0}, <@{"utility/name.h" LINK "utility/name.h/MAIN" 0}> @ENDNODE @NODE "Amiga2Date" "utility.library/Amiga2Date()" @{jcenter} @{u}@{b}Amiga2Date@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} Amiga2Date - fill in a @{"ClockData" LINK "utility/date.h/MAIN" 23} structure based on a system time stamp @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} Amiga2Date(seconds,result); D0 A0 VOID Amiga2Date(ULONG,struct @{"ClockData" LINK "utility/date.h/MAIN" 23} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Fills in a @{"ClockData" LINK "utility/date.h/MAIN" 23} structure with the date and time calculated from a ULONG containing the number of seconds from 01-Jan-1978 to the date. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} seconds - the number of seconds from 01-Jan-1978. @{lindent 17}result - a pointer to a @{"ClockData" LINK "utility/date.h/MAIN" 23} structure that will be altered by this function @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"CheckDate()" LINK "CheckDate" 0}, @{"Date2Amiga()" LINK "Date2Amiga" 0} @ENDNODE @NODE "ApplyTagChanges" "utility.library/ApplyTagChanges()" @{jcenter} @{u}@{b}ApplyTagChanges@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} ApplyTagChanges - change a tag list based on a second tag list. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} ApplyTagChanges(list,changeList); A0 A1 VOID ApplyTagChanges(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *, struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} For any tag that appears in both 'list' and 'changeList', this function will change the ti_Data field of the tag in 'list' to match the ti_Data field of the tag in 'changeList'. In effect, 'changeList' contains a series of new values for tags already in 'list'. Any tag in 'changeList' that is not in 'list' is ignored. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} list - a list of existing tags (may be NULL) changeList - a list of tags to modify 'list' with (may be NULL) @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"FilterTagChanges()" LINK "FilterTagChanges" 0} @ENDNODE @NODE "AttemptRemNamedObject" "utility.library/AttemptRemNamedObject()" @{jcenter} @{u}@{b}AttemptRemNamedObject@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} AttemptRemNamedObject - attempt to remove a named object. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = AttemptRemNamedObject(object); D0 A0 LONG AttemptRemNamedObject(struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Attempts to remove an object from whatever NameSpace it's in. You must have found the object first (in order to get a use count) before trying to remove it. If the object is in use or is in the process of being removed, this function will return a failure code. If the object is fully removed, the object will then be available to be @{"FreeNamedObject()" LINK "FreeNamedObject" 0}. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} object - the object to attempt to remove. The object must be valid @{lindent 4} @{fg shine}@{b}RESULT@{ub}@{fg text}@{lindent 8} @{lindent 18}success - FALSE if object is still in use (somewhere) TRUE if object was removed @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"RemNamedObject()" LINK "RemNamedObject" 0}, @{"AddNamedObject()" LINK "AddNamedObject" 0}, @{"ReleaseNamedObject()" LINK "ReleaseNamedObject" 0} @ENDNODE @NODE "CallHookPkt" "utility.library/CallHookPkt()" @{jcenter} @{u}@{b}CallHookPkt@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} CallHookPkt - invoke a Hook function callback. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} return = CallHookPkt(hook,object,message); D0 A0 A2 A1 ULONG CallHookPkt(struct @{"Hook" LINK "libraries/xpk.h/MAIN" 43} *,APTR,APTR); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Performs the callback standard defined by a Hook structure. This function is really very simple; it effectively performs a JMP to Hook->h_Entry. It is probably just as well to do this operation in an assembly language function linked in to your program, possibly from a compiler supplied library or a builtin function. It is anticipated that C programs will often call a 'varargs' variant of this function which will be named @{"CallHook" LINK "amiga_lib.guide/CallHook" 0}.This function must be provided in a compiler specific library, but an example of use would be: result = @{"CallHook" LINK "amiga_lib.guide/CallHook" 0}(hook,dataobject,COMMAND_ID,param1,param2); The function @{"CallHook()" LINK "amiga_lib.guide/CallHook" 0} can be implemented in many C compilers like this: ULONG @{"CallHook" LINK "amiga_lib.guide/CallHook" 0}(struct @{"Hook" LINK "libraries/xpk.h/MAIN" 43} *hook, APTR object, ULONG command, ... ) { return(CallHookPkt(hook,object,(APTR)&command)); } @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 15}hook - pointer to an initialized Hook structure as defined in <@{"utility/hooks.h" LINK "utility/hooks.h/MAIN" 0}>@{lindent 8} @{lindent 17}object - useful data structure in the particular context the hook is being used for.@{lindent 8} @{lindent 18}message - pointer to a message to be passed to the hook. This is not an Exec Message structure, but is a message in the OOP sense. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} return - the value returned by the hook function. @{lindent 4} @{fg shine}@{b}WARNING@{ub}@{fg text}@{lindent 8} The functions called through this function should follow normal register conventions unless EXPLICITLY documented otherwise (and they have a good reason too). @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/hooks.h" LINK "utility/hooks.h/MAIN" 0}> @ENDNODE @NODE "CheckDate" "utility.library/CheckDate()" @{jcenter} @{u}@{b}CheckDate@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} CheckDate - checks a @{"ClockData" LINK "utility/date.h/MAIN" 23} structure for legal date. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} seconds = CheckDate(date); D0 A0 ULONG CheckDate(struct @{"ClockData" LINK "utility/date.h/MAIN" 23} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Determines if the @{"ClockData" LINK "utility/date.h/MAIN" 23} structure contains legal date information and returns the number of seconds from 01-Jan-1978 to that date, or 0 if the @{"ClockData" LINK "utility/date.h/MAIN" 23} structure contains illegal data. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} date - a filled-in @{"ClockData" LINK "utility/date.h/MAIN" 23} structure @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 18}seconds - 0 if date is invalid, otherwise the number of seconds from 01-Jan-1978 to the date @{lindent 4} @{fg shine}@{b}BUGS@{ub}@{fg text}@{lindent 8} The wday field of the @{"ClockData" LINK "utility/date.h/MAIN" 23} structure is not checked. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"Amiga2Date()" LINK "Amiga2Date" 0}, @{"Date2Amiga()" LINK "Date2Amiga" 0} @ENDNODE @NODE "CloneTagItems" "utility.library/CloneTagItems()" @{jcenter} @{u}@{b}CloneTagItems@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} CloneTagItems - copy a tag list. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} clone = CloneTagItems(original); D0 A0 struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *CloneTagItems(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Copies the essential contents of a tag list into a new tag list. The cloning is such that calling @{"FindTagItem()" LINK "FindTagItem" 0} with a given tag on the original or cloned tag lists will always return the same tag value. That is, the ordering of the tags is maintained. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 19}original - tag list to clone. May be NULL, in which case an empty tag list is returned. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 16}clone - copy of the original tag list, or NULL if there was not enough memory. This tag list must eventually by freed by calling @{"FreeTagItems()" LINK "FreeTagItems" 0}. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"AllocateTagItems()" LINK "AllocateTagItems" 0}, @{"FreeTagItems()" LINK "FreeTagItems" 0}, @{"RefreshTagItemClones()" LINK "RefreshTagItemClones" 0} @ENDNODE @NODE "Date2Amiga" "utility.library/Date2Amiga()" @{jcenter} @{u}@{b}Date2Amiga@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} Date2Amiga - calculate seconds from 01-Jan-1978. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} seconds = Date2Amiga(date); D0 A0 ULONG Date2Amiga(struct @{"ClockData" LINK "utility/date.h/MAIN" 23} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Calculates the number of seconds from 01-Jan-1978 to the date specified in the @{"ClockData" LINK "utility/date.h/MAIN" 23} structure. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 15}date - pointer to a @{"ClockData" LINK "utility/date.h/MAIN" 23} structure containing the date of interest. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} seconds - the number of seconds from 01-Jan-1978 to the date specified. @{lindent 4} @{fg shine}@{b}WARNING@{ub}@{fg text}@{lindent 8} This function does no sanity checking of the data in the @{"ClockData" LINK "utility/date.h/MAIN" 23} structure. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"Amiga2Date()" LINK "Amiga2Date" 0}, @{"CheckDate()" LINK "CheckDate" 0} @ENDNODE @NODE "FilterTagChanges" "utility.library/FilterTagChanges()" @{jcenter} @{u}@{b}FilterTagChanges@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} FilterTagChanges - eliminate tags which specify no change. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} FilterTagChanges(changeList,originalList,apply); A0 A1 D0 VOID FilterTagChanges(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *, struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *, ULONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} This function goes through changeList. For each item found in changeList, if the item is also present in originalList, and their data values are identical, then the tag is removed from changeList. If the two tag's data values are different and the 'apply' value is non-zero, then the tag data in originalList will be updated to match the value from changeList. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} changeList - list of new tags (may be NULL) originalList - a list of existing tags (may be NULL) @{lindent 16}apply - boolean specification as to whether the data values in originalList are to be updated to the data values in changeList. @{lindent 4} @{fg shine}@{b}EXAMPLE@{ub}@{fg text}@{lindent 8} Assume you have an attribute list for an object (originalList) which looks like this: @{lindent 12} {ATTR_Size, "large"}, {ATTR_Color, "orange"}, {ATTR_Shape, "square"} @{lindent 8} If you receive a new tag list containing some changes (changeList), which looks like this: @{lindent 12} {ATTR_Size, "large"}, {ATTR_Shape, "triangle"} @{lindent 8} If you call FilterTagChanges(), changeList will be modified to contain only those attributes which are different from those in originalList. All other items will have their tag values set to TAG_IGNORE. The resulting changeList will become: @{lindent 12} {TAG_IGNORE, "large"}, {ATTR_Shape, "triangle"} @{lindent 8} If 'apply' was set to 0, originalList would be unchanged. If 'apply' was non-zero, originalList would be changed to: @{lindent 12} {ATTR_Size, "large"}, {ATTR_Color, "orange"}, {ATTR_Shape, "triangle"} @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"ApplyTagChanges()" LINK "ApplyTagChanges" 0} @ENDNODE @NODE "FilterTagItems" "utility.library/FilterTagItems()" @{jcenter} @{u}@{b}FilterTagItems@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} FilterTagItems - remove selected items from a tag list. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} numValid = FilterTagItems(tagList,filterArray,logic); D0 A0 A1 D0 ULONG FilterTagItems(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *,Tag *,ULONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Removes tag items from a tag list (by changing ti_Tag to TAG_IGNORE) depending on whether its ti_Tag value is found in an array of tag values. If the 'logic' parameter is TAGFILTER_AND, then all items not appearing in 'tagArray' are excluded from 'tagList'. If 'logic' is TAGFILTER_NOT, then items not found in 'tagArray' are preserved, and the ones in the array are cast out. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 18}tagList - input list of tag items which is to be filtered by having selected items changed to TAG_IGNORE.@{lindent 8} @{lindent 22}filterArray - an array of tag values, terminated by TAG_DONE, as specified in the documentation for @{"TagInArray()" LINK "TagInArray" 0}.@{lindent 8} @{lindent 16}logic - specification whether items in 'tagArray' are to be included or excluded in the filtered result. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} numValid - number of valid items left in resulting filtered list. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"TagInArray()" LINK "TagInArray" 0} @ENDNODE @NODE "FindNamedObject" "utility.library/FindNamedObject()" @{jcenter} @{u}@{b}FindNamedObject@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} FindNamedObject - find the next object of a given name. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} object = FindNamedObject(nameSpace, name, lastObject); D0 A0 A1 A2 @{lindent 45}struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *FindNamedObject(struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *, STRPTR, struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Finds an object and adds to the open count of the object. The object is guaranteed not to be freed until @{"ReleaseNamedObject()" LINK "ReleaseNamedObject" 0} is called. The name comparison is caseless, using the current locale string comparison routines. If name is NULL, then all objects will be matched. If lastObject is non-NULL, it must be an object from the same NameSpace found on a previous call to FindNamedObject(). It will not be freed by this call. The search will start at the node after lastobject, if non-NULL. NameSpace is the name space from the named object given or the root name space if NULL is given. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} nameSpace - the name space to search name - the name of the object to search for lastObject - the starting point for the search or NULL @{lindent 4} @{fg shine}@{b}RESULT@{ub}@{fg text}@{lindent 8} object - the first match found, or NULL for no match @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"ReleaseNamedObject()" LINK "ReleaseNamedObject" 0}, <@{"utility/name.h" LINK "utility/name.h/MAIN" 0}> @ENDNODE @NODE "FindTagItem" "utility.library/FindTagItem()" @{jcenter} @{u}@{b}FindTagItem@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} FindTagItem - scan a tag list for a specific tag. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} tag = FindTagItem(tagValue,tagList); D0 D0 A0 struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *FindTagItem(Tag,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Scans a tag list and returns a pointer to the first item with ti_Tag matching the 'tagValue' parameter. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} tagValue - tag value to search for tagList - tag item list to search (may be NULL) @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 14}tag - a pointer to the item with ti_Tag matching 'tagValue' or NULL if no match was found. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"GetTagData()" LINK "GetTagData" 0}, @{"PackBoolTags()" LINK "PackBoolTags" 0}, @{"NextTagItem()" LINK "NextTagItem" 0} @ENDNODE @NODE "FreeNamedObject" "utility.library/FreeNamedObject()" @{jcenter} @{u}@{b}FreeNamedObject@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} FreeNamedObject - frees a name object. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} FreeNamedObject(object); A0 VOID FreeNamedObject(struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Free one of a number of structures used by utility.library. The item must not be a member of any NameSpace, and no one may have it open other than yourself. If the object also contained a NameSpace, that namespace must be empty. Any additional space allocated via the datasize parameter for @{"AllocNamedObjectA()" LINK AllocNamedObjectA 0} is also released. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} object - the object to be freed @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"AllocNamedObjectA()" LINK "AllocNamedObjectA" 0} @ENDNODE @NODE "FreeTagItems" "utility.library/FreeTagItems()" @{jcenter} @{u}@{b}FreeTagItems@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} FreeTagItems - free an allocated tag list. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} FreeTagItems(tagList); A0 VOID FreeTagItems(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Frees the memory of a @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} list allocated either by @{"AllocateTagItems()" LINK "AllocateTagItems" 0} or @{"CloneTagItems()" LINK "CloneTagItems" 0}. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 18}tagList - list to free, must have been obtained from @{"AllocateTagItems()" LINK "AllocateTagItems" 0} or @{"CloneTagItems()" LINK "CloneTagItems" 0} (may be NULL) @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"AllocateTagItems()" LINK "AllocateTagItems" 0}, @{"CloneTagItems()" LINK "CloneTagItems" 0} @ENDNODE @NODE "GetTagData" "utility.library/GetTagData()" @{jcenter} @{u}@{b}GetTagData@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} GetTagData - obtain the data corresponding to a tag. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} value = GetTagData(tagValue,defaultVal,tagList); D0 D0 D1 A0 ULONG GetTagData(Tag,ULONG,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Searches a tag list for a matching tag, and returns the corresponding ti_Data value for the @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} found. If no match is found, this function returns the value passed in as 'default'. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} tagValue - tag value to search for. defaultVal - value to be returned if tagValue is not found. tagList - the tag list to search. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 16}value - the ti_Data value for the first matching @{"TagItem" LINK "libraries/xpk.h/MAIN" 34}, or 'default' if a ti_Tag matching 'Tag' is not found. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"FindTagItem()" LINK "FindTagItem" 0}, @{"PackBoolTags()" LINK "PackBoolTags" 0}, @{"NextTagItem()" LINK "NextTagItem" 0} @ENDNODE @NODE "GetUniqueID" "utility.library/GetUniqueID()" @{jcenter} @{u}@{b}GetUniqueID@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} GetUniqueID - return a relatively unique number. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} id = GetUniqueID(); D0 ULONG GetUniqueID(VOID); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Returns a unique value each time it is called. This is useful for things that need unique ID such as the GadgetHelp ID, etc. Note that this is only unique for 4,294,967,295 calls to this function. Under normal use this is not a problem. This function is safe in interrupts. @{lindent 4} @{fg shine}@{b}RESULT@{ub}@{fg text}@{lindent 8} id - a 32-bit value that is unique. @ENDNODE @NODE "MapTags" "utility.library/MapTags()" @{jcenter} @{u}@{b}MapTags@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} MapTags - convert ti_Tag values in a list via map pairing. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} MapTags(tagList,mapList,mapType); A0 A1 D0 VOID MapTags(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *,ULONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Apply a "mapping list" mapList to tagList. If the ti_Tag field of an item in tagList appears as ti_Tag in some item in mapList, overwrite ti_Tag with the corresponding ti_Data from the map list. The mapType parameter specifies how the mapping operation is to proceed, with the following available types: @{lindent 12} MAP_REMOVE_NOT_FOUND If a tag in tagList does not appear in the mapList, remove it from tagList. MAP_KEEP_NOT_FOUND To have items which do not appear in the mapList survive the mapping process as-is. @{lindent 8} MapTags() is central to BOOPSI gadget interconnections where you want to convert the tag values from one space (the sender) to another (the receiver). The procedure will change the values of the input tag list tagList (but not mapList). You can "filter" a list by passing MAP_REMOVE_NOT_FOUND as mapType, and having the data items in mapList equal the corresponding tags. You can perform the inverse filter ("everything but") by passing a mapType of MAP_KEEP_NOT_FOUND, and creating a map item for every tag you want to filter out, pairing it with a mapped data value of TAG_IGNORE. For safety and "order independence" of tag item arrays, if you attempt to map some tag to the value TAG_DONE, the value TAG_IGNORE will be substituted instead. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 18}tagList - input list of tag items which is to be mapped to tag values as specified in mapList.@{lindent 8} @{lindent 18}mapList - a "mapping list" tag list which pairs tag values expected to appear in tagList with new values to be substituted in the ti_Tag fields of tagList (may be NULL)@{lindent 8} @{lindent 18}mapType - one of the available mapping types as defined in <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}> @{lindent 4} @{fg shine}@{b}EXAMPLE@{ub}@{fg text}@{lindent 8} /* Consider this source list: */ struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} list[] = { {MY_SIZE, 71}, {MY_WEIGHT, 200}, {TAG_DONE, } }; /* And the mapping list: */ struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} map[] = { {MY_SIZE, HIS_TALL}, {TAG_DONE, } }; /* Then after MapTags(list,map,MAP_REMOVE_NOT_FOUND), 'list' will become: */ {HIS_TALL,71}, {TAG_IGNORE,}, {TAG_DONE,} /* Or after MapTags(list,map,MAP_KEEP_NOT_FOUND), 'list' will become: */ {HIS_TALL, 71}, {MY_WEIGHT, 200}, {TAG_DONE, } @{lindent 4} @{fg shine}@{b}BUGS@{ub}@{fg text}@{lindent 8} Prior to V39, the mapType parameter did not work. The function always behaved as if the parameter was set to MAP_KEEP_NOT_FOUND. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"ApplyTagChanges()" LINK "ApplyTagChanges" 0}, @{"FilterTagChanges()" LINK "FilterTagChanges" 0} @ENDNODE @NODE "NamedObjectName" "utility.library/NamedObjectName()" @{jcenter} @{u}@{b}NamedObjectName@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} NamedObjectName - return the name of the object. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} name = NamedObjectName(object); D0 A0 STRPTR NamedObjectName(struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Returns the name of the object passed in... Note that the name string is passed back as just a pointer to a read-only name. If the object goes away, so does the name. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 17}object - the object, may be NULL in which case this function returns NULL. @{lindent 4} @{fg shine}@{b}RESULT@{ub}@{fg text}@{lindent 8} name - pointer to the name string, or NULL if 'object' is NULL. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"FindNamedObject()" LINK "FindNamedObject" 0}, @{"RemNamedObject()" LINK "RemNamedObject" 0} @ENDNODE @NODE "NextTagItem" "utility.library/NextTagItem()" @{jcenter} @{u}@{b}NextTagItem@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} NextTagItem - iterate through a tag list. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} tag = NextTagItem(tagItemPtr); D0 A0 struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *NextTagItem(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} **); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Iterates through a tag list, skipping and chaining as dictated by system tags. TAG_SKIP will cause it to skip the entry and a number of following tags as specified in ti_Data. TAG_IGNORE ignores that single entry, and TAG_MORE has a pointer to another array of tags (and terminates the current array!). TAG_DONE also terminates the current array. Each call returns either the next tagitem you should examine, or NULL when the end of the list has been reached. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 21}tagItemPtr - doubly-indirect reference to a @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} structure. The pointer will be changed to keep track of the iteration. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 18}nextTag - each @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} in the array or chain of arrays that should be processed according to system tag values defined in <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>) is returned in turn with successive calls. @{lindent 4} @{fg shine}@{b}EXAMPLE@{ub}@{fg text}@{lindent 8} Iterate(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *tags) { struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *tstate; struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *tag; tstate = tags; while (tag = NextTagItem(&tstate)) { switch (tag->ti_Tag) { case TAG1: ... break; case TAG2: ... break; ... } } } @{lindent 4} @{fg shine}@{b}WARNING@{ub}@{fg text}@{lindent 8} Do NOT use the value of *tagItemPtr, but rather use the pointer returned by NextTagItem(). @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"GetTagData()" LINK "GetTagData" 0}, @{"PackBoolTags()" LINK "PackBoolTags" 0}, @{"FindTagItem()" LINK "FindTagItem" 0} @ENDNODE @NODE "PackBoolTags" "utility.library/PackBoolTags()" @{jcenter} @{u}@{b}PackBoolTags@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} PackBoolTags - builds a "flag" word from a tag list. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} flags = PackBoolTags(initialFlags,tagList,boolMap); D0 D0 A0 A1 ULONG PackBoolTags(ULONG,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Picks out the boolean tag items in a tag list and converts them into bit-flag representations according to a correspondence defined by the tag list 'boolMap'. A boolean tag item is one where only the logical value of the ti_Data is relevant. If this field is 0, the value is FALSE, otherwise TRUE. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} @{lindent 23}initialFlags - a starting set of bit-flags which will be changed by the processing of TRUE and FALSE boolean tags in tagList.@{lindent 8} @{lindent 23}tagList - a @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} list which may contain several tag items defined to be boolean by their presence in boolMap. The logical value of ti_Data determines whether a tag item causes the bit-flag value related by boolMap to be set or cleared in the returned flag longword.@{lindent 8} @{lindent 23}boolMap - a tag list defining the boolean tags to be recognized, and the bit (or bits) in the returned longword that are to be set or cleared when a boolean Tag is found to be TRUE or FALSE in tagList. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 16}flags - the accumulated longword of bit-flags, starting with initialFlags and modified by each boolean tag item encountered. @{lindent 4} @{fg shine}@{b}EXAMPLE@{ub}@{fg text}@{lindent 8} /* define some nice user tag values ... */ enum mytags { tag1 = TAG_USER+1, tag2, tag3, tag4, tag5 }; /* this @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} list defines the correspondence between boolean tags * and bit-flag values. */ struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} boolMap[] = { {tag1, 0x0001}, {tag2, 0x0002}, {tag3, 0x0004}, {tag4, 0x0008}, {TAG_DONE, } }; /* You are probably passed these by some client, and you want * to "collapse" the boolean content into a single longword. */ struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} boolExample[] = { {tag1, TRUE}, {tag2, FALSE}, {tag5, Irrelevant}, {tag3, TRUE}, {TAG_DONE, } }; /* Perhaps 'boolFlags' already has a current value of 0x800002. */ boolFlags = PackBoolTags(boolFlags,boolExample,boolMap); /* The resulting new value of 'boolFlags' will be 0x80005. /* @{lindent 4} @{fg shine}@{b}WARNING@{ub}@{fg text}@{lindent 8} In a case where there is duplication of a tag in tagList, the last of the identical tags will hold sway. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"GetTagData()" LINK "GetTagData" 0}, @{"FindTagItem()" LINK "FindTagItem" 0}, @{"NextTagItem()" LINK "NextTagItem" 0} @ENDNODE @NODE "PackStructureTags" "utility.library/PackStructureTags()" @{jcenter} @{u}@{b}PackStructureTags@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} PackStructureTags - pack a structure with values from taglist. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} num = PackStructureTags(pack,packTable,tagList); D0 A0 A1 A2 ULONG PackStructureTags(APTR,ULONG *,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} For each table entry, a @{"FindTagItem()" LINK "FindTagItem" 0} will be done and if the matching tag is found in the taglist, the data field will be packed into the given structure based on the packtable definition. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} pack - a pointer to the data area to fill in. @{lindent 20}packTable - a pointer to the packing information table. See <@{"utility/pack.h" LINK "utility/pack.h/MAIN" 0}> for definition and macros.@{lindent 8} @{lindent 18}tagList - a pointer to the taglist to pack into the structure @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} num - the number of tag items packed @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/pack.h" LINK "utility/pack.h/MAIN" 0}>, @{"FindTagItem()" LINK "FindTagItem" 0}, @{"UnpackStructureTags()" LINK "UnpackStructureTags" 0} @ENDNODE @NODE "RefreshTagItemClones" "utility.library/RefreshTagItemClones()" @{jcenter} @{u}@{b}RefreshTagItemClones@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} RefreshTagItemClones - rejuvenate a clone from the original. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} RefreshTagItemClones(clone,original) A0 A1 VOID RefreshTagItemClones(struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} If (and only if) the tag list 'clone' was created from 'original' by @{"CloneTagItems()" LINK "CloneTagItems" 0}, and if 'original' has not been changed in any way, you can reset the clone list to its original state by using this function. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} clone - return value from @{"CloneTagItems" LINK "CloneTagItems" 0}(original) original - a tag list that hasn't changed since @{"CloneTagItems()" LINK "CloneTagItems" 0} @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"CloneTagItems()" LINK "CloneTagItems" 0}, @{"AllocateTagItems()" LINK "AllocateTagItems" 0}, @{"FreeTagItems()" LINK "FreeTagItems" 0}, @{"ApplyTagChanges()" LINK "ApplyTagChanges" 0} @ENDNODE @NODE "ReleaseNamedObject" "utility.library/ReleaseNamedObject()" @{jcenter} @{u}@{b}ReleaseNamedObject@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} ReleaseNamedObject - free a named object. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} ReleaseNamedObject(object); A0 VOID ReleaseNamedObject(struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Decrements the open count of the object. If the object has been removed, and the count goes to 0, the remover will be notified that the object is now free. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} object - the object to release. (No action if NULL) @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"FindNamedObject()" LINK "FindNamedObject" 0}, @{"RemNamedObject()" LINK "RemNamedObject" 0} @ENDNODE @NODE "RemNamedObject" "utility.library/RemNamedObject()" @{jcenter} @{u}@{b}RemNamedObject@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} RemNamedObject - remove a named object. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} RemNamedObject(object, message); A0 A1 VOID RemNamedObject(struct @{"NamedObject" LINK "utility/name.h/MAIN" 24} *, struct @{"Message" LINK "exec/ports.h/MAIN" 46} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} This function will post a request to release the object from whatever NameSpace it is in. It will reply the message when the object is fully removed. The message.mn_Node.ln_Name field will contain the object pointer or NULL if the object was removed by another process. This function will effectively do a @{"ReleaseNamedObject()" LINK "ReleaseNamedObject" 0} thus you must have "found" the object first. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} object - the object to remove: Must be a valid @{"NamedObject" LINK "utility/name.h/MAIN" 24}. message - message to @{"ReplyMsg()" LINK "exec.guide/ReplyMsg" 0} (must be supplied) @{lindent 4} @{fg shine}@{b}RESULT@{ub}@{fg text}@{lindent 8} The message is replied with the ln_Name field either being the object or NULL. If it contains the object, the object is completely removed. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"AttemptRemNamedObject()" LINK "AttemptRemNamedObject" 0}, @{"AddNamedObject()" LINK "AddNamedObject" 0}, @{"ReleaseNamedObject()" LINK "ReleaseNamedObject" 0} @ENDNODE @NODE "SDivMod32" "utility.library/SDivMod32()" @{jcenter} @{u}@{b}SDivMod32@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} SDivMod32 - signed 32 by 32 bit division and modulus. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} quotient:remainder = SDivMod32(dividend,divisor); D0 D1 D0 D1 LONG:LONG SDivMod32(LONG,LONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Divides the signed 32 bit dividend by the signed 32 bit divisor and returns a signed 32 bit quotient and remainder. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} dividend - signed 32 bit dividend. divisor - signed 32 bit divisor. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} quotient - signed 32 quotient of the division. remainder - signed 32 remainder of the division. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Unlike other Amiga library function calls, the utility.library 32 bit math routines do NOT require A6 to be loaded with a pointer to the library base. A6 can contain anything the application wishes. This is in order to avoid overhead in calling them. In addition, the utility.library math routines preserve all address registers including A0 and A1 @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"SMult32()" LINK "SMult32" 0}, @{"UDivMod32()" LINK "UDivMod32" 0}, @{"UMult32()" LINK "UMult32" 0}, @{"SMult64()" LINK "SMult64" 0}, @{"UMult64()" LINK "UMult64" 0} @ENDNODE @NODE "SMult32" "utility.library/SMult32()" @{jcenter} @{u}@{b}SMult32@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} SMult32 - signed 32 by 32 bit multiply with 32 bit result. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = SMult32(arg1,arg2); D0 D0 D1 LONG SMult32(LONG,LONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Returns the signed 32 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} arg1, arg2 - numbers to multiply @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} result - the signed 32 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Unlike other Amiga library function calls, the utility.library 32 bit math routines do NOT require A6 to be loaded with a pointer to the library base. A6 can contain anything the application wishes. This is in order to avoid overhead in calling them. In addition, the utility.library math routines preserve all address registers including A0 and A1 @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"SDivMod32()" LINK "SDivMod32" 0}, @{"UDivMod32()" LINK "UDivMod32" 0}, @{"UMult32()" LINK "UMult32" 0}, @{"SMult64()" LINK "SMult64" 0}, @{"UMult64()" LINK "UMult64" 0} @ENDNODE @NODE "SMult64" "utility.library/SMult64()" @{jcenter} @{u}@{b}SMult64@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} SMult64 - signed 32 by 32 bit multiply with 64 bit result. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = SMult64(arg1,arg2); D0:D1 D0 D1 LONG SMult64(LONG,LONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Returns the signed 64 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} arg1, arg2 - numbers to multiply @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} result - the signed 64 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Unlike other Amiga library function calls, the utility.library 32 bit math routines do NOT require A6 to be loaded with a pointer to the library base. A6 can contain anything the application wishes. This is in order to avoid overhead in calling them. In addition, the utility.library math routines preserve all address registers including A0 and A1 @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"SDivMod32()" LINK "SDivMod32" 0}, @{"UDivMod32()" LINK "UDivMod32" 0}, @{"UMult32()" LINK "UMult32" 0}, @{"UMult64()" LINK "UMult64" 0} @ENDNODE @NODE "Stricmp" "utility.library/Stricmp()" @{jcenter} @{u}@{b}Stricmp@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} Stricmp - case-insensitive string comparison. @{fg shine}(V37)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = Stricmp(string1,string2); D0 A0 A1 LONG Stricmp(STRPTR,STRPTR); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} This function compares two strings, ignoring case using a generic case conversion routine. If the strings have different lengths, the shorter is treated as if it were extended with zeros. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} string1, string2 - strings to be compared @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 17}result - relationship between string1 and string2 <0 means string1 < string2 =0 means string1 = string2 >0 means string1 > string2 @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Whenever locale.library is installed in a system, this function is replaced by language-specific code. This means that depending on which language the user has currently selected, identical pairs of strings may return different values when passed to this function. This fact must be taken into consideration when using this function. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"Strnicmp()" LINK "Strnicmp" 0}, @{"locale.library/StrnCmp()" LINK "locale.guide/StrnCmp" 0} @ENDNODE @NODE "Strnicmp" "utility.library/Strnicmp()" @{jcenter} @{u}@{b}Strnicmp@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} Strnicmp - length-limited case-insensitive string compare. @{fg shine}(V37)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = Strnicmp(string1,string2,length); D0 A0 A1 D0 LONG Strnicmp(STRPTR,STRPTR,LONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} This function compares two strings, ignoring case using a generic case conversion routine. If the strings have different lengths, the shorter is treated as if it were extended with zeros. This function never compares more than 'length' characters. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} string1, string2 - strings to be compared length - maximum number of characters to examine @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} @{lindent 17}result - relationship between string1 and string2 <0 means string1 < string2 =0 means string1 = string2 >0 means string1 > string2 @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Whenever locale.library is installed in a system, this function is replaced by language-specific code. This means that depending on which language the user has currently selected, identical pairs of strings may return different values when passed to this function. This fact must be taken into consideration when using this function. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"Stricmp()" LINK "Stricmp" 0}, @{"locale.library/StrnCmp()" LINK "locale.guide/StrnCmp" 0} @ENDNODE @NODE "TagInArray" "utility.library/TagInArray()" @{jcenter} @{u}@{b}TagInArray@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} TagInArray - check if a tag value appears in an array of tag values. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = TagInArray(tagValue,tagArray); D0 D0 A0 BOOL TagInArray(Tag,Tag *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Performs a quick scan to see if a tag value appears in an array terminated with TAG_DONE. Returns TRUE if the value is found. The 'tagArray' must be terminated by TAG_DONE. Note that this is an array of tag values, NOT an array of TagItems. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} tagValue - tag value to search array for in array. tagArray - a simple array of tag values terminated by TAG_DONE. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} result - TRUE if tagValue was found in tagArray. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/tagitem.h" LINK "utility/tagitem.h/MAIN" 0}>, @{"FilterTagItems()" LINK "FilterTagItems" 0} @ENDNODE @NODE "ToLower" "utility.library/ToLower()" @{jcenter} @{u}@{b}ToLower@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} ToLower - convert a character to lower case. @{fg shine}(V37)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} char = ToLower(char); D0 D0 @{"UBYTE" LINK "exec/nodes.h/MAIN" 21} ToLower(@{"UBYTE" LINK "exec/nodes.h/MAIN" 21}); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Converts a character to lower case, handling international character sets. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} char - character to be converted. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} char - lower case version of the input character. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Whenever locale.library is installed in a system, this function is replaced by language-specific code. This means that depending on which language the user has currently selected, a given character may return different results when passed to this function. This fact must be taken into consideration when using this function. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"ToUpper()" LINK "ToUpper" 0}, @{"locale.library/ConvToLower()" LINK "locale.guide/ConvToLower" 0} @ENDNODE @NODE "ToUpper" "utility.library/ToUpper()" @{jcenter} @{u}@{b}ToUpper@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} ToUpper - convert a character to upper case. @{fg shine}(V37)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} char = ToUpper(char); D0 D0 @{"UBYTE" LINK "exec/nodes.h/MAIN" 21} ToUpper(@{"UBYTE" LINK "exec/nodes.h/MAIN" 21}); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Converts a character to upper case, handling international character sets. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} char - character to be converted. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} char - upper case version of input character. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Whenever locale.library is installed in a system, this function is replaced by language-specific code. This means that depending on which language the user has currently selected, a given character may return different results when passed to this function. This fact must be taken into consideration when using this function. @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"ToLower()" LINK "ToLower" 0}, @{"locale.library/ConvToLower()" LINK "locale.guide/ConvToLower" 0} @ENDNODE @NODE "UDivMod32" "utility.library/UDivMod32()" @{jcenter} @{u}@{b}UDivMod32@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} UDivMod32 - unsigned 32 by 32 bit division and modulus. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} quotient:remainder = UDivMod32(dividend,divisor); D0 D1 D0 D1 ULONG:ULONG UDivMod32(ULONG,ULONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Divides the unsigned 32 bit dividend by the unsigned 32 bit divisor and returns an unsigned 32 bit quotient and remainder. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} dividend - unsigned 32 bit dividend. divisor - unsigned 32 bit divisor. @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} quotient - unsigned 32 quotient of the division. remainder - unsigned 32 remainder of the division. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Unlike other Amiga library function calls, the utility.library 32 bit math routines do NOT require A6 to be loaded with a pointer to the library base. A6 can contain anything the application wishes. This is in order to avoid overhead in calling them. In addition, the utility.library math routines preserve all address registers including A0 and A1 @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"SDivMod32()" LINK "SDivMod32" 0}, @{"SMult32()" LINK "SMult32" 0}, @{"UMult32()" LINK "UMult32" 0} @ENDNODE @NODE "UMult32" "utility.library/UMult32()" @{jcenter} @{u}@{b}UMult32@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} UMult32 - unsigned 32 by 32 bit multiply with 32 bit result. @{fg shine}(V36)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = UMult32(arg1,arg2); D0 D0 D1 ULONG UMult32(ULONG,ULONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Returns the unsigned 32 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} arg1, arg2 - numbers to multiply @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} result - the unsigned 32 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Unlike other Amiga library function calls, the utility.library 32 bit math routines do NOT require A6 to be loaded with a pointer to the library base. A6 can contain anything the application wishes. This is in order to avoid overhead in calling them. In addition, the utility.library math routines preserve all address registers including A0 and A1 @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"SDivMod32()" LINK "SDivMod32" 0}, @{"SMult32()" LINK "SMult32" 0}, @{"UDivMod32()" LINK "UDivMod32" 0}, @{"SMult64()" LINK "SMult64" 0}, @{"UMult64()" LINK "UMult64" 0} @ENDNODE @NODE "UMult64" "utility.library/UMult64()" @{jcenter} @{u}@{b}UMult64@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} UMult64 - unsigned 32 by 32 bit multiply with 64 bit result. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} result = UMult64(arg1,arg2); D0:D1 D0 D1 ULONG UMult64(ULONG,ULONG); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} Returns the unsigned 64 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} arg1, arg2 - numbers to multiply @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} result - the unsigned 64 bit result of multiplying arg1 by arg2. @{lindent 4} @{fg shine}@{b}NOTES@{ub}@{fg text}@{lindent 8} Unlike other Amiga library function calls, the utility.library 32 bit math routines do NOT require A6 to be loaded with a pointer to the library base. A6 can contain anything the application wishes. This is in order to avoid overhead in calling them. In addition, the utility.library math routines preserve all address registers including A0 and A1 @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} @{"SDivMod32()" LINK "SDivMod32" 0}, @{"SMult32()" LINK "SMult32" 0}, @{"UDivMod32()" LINK "UDivMod32" 0}, @{"SMult64()" LINK "SMult64" 0} @ENDNODE @NODE "UnpackStructureTags" "utility.library/UnpackStructureTags()" @{jcenter} @{u}@{b}UnpackStructureTags@{ub}@{uu} @{jleft}@{lindent 4} @{fg shine}@{b}NAME@{ub}@{fg text}@{lindent 8} UnpackStructureTags - unpack a structure to values in taglist. @{fg shine}(V39)@{fg text} @{lindent 4} @{fg shine}@{b}SYNOPSIS@{ub}@{fg text}@{lindent 8} num = UnpackStructureTags(pack,packTable,tagList); D0 A0 A1 A2 ULONG UnpackStructureTags(APTR,ULONG *,struct @{"TagItem" LINK "libraries/xpk.h/MAIN" 34} *); @{lindent 4} @{fg shine}@{b}FUNCTION@{ub}@{fg text}@{lindent 8} For each table entry, a @{"FindTagItem()" LINK "FindTagItem" 0} will be done and if the matching tag is found in the taglist, the data in the structure will be placed into the memory pointed to by the tag's ti_Data. ti_Data *must* point to a LONGWORD. @{lindent 4} @{fg shine}@{b}INPUTS@{ub}@{fg text}@{lindent 8} pack - a pointer to the data area to be unpacked @{lindent 20}packTable - a pointer to the packing information table. See <@{"utility/pack.h" LINK "utility/pack.h/MAIN" 0}> for definition and macros@{lindent 8} tagList - a pointer to the taglist to unpack into @{lindent 4} @{fg shine}@{b}RESULTS@{ub}@{fg text}@{lindent 8} num - the number of tag items unpacked @{lindent 4} @{fg shine}@{b}SEE ALSO@{ub}@{fg text}@{lindent 8} <@{"utility/pack.h" LINK "utility/pack.h/MAIN" 0}>, @{"FindTagItem()" LINK "FindTagItem" 0}, @{"PackStructureTags()" LINK "PackStructureTags" 0} @ENDNODE