@database StringNode.guide

@$VER: StringNode V3.10 - By Fabio Rotondo (C)Brighting Brain Brothers

This guide file has been created using AutoGuide V1.05 - By Fabio Rotondo (fsoft@intercom.it).

@node "Main" "Amiga Foundation Classes Module: StringNode"



                 ** StringNode_OO V3.0 - Original By Fabio Rotondo **

                     Part of The Amiga Foundation Classes

   @{" Introduction " link "StringNode_introduction" }             @{" Author's Infos " link "author" }           @{" Amiga Foundation Classes " LINK "afc.guide/main"}


   Requires: @{" NodeMaster_oo " LINK "NodeMaster.guide/main"}

   Base: $0002

   NEW COMMANDS                          BRIEF DESCRIPTION
   -------------------------------------------------------------------------
   @{" stringnode()                       " link "StringNode_StringNode" } Initailizes the object
   @{" add(string, mode)                  " link "StringNode_add" } Add a new string to the list
   @{" addr()                             " link "StringNode_addr"} Returns memory address of the list
   @{" change(string)                     " link "StringNode_change" } Changes the current object string
   @{" clear()                            " link "StringNode_clear"} Free all strings in list
   @{" del()                              " link "StringNode_del"} Deletes a string from the list
   @{" empty()                            " link "StringNode_empty"} Checks for empty list
   @{" first()                            " link "StringNode_first"} Pos on the first string in the list
   @{" insert(string)                     " link "StringNode_insert" } Inserts a new string AFTER the current one
   @{" item(num)                          " link "StringNode_item"} Pos on a specific item
   @{" last()                             " link "StringNode_last"} Pos on the last String in the list
   @{" numitems()                         " link "StringNode_numitems"} Returns the number of strings in the list
   @{" obj()                              " link "StringNode_obj" } Returns the current string.
   @{" pop(pos=TRUE)                      " link "StringNode_pop"} Pops to the current stacked string
   @{" pos()                              " link "StringNode_pos"} Returns numeric position of a string in the list
   @{" prev()                             " link "StringNode_prev"} Pos on the previous string in the list
   @{" push()                             " link "StringNode_push"} Pushes current string in the stack
   @{" search(string, fromhere=FALSE)     " link "StringNode_search" } Search for a specific string
   @{" setattrs(taglist)                  " link "StringNode_setattrs" } Change StringNode's behaviours
   @{" sort(nocase=FALSE, inverted=FALSE) " link "StringNode_sort" } Sort All Items By Name
   @{" succ()                             " link "StringNode_succ"} Pos on the next string in the list
   @{" version()                          " link "StringNode_version"} Returns Class version

   @{" Tags Table  " LINK "StringNode_tagstable" }

   @{" Error Table " LINK "StringNode_errortable"}

@endnode

@node "stringnode_introduction"  "StringNode Introduction"

    StringNode is a object to handle lists of strings.

    These  lists  are  standard  Exec  lists  and  all  handling  functions are
inherited  by  the  ROOTCLASS  NodeMaster_oo.   But  StringNode has some unique
features  to  handle  correctly  strings  without memory loss or something like
that.   You  will also have the method "addr()" to get a pointer to the List so
you can easily add a list of items to a ListView gadget!

    Main features are:

        * Very Fast String Sorting Algorithm.

        * Very Flexible String Sorting Algo:

             - case (in)sensitive
             - from a...z or z...a

        * Search routines use AmigaDOS MatchNoPattern() functions!

             - You can do searches with patterns like:

                    "#?.IN#?" or "~(#?.INFO)" !!!

        * Return Raise() errors!

NEW V2.10 features:

    * Enhanced search() method: now it updates also numeric pos!

    * Enhanced sort() method:   now it is 60% faster than the original!

    * Enhanced change() method: now allows less memory fragmentation.

    * Added a new (and expandible) method: setattrs().

      NOTE: a very big THANK YOU must go to Andrea Galimberti aka Kronos
            for helping me in creating a new and fast sort() method!!!

V3.00 features:

    * Restructured code.

    * Implemented new NodeMaster sort() method

    * Optimized code

    * Now StringNode is part of Amiga Foundation Classes

@endnode

@node "StringNode_tagstable" "Amiga Foundation Classes Modules: StringNode/TAGS TABLE"
    TAG NAME     |     VALUES(DEFAULT) | DESCRIPTION
-----------------+---------------------+-------------------------------------
TAGSTR_MAXCHARS  | 0..32768 (128)      | Max number of chars to leave unused.
@endnode

@node "StringNode_ErrorTable" "Amiga Foundation Classes Modules: StringNode/Error Table"
ERROR CODE       | DESCRIPTION
-----------------+-----------------------------------------------------------
     $0000       | No Memory
@endnode

@node author "Author(s) Info"

    Original By:  Fabio Rotondo  (fsoft@intercom.it)

    E Version By: Fabio Rotondo



    Address:

            Fabio Rotondo
            C.so Vercelli 9
            28100 Novara
            ITALY

            e-mail: fsoft@intercom.it
                    Fabio.Rotondo@deagostini.it

            Phone:  (ITA) - (0)321 -   459676  (home)
                    (ITA) - (0)2   - 38086520  (office)
                    (ITA) - (0)338 -  7336477  (GSM Phone)

            Fax:    (ITA) - (0)2   - 38086278

            Web:    http://www.intercom.it/~fsoft               (my home page)

                    http://www.intercom.it/~fsoft/ablast.html   (Amiga Blast Home Page)
@endnode

@node "stringnode_stringnode" "StringNode_oo/stringnode()"
           NAME: stringnode()

    DESCRIPTION: Use this command to initialize the object.

          INPUT: NONE

        RESULTS: NONE.

           NOTE: Starting from V2.10 TAGSTR_MAXCHARS value is set to 128.
                 Please, refer to @{" change() " LINK "StringNode_change" } and @{" setattrs() " LINK "StringNode_setattrs" } methods.

       SEE ALSO: @{" change() " LINK "StringNode_change" }
                 @{" setattrs() " LINK "StringNode_setattrs" }

                 @{" NodeMaster/change() " LINK "NodeMaster.guide/NodeMaster_change"}
@endnode

@node StringNode_add "Amiga Foundation Classes Modules: StringNode/add()"
           NAME: add(string:PTR TO CHAR)

    DESCRIPTION: Use this command to add a string to the list.

          INPUT: string     - PTR TO CHAR, the string you wish to add.

        RESULTS: a PTR to String            - No errors.
                 a Raise()d exception       - Possible problems.

       SEE ALSO: @{" NodeMaster/add() " LINK "NodeMaster.guide/NodeMaster_add"}
@endnode

@node StringNode_insert "Amiga Foundation Classes Modules: StringNode/insert()"
           NAME: insert(string:PTR TO CHAR)

    DESCRIPTION: Use this command to add a string AFTER the current one.

          INPUT: string     - PTR TO CHAR. String to insert.

        RESULTS: a PTR to String         - No Errors.
                 a Raise()d exception    - Problems.

       SEE ALSO: @{" NodeMaster/insert() " LINK "NodeMaster.guide/NodeMaster_insert"}
@endnode

@node StringNode_obj "Amiga Foundation Classes Modules: StringNode/obj()"
           NAME: obj()

    DESCRIPTION: This command returns the current node string.

          INPUT: NONE.

        RESULTS: A PTR TO CHAR to the current node string.

       SEE ALSO: @{" NodeMaster/obj() " LINK "NodeMaster.guide/NodeMaster_obj"}
@endnode

@node "StringNode_first" "Amiga Foundation Classes Modules: StringNode/first()"
           NAME: first()

    DESCRIPTION: This method pos the class to the first String in the list.

          INPUT: NONE

        RESULTS: a PTR to String    - first() succeded.

                 NIL                - first() failed. (Maybe list is empty)

       SEE ALSO: @{" NodeMaster/first() " LINK "NodeMaster.guide/NodeMaster_first"}

@endnode

@node "StringNode_succ" "Amiga Foundation Classes Modules: StringNode/succ()"
           NAME: succ()

    DESCRIPTION: This method pos the class to the next String in the list.

          INPUT: NONE

        RESULTS: a PTR to String    - succ() succeded.

                 NIL                - succ() failed. (We are on the last item)

       SEE ALSO: @{" NodeMaster/succ() " LINK "NodeMaster.guide/NodeMaster_succ"}

@endnode

@node "StringNode_prev" "Amiga Foundation Classes Modules: StringNode/prev()"
           NAME: prev()

    DESCRIPTION: This method pos the class to the previous String in the list.

          INPUT: NONE

        RESULTS: a PTR to String    - prev() succeded.

                 NIL                - prev() failed. (We are on the first item.)

       SEE ALSO: @{" NodeMaster/prev() " LINK "NodeMaster.guide/NodeMaster_prev"}

@endnode

@node "StringNode_push" "Amiga Foundation Classes Modules: StringNode/push()"
           NAME: push()

    DESCRIPTION: This method pushes current string on  the stack.

          INPUT: NONE

        RESULTS: TRUE   - push() succeded.

                 FALSE  - push() failed. (Stack is full)

       SEE ALSO: @{" pop() " LINK "StringNode_pop"}

                 @{" NodeMaster/push() " LINK "NodeMaster.guide/NodeMaster_push"}
@endnode

@node "StringNode_pop" "Amiga Foundation Classes Modules: StringNode/pop()"
           NAME: pop(pos=TRUE)

    DESCRIPTION: This method pops a stacked String.

          INPUT: pos    - (default = TRUE) if pos is set to TRUE, the StringNode
                          class focuses on the pop()ed string, if it is set to
                          FALSE, then the current stack String is just freed.

        RESULTS: a PTR to String    - pop() succeded.

                 NIL                - pop() failed or pos=FALSE.

       SEE ALSO: @{" push() " LINK "StringNode_push"}

                 @{" NodeMaster/pop() " LINK "NodeMaster.guide/NodeMaster_pop"}

@endnode

@node "StringNode_addr" "Amiga Foundation Classes Modules: StringNode/addr()"
           NAME: addr()

    DESCRIPTION: This method returns a PTR to the list allocated by StringNode.

          INPUT: NONE

        RESULTS: a PTR to an Exec List.

           NOTE: This function CANNOT fail: you should not be able to do an addr()
                 if the list isn't allocated because the object should raise an
                 exception during initialization.

       SEE ALSO: @{" NodeMaster/addr() " LINK "NodeMaster.guide/NodeMaster_addr"}

@endnode

@node "StringNode_del" "Amiga Foundation Classes Modules: StringNode/del()"
           NAME: del()

    DESCRIPTION: This method deletes current String in the list.

          INPUT: NONE

        RESULTS: a PTR to next avaible string or NIL if list is empty.

           NOTE: This method "moves" inside the list in a particular way:
                 if you are deleting a string which is NOT the last, then
                 StringNode will pos to the next item, if it was the last,
                 it tries to move to the previous String, if nothing is
                 avaible, then it returns NIL.

       SEE ALSO: @{" NodeMaster/del() " LINK "NodeMaster.guide/NodeMaster_del"}

@endnode

@node "StringNode_empty" "Amiga Foundation Classes Modules: StringNode/empty()"
           NAME: empty()

    DESCRIPTION: This method checks whether the list is empty or not.

          INPUT: NONE

        RESULTS: TRUE   - List is empty
                 FALSE  - At least one item is present

       SEE ALSO: @{" NodeMaster/empty() " LINK "NodeMaster.guide/NodeMaster_empty"}

@endnode

@node StringNode_change "Amiga Foundation Classes Modules: StringNode/change()"
           NAME: change(string:PTR TO CHAR)

    DESCRIPTION: Use this command to change the current node string.

          INPUT: string     - PTR TO CHAR, the new string you wish to replace
                              the existing one.

        RESULTS: a PTR to String      - No Errors
                 a Raise()d exception - Memory problems.

           NOTE: Starting from V2.10, this method behaves quite differently
                 than before, to allow better control towards memory
                 fragmentation's problems. Now, before DisposeLink()
                 and do a new String(), change() checks whether or not the
                 new string passed to it would fit inside the current memory
                 area and how many bytes should be left unused. If they are
                 less than TAGSTR_MAXCHARS (Default is 128), the string is not
                 Disposed() and created again. Of course, if the new string is
                 bigger than the original, a new string is created.


       SEE ALSO: @{" NodeMaster/change() " LINK "NodeMaster.guide/NodeMaster_change"}
                 @{" setattrs() " LINK "StringNode_setattrs" }
@endnode

@node "StringNode_clear" "Amiga Foundation Classes Modules: StringNode/clear()"
           NAME: clear()

    DESCRIPTION: This method clear all Strings in the list.

          INPUT: NONE

        RESULTS: the StringNode will be freed.

       SEE ALSO: @{" NodeMaster/clear() " LINK "NodeMaster.guide/NodeMaster_clear"}

@endnode

@node "StringNode_numitems" "Amiga Foundation Classes Modules: StringNode/numitems()"
           NAME: numitems()

    DESCRIPTION: This method returns the number of Strings inside the list.

          INPUT: NONE

        RESULTS: a LONG containing the number of Strings in the list.

           NOTE: if the list is empty, this method returns 0.

       SEE ALSO: @{" NodeMaster/numitems() " LINK "NodeMaster.guide/NodeMaster_numitems"}

@endnode

@node "StringNode_item" "Amiga Foundation Classes Modules: StringNode/item()"
           NAME: item(num)

    DESCRIPTION: This method to pos StringNode to the specific ordinal
                 String in the list.

          INPUT: num        - LONG. Ordinal value of String position in the list.

        RESULTS: a PTR to CHAR   - item() succeded.

                 NIL             - item() failed.

           NOTE: If num is greater than current items in the list, StringNode
                 will pos on the last item.

       SEE ALSO: @{" numitems() " LINK "StringNode_numitems"}

                 @{" NodeMaster/item() " LINK "NodeMaster.guide/NodeMaster_item"}
@endnode

@node "StringNode_last" "Amiga Foundation Classes Modules: StringNode/last()"
           NAME: last()

    DESCRIPTION: This method pos StringNode on the last String in the list.

          INPUT: NONE.

        RESULTS: a PTR to CHAR  - last() succeded.

                 NIL            - list is empty.

       SEE ALSO: @{" first() " LINK "StringNode_first"}
                 @{" item() " LINK "StringNode_item"}

                 @{" NodeMaster/last() " LINK "NodeMaster.guide/NodeMaster_last"}

@endnode

@node "StringNode_pos" "Amiga Foundation Classes Modules: StringNode/pos()"
           NAME: pos()

    DESCRIPTION: This method returns the numberic (ordinal) position
                 of the String in the list.

          INPUT: NONE

        RESULTS: a LONG value containing the ordinal position of the String
                 in the list.

           NOTE: If the StringNode is empty, this method returns 0.

       SEE ALSO: @{" item() " LINK "StringNode_item"}

                 @{" NodeMaster/numpos() " LINK "NodeMaster.guide/NodeMaster_numpos"}

@endnode

@node "StringNode_search" "Amiga Foundation Classes Modules: StringNode/search()"
           NAME: search(string:PTR TO CHAR, fromhere=FALSE)

    DESCRIPTION: Use this command to scan the list looking for a specific
                 string inside the node.

          INPUT: string     - PTR TO CHAR. Pattern string to search.
                              (Standard AmigaDOS match patterns)

                 fromhere   - A BOOL value.
                              TRUE  = Scan starting from current node.
                              FALSE = Scan starting from the first node.

        RESULTS: a PTR to String    - Searching successful.
                 FALSE              - Nothing found.


          NOTES: * Search is NOT case sensitive.

                 * Search support AmigaDOS MatchNoCase() functions.
                   So you can create Pattern String such as:

                    "#?.INFO" or "~(#?.info)" and so on.

                 * Search will position the current node to a valid value
                   IF Search() fails, the current node will not change.

       SEE ALSO:
@endnode

@node "StringNode_setattrs" "Amiga Foundation Classes Modules: StringNode/setattrs()"
           NAME: setattrs(tags:PTR TO LONG)

    DESCRIPTION: Use this command to change the way stringnode works.
                 At the moment just ONE single tag has been implemented,
                 but they'll grow as soon as new needs will raise.

          INPUT: setattrs     - This is a list of tags.
                              Please, refer to @{" TAGS TABLE " LINK "StringNode_TagsTable" }
                              to know what tags are implemented.

        RESULTS: NONE.

           NOTE: REMEMBER TO END THE LIST WITH TAG_END or 0!!!

       SEE ALSO: @{" change()   " LINK "StringNode_change" }
                 @{" Tags Table " LINK "StringNode_tagstable" }
@endnode

@node StringNode_sort "Amiga Foundation Classes Modules: StringNode/sort()"
           NAME: sort(nocase=FALSE, inverted=FALSE)

    DESCRIPTION: Use this command to sort by name all items in a object.

          INPUT: nocase     - (OPTIONAL) if you set this to TRUE, the sort will
                              be done without case sense (but it is slower...)

                 inverted   - (OPTIONAL) if you set this to TRUE, the sort will
                              be done hight to low and not low-2-high as
                              default.

        RESULTS: The list will be completely sorted up.

       SEE ALSO: @{" NodeMaster/sort() " LINK "NodeMaster.guide/NodeMaster_sort"}
@endnode

@node "StringNode_version" "Amiga Foundation Classes Modules: StringNode/version()"
           NAME: version()

    DESCRIPTION: This method returns StringNode version and revision values.

          INPUT: NONE

        RESULTS: this method returns TWO values, version and revision.

       SEE ALSO:
@endnode

