(deguix) replaced StrSort and updated documentation some more

git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@3482 212acab6-be3b-0410-9dea-997c60f758d6

Examples/StrFunc.nsi

@@ -17,6 +17,7 @@ ${StrStrAdv}
 ${StrTok}
 ${StrTrimNewLines}
 ${StrUpperCase}
+${StrSort}
 
 Section
 
@@ -131,6 +132,50 @@ strstradverror:
 strreperror:
   DetailPrint "FAILED StrRep test"
 
+  # test sorting
+  ${StrSort} $0 "This is just an example" " just" "" "ple" "0" "0"
+  StrCmp $0 "This is an exam" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "j" " " " " "0" "1"
+  StrCmp $0 "just" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "j" "" "" "0" "1"
+  StrCmp $0 "This is just an example" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "us" " " "" "0" "1"
+  StrCmp $0 "just an example" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "u" "" " " "0" "1"
+  StrCmp $0 "This is just" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "just" " " " " "0" "1"
+  StrCmp $0 "just" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "t" " " " " "0" "1"
+  StrCmp $0 "This" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "le" " " " " "0" "1"
+  StrCmp $0 "example" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "le" " " " " "1" "0"
+  StrCmp $0 " examp" 0 strsorterror
+  ${StrSort} $0 "an error has occured" "e" " " " " "0" "1"
+  StrCmp $0 "error" 0 strsorterror
+  ${StrSort} $0 "" "something" " " " " "0" "1"
+  StrCmp $0 "" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "j" " " " " "1" "1"
+  StrCmp $0 " just " 0 strsorterror
+  ${StrSort} $0 "This is just an example" "j" " " " " "1" "0"
+  StrCmp $0 " ust " 0 strsorterror
+  ${StrSort} $0 "This is just an example" "j" "" "" "1" "0"
+  StrCmp $0 "This is ust an example" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "us" " " "" "1" "0"
+  StrCmp $0 " jt an example" 0 strsorterror
+  ${StrSort} $0 "This is just an example" "u" "" " " "1" "0"
+  StrCmp $0 "This is jst " 0 strsorterror
+  ${StrSort} $0 "This is just an example" "just" " " " " "1" "0"
+  StrCmp $0 "  " 0 strsorterror
+  ${StrSort} $0 "an error has occured" "e" " " " " "1" "0"
+  StrCmp $0 " rror " 0 strsorterror
+  ${StrSort} $0 "" "something" " " " " "1" "0"
+  StrCmp $0 "" 0 strsorterror
+  DetailPrint "PASSED StrSort test"
+  Goto +2
+strsorterror:
+  DetailPrint "FAILED StrSort test"
+
   # test lower/upper case
   ${StrLowerCase} $0 "abcefghijklmnopqrstuvwxyz"
   ${StrUpperCase} $0 $0

Include/StrFunc.nsh

@@ -13,7 +13,7 @@ by Diego Pedroso (aka deguix)
   !define MUI_VERBOSE 3
 !endif
 
-!echo "$\r$\n----------------------------------------------------------------------$\r$\nNSIS String Functions Header File 1.01 - © 2004 Diego Pedroso$\r$\n----------------------------------------------------------------------$\r$\n$\r$\n"
+!echo "$\r$\n----------------------------------------------------------------------$\r$\nNSIS String Functions Header File 1.02 - © 2004 Diego Pedroso$\r$\n----------------------------------------------------------------------$\r$\n$\r$\n"
 
 !define StrClbGet "!insertmacro FUNCTION_STRING_StrClbGet"
 !define StrClbSet "!insertmacro FUNCTION_STRING_StrClbSet"
@@ -22,6 +22,7 @@ by Diego Pedroso (aka deguix)
 !define StrLowerCase "!insertmacro FUNCTION_STRING_StrLowerCase"
 !define StrNSISToIO "!insertmacro FUNCTION_STRING_StrNSISToIO"
 !define StrRep "!insertmacro FUNCTION_STRING_StrRep"
+!define StrSort "!insertmacro FUNCTION_STRING_StrSort"
 !define StrStr "!insertmacro FUNCTION_STRING_StrStr"
 !define StrStrAdv "!insertmacro FUNCTION_STRING_StrStrAdv"
 !define StrTok "!insertmacro FUNCTION_STRING_StrTok"
@@ -116,8 +117,8 @@ by Diego Pedroso (aka deguix)
 
       StrCmp $R0 "<" 0 +5
         StrLen $R0 $R2
-        IntOp $R0 $R0 - $R4
+        IntOp $R5 $R3 + $R4
-        IntOp $R0 $R0 - $R3
+        IntOp $R0 $R0 - $R5
         Goto +2
 
       StrCpy $R0 $R4
@@ -138,13 +139,13 @@ by Diego Pedroso (aka deguix)
 
 !macroend
 
-!macro FUNCTION_STRING_StrLoc_Call ResultVar String StrToSearchFor Direction
+!macro FUNCTION_STRING_StrLoc_Call ResultVar String StrToSearchFor OffsetDirection
 
-  !echo `$ {StrLoc} "${ResultVar}" "${String}" "${StrToSearchFor}" "${Direction}"$\r$\n`
+  !echo `$ {StrLoc} "${ResultVar}" "${String}" "${StrToSearchFor}" "${OffsetDirection}"$\r$\n`
 
   Push `${String}`
   Push `${StrToSearchFor}`
-  Push `${Direction}`
+  Push `${OffsetDirection}`
 
   Call StrLoc
 
@@ -525,11 +526,11 @@ by Diego Pedroso (aka deguix)
 
 !macroend
 
-!macro FUNCTION_STRING_StrTok_Call ResultVar StrToTokenizing Separators ResultPart SkipEmptyParts
+!macro FUNCTION_STRING_StrTok_Call ResultVar StrToTokenize Separators ResultPart SkipEmptyParts
 
-  !echo `$ {StrTok} "${ResultVar}" "${StrToTokenizing}" "${Separators}" "${ResultPart}" "${SkipEmptyParts}"$\r$\n`
+  !echo `$ {StrTok} "${ResultVar}" "${StrToTokenize}" "${Separators}" "${ResultPart}" "${SkipEmptyParts}"$\r$\n`
 
-  Push `${StrToTokenizing}`
+  Push `${StrToTokenize}`
   Push `${Separators}`
   Push `${ResultPart}`
   Push `${SkipEmptyParts}`
@@ -792,13 +793,13 @@ by Diego Pedroso (aka deguix)
 
 !macroend
 
-!macro FUNCTION_STRING_StrRep_Call ResultVar String StringToReplaceFor StringToBeReplacedWith
+!macro FUNCTION_STRING_StrRep_Call ResultVar String StringToReplace ReplacementString
 
-  !echo `$ {StrRep} "${ResultVar}" "${String}" "${StringToReplaceFor}" "${StringToBeReplacedWith}"$\r$\n`
+  !echo `$ {StrRep} "${ResultVar}" "${String}" "${StringToReplace}" "${ReplacementString}"$\r$\n`
 
   Push `${String}`
-  Push `${StringToReplaceFor}`
+  Push `${StringToReplace}`
-  Push `${StringToBeReplacedWith}`
+  Push `${ReplacementString}`
 
   Call StrReplace
 
@@ -806,6 +807,165 @@ by Diego Pedroso (aka deguix)
 
 !macroend
 
+!macro FUNCTION_STRING_StrSort
+
+  !ifndef FUNCTION_STRING_StrSort
+
+    !echo "$\r$\n----------------------------------------------------------------------$\r$\nAdvanced String Sort Function - © 2004 Diego Pedroso$\r$\n----------------------------------------------------------------------$\r$\n$\r$\n"
+
+    !define FUNCTION_STRING_StrSort
+    !undef StrSort
+    !define StrSort "!insertmacro FUNCTION_STRING_StrSort_Call"
+
+    Function AdvStrSort
+
+      # Prepare Variables
+
+      Exch $R7 ;Include Center string
+      Exch
+      Exch $R6 ;Include Left and Right strings
+      Exch 2
+      Exch $0 ;Right String
+      Exch 3
+      Exch $1 ;Left String
+      Exch 4
+      Exch $2 ;Center String
+      Exch 5
+      Exch $R0 ;String
+      Push $3
+      Push $4
+      Push $5
+      Push $R1
+      Push $R2
+      Push $R3
+      Push $R4
+      Push $R5
+
+      StrLen $3 $0
+      StrLen $4 $1
+      StrLen $5 $2
+      StrCpy $R1 0
+
+      # Center String Search
+
+      loop:
+        StrCpy $R3 $R0 $5 $R1
+        StrCmp $R3 "" error
+          StrCmp $R3 $2 done
+            IntOp $R1 $R1 + 1
+            Goto loop
+      done:
+
+      StrCpy $R5 $R1
+
+      IntOp $R1 $R1 - $4
+
+      # Left String Search
+
+      loop2:
+        StrCpy $R3 $R0 $4 $R1
+        StrCmp $R3 "" error2
+          StrCmp $R3 $1 done2
+            IntOp $R1 $R1 - 1
+            Goto loop2
+
+        error2:
+        StrCpy $R1 0
+        StrCpy $R3 0
+        Goto +2
+
+      done2:
+      StrCpy $R3 1
+
+      StrCpy $R4 $R0 $R5
+
+      StrCmp $R1 0 +2
+        StrCpy $R4 $R4 "" $R1
+
+      StrCmp $R3 1 0 +3
+        StrCmp $R6 0 0 +2
+          StrCpy $R4 $R4 "" $4
+
+      # Center String Addition
+
+      StrCmp $R7 0 +2
+        StrCpy $R4 $R4$2
+
+      StrCpy $R1 $R5
+      IntOp $R1 $R1 + $5
+
+      # Right String Search
+
+      loop3:
+
+        StrCpy $R3 $R0 $3 $R1
+        StrCmp $R3 "" error3
+          StrCmp $R3 $0 done3
+            IntOp $R1 $R1 + 1
+            Goto loop3
+
+        error3:
+        StrCpy $R1 0
+
+      done3:
+
+      IntOp $R5 $R5 + $5
+      StrCpy $R3 $R0 "" $R5
+
+      StrCmp $R1 0 +5
+        IntOp $R1 $R1 - $R5
+        StrCmp $R6 0 +2
+          IntOp $R1 $R1 + $3
+        StrCpy $R3 $R3 $R1
+
+      StrCpy $R4 $R4$R3
+
+      StrCpy $2 $R4
+      Goto +2
+
+        Error:
+        StrCpy $2 ""
+
+      # Return to User
+
+      Pop $R5
+      Pop $R4
+      Pop $R3
+      Pop $R2
+      Pop $R1
+      Pop $5
+      Pop $4
+      Pop $3
+      Pop $R0
+      Pop $R7
+      Pop $R6
+      Pop $0
+      Pop $1
+      Exch $2
+
+    FunctionEnd
+
+  !endif
+
+!macroend
+
+!macro FUNCTION_STRING_StrSort_Call ResultVar String CenterStr LeftStr RightStr IncludeLeftRightStr IncludeCenterStr
+
+  !echo `$ {StrSort} "${ResultVar}" "${String}" "${CenterStr}" "${LeftStr}" "${RightStr}" "${IncludeLeftRightStr}" "${IncludeCenterStr}"$\r$\n`
+
+  Push `${String}`
+  Push `${CenterStr}`
+  Push `${LeftStr}`
+  Push `${RightStr}`
+  Push `${IncludeLeftRightStr}`
+  Push `${IncludeCenterStr}`
+
+  Call AdvStrSort
+
+  Pop `${ResultVar}`
+
+!macroend
+
 !macro FUNCTION_STRING_StrTrimNewLines
 
   !ifndef FUNCTION_STRING_StrTrimNewLines

Include/StrFunc.txt

@@ -12,9 +12,12 @@ How to use
   Parameters are specified in this format: required (option1 | option2)
   [optional]
 
-  The stars in commands title (*****) are the function usefullness in my
+  The stars in command titles (*****) are the function usefulness in my
   opinion. 5 stars (*****) the function is much useful.
 
+  Any time when is mentioned "Default is" means that you can use the value
+  mentioned or keep blank, the result is the same.
+
   If you want a certain value (e.g. a text) to be language-specific, set a
   language string (using LangString) and define $(STRINGNAME) as value.
 
@@ -67,17 +70,17 @@ How to use
 
       "StrToSearchFor" + the string after where it was found in "String".
 
-    Example:
+    Example: 
 
       ${StrStr} $0 "This is just an example" "just"
 
       $0 = "just an example"
 
     =========================================================================
-    **                    ${StrLoc} ResultVar String StrToSearchFor Direction
+    **         ${StrLoc} ResultVar String StrToSearchFor OffsetDirection(>|<)
     =========================================================================
     Searches for "StrToSearchFor" in "String" and returns its location,
-    according to "Direction"
+    according to "OffsetDirection".
 
     Parameters:
 
@@ -90,15 +93,15 @@ How to use
       StrToSearchFor
       String to search in "String".
 
-      Direction
+      OffsetDirection(>|<)
-      Direction where the counter goes to. (Anything except < = To Right,
+      Direction where the counter goes to. Default is ">". (> = left to right,
-      < = To Left).
+      < = right to left)
 
     Result Value -> ResultVar:
 
-      Where "StrToSearchFor" is going to "direction".
+      Where "StrToSearchFor" is, according to "OffsetDirection".
 
-    Example:
+    Example: 
 
       ${StrLoc} $0 "This is just an example" "just" "<"
 
@@ -128,7 +131,7 @@ How to use
 
       ResultStrDirection (>|<)
       Where the result string will be based on in relation of "StrToSearchFor"
-      position. Default is ">" (to right) (< = To left, > = To right)
+      position. Default is ">" (to right). (< = To left, > = To right)
 
       DisplayStrToSearch (1|0)
       Display "StrToSearchFor" in the result. Default is "1" (True). (1 = True,
@@ -141,8 +144,8 @@ How to use
 
     Result Value -> ResultVar:
 
-      "StrToSearchFor" if "DisplayStrToSearch" is 1 + the result string the
+      "StrToSearchFor" if "DisplayStrToSearch" is 1 + the result string after
-      direction "ResultStrDirection" of the "StrToSearchFor".
+      or before "StrToSearchFor", depending on "ResultStrDirection".
 
     Result with Errors:
 
@@ -154,16 +157,16 @@ How to use
       When you put nothing in "String", will return an empty string and set
       error flag.
 
-    Example:
+    Example: 
 
       ${StrStrAdv} $0 "This is just an example" "is" "<" "<" "1" "1"
 
       $0 = "This"
 
     =========================================================================
-    *****        ${StrRep} ResultVar String StringToReplace ReplacementString
+    *****           ${StrRep} ResultVar String StrToReplace ReplacementString
     =========================================================================
-    Searches for all "StringToReplace" in "String" replacing those with
+    Searches for all "StrToReplaceFor" in "String" replacing those with
     "ReplacementString".
 
     Parameters:
@@ -172,12 +175,12 @@ How to use
       Destination where result is returned.
 
       String
-      String where to search "StringToReplaceIn".
+      String where to search "StrToReplaceFor".
 
-      StringToReplace
+      StrToReplaceFor
-      String to search for in "String".
+      String to search in "String".
 
-      ReplacementString
+      StringToBeReplacedWith
       String to replace "StringToReplace" when it is found in "String".
 
     Result Value -> ResultVar:
@@ -185,7 +188,7 @@ How to use
       "String" with all occurences of "StringToReplace" replaced with
       "ReplacementString".
 
-    Example:
+    Example: 
 
       ${StrRep} $0 "This is just an example" "an" "one"
 
@@ -195,7 +198,7 @@ How to use
     =========================================================================
     ****                                                  ${StrClbSet} String
     =========================================================================
-    Copy "String" to the clipboard.
+    Copy "String" to clipboard.
 
     Parameters:
 
@@ -234,7 +237,7 @@ How to use
       String where to search for "Separators".
 
       Separators
-      Characters to find in "StrToTokenizing".
+      Characters to find in "StrToTokenize".
 
       ResultPart
       The part want to be found in "StrToTokenize" between two "Separators".
@@ -249,7 +252,7 @@ How to use
 
       "StrToTokenize" part "Part" between two "Separators".
 
-    Examples:
+    Examples: 
 
       1) ${StrTok} $0 "This is, or is not, just an example" " ," "5" "1"
 
@@ -306,6 +309,57 @@ How to use
 
       $0 = "oh man!"
 
+    =========================================================================
+    *****              ${StrSort} ResultVar String CenterStr LeftStr RightStr
+                               IncludeLeftRightStr(1|0) IncludeCenterStr(1|0)
+    =========================================================================
+    Searches for "CenterStr" in "String", and returns only the value
+    between "LeftStr" and "RightStr", including or not the "CenterStr" using
+    "IncludeCenterStr" and/or the "LeftStr" and "RightStr" using
+    "IncludeLeftRightStr".
+
+    Parameters:
+
+      ResultVar
+      Destination where result is returned.
+
+      String
+      String where to search "CenterStr".
+
+      CenterStr
+      String to search in "String".
+
+      LeftStr
+      The first occurrence of "LeftStr" on the left of "CenterStr".
+      If it is an empty value, or was not found, will return
+      everything on the left of "CenterStr".
+
+      RightStr
+      The first occurrence of "RightStr" on the right of "CenterStr".
+      If it is an empty value, or was not found, will return
+      everything on the right of "CenterStr".
+
+      IncludeLeftRightStr(1|0)
+      Include or not the "LeftStr" and "RightStr" in the result value.
+      Default is 1 (True). (1 = True, 0 = False)
+
+      IncludeCenterStr(1|0)
+      Include or not the "CenterStr" in the result value. Default is 1
+      (True). (1 = True, 0 = False)
+
+    Result Value -> ResultVar:
+
+      String between "LeftStr" and "RightStr" of a found "CenterStr"
+      including or not the "LeftStr" and "RightStr" if
+      "IncludeLeftRightStr" is 1 and/or the "CenterStr" if
+      "IncludeCenterStr" is 1.
+
+    Example: 
+
+      ${StrSort} $0 "This is just an example" " just" "" "ple" "0" "0"
+
+      $0 = "This is an exam"
+
     =========================================================================
     *                                     ${StrTrimNewLines} ResultVar String
     =========================================================================
@@ -332,7 +386,7 @@ How to use
     =========================================================================
     *****                                     ${StrNSISToIO} ResultVar String
     =========================================================================
-    Convert "String" from NSIS to be supported by Install Options plugin.
+    Converts "String" from NSIS to be supported by Install Options plugin.
     Escape, back-slash, carriage return, line feed and tab characters are
     converted.
 
@@ -382,35 +436,34 @@ How to use
 Comments about functions included and not included
 --------------------------------------------------
 
-12 functions have been included
+13 functions have been included
   7 were included was it was in Archive
-  4 were not included in Archive
+  5 were not included in Archive
-    AdvStrTok
+    StrTok
     NSISToIO
     IOToNSIS
     StrLoc
+    StrSort
   1 was been changed from original version
     StrClbGet
 
-11 functions were not been included
+12 functions have not been included
-  7 were not included because of better functions
+  8 were not included because of better functions
-    5 were not included because of AdvStrTok (called here as StrTok)
+    6 were not included because of AdvStrTok (called here as StrTok)
       First String Part Function
       Save on Variables Function
-      Sort Strings (1, and 2) Functions
+      Sort Strings (1, 2 and 3) Functions
       StrTok Function
     1 was not included because of NSISToIO and IOToNSIS
       Convert / to // in Paths Function
     1 was not included because of original String Replace Function (called
       here as StrRep)
       Another String Replace Function
-  2 were not included because isn't usefull anymore
+  2 were not included because isn't useful anymore
     Slash <-> Backslash Converter Function
     Trim Function
   1 was not included because of bugs
     Number to String Converter Function
-  1 removed by kichik
-    StrSort
 
 Comments
 ------------------------------------------------------------
@@ -421,6 +474,10 @@ Advanced Token String Function
   going to replace several functions with just one. The principal idea was
   based on "Save On Variables" by Afrow UK.
 
+Advanced String Sort Function
+
+  New function not published in Archive, much better than original StrSort.
+
 Another String Replace Function
 
   Another doesn't mean better and simpler than the original version.
@@ -455,12 +512,15 @@ Save on Variables Function
 
   AdvStrTok (called here as StrTok) is better.
 
-
 Slash <-> Backslash Converter Function
 
   Will convert "http://www.site.com\" to "http:\\www.site.com/", not
   really useful for anyone.
 
+Sort Strings (1, 2 and 3) Functions
+
+  AdvStrTok (called here as StrTok), AdvStrStr (called here as StrStrAdv)
+  and AdvStrSort (called here as StrSort) are better.
 
 Split String Function
 
@@ -478,18 +538,17 @@ Trim Function
   paths, and now with the NSIS command GetFullPathName this is not useful
   anymore.
 
-
 Version History
 ---------------
 
-1.02 (kichik) - 02/07/2004
+1.02 - 02/07/2004
 
- - Documentation fixes.
+- Fixed StrLoc.
- - Fixed StrLoc.
+- Fixed Documentation about StrLoc. "Direction" is really
- - Remove StrSort as it was giving too much trouble and it looks like it's
+"OffsetDirection".
-built for a very specific, nongeneric purpose.
+- Added my new AdvStrSort, and removed the old one.
 
-1.01 - 02/06/2004
+1.01 - 02/05/2004
 
 - Fixed Documentation about StrSort and StrTok.
 - Fixed StrTok default value for the string part. Now it's "L".
@@ -503,7 +562,7 @@ substrings one after another in a string.
 - Renamed header file to "StrFunc.nsh".
 - Added 1 function, StrLoc.
 - Modified StrStrAdv, removed some lines.
-- Fixed StrTok, 2 simple numbers made it loop everytime.
+- Fixed StrTok, 2 simple numbers made it loop every time.
 - Fixed some small issues in the header file.
 
 0.02 - 01/24/2004
@@ -522,10 +581,9 @@ Made by Diego Pedroso (aka deguix).
 Functions Credits
 -----------------
 
-- Advanced Search in String, Advanced Token String, String Localizator
+- Advanced Search in String, Advanced Token String, Localize in String
 made by Diego Pedroso.
 - Copy to/from clipboard made by Nik Medved.
-- Sort String 3 made by "Afrow UK".
 - StrUpper made by Dave Laundon.
 - StrReplace made by Hendri Adriaens.
 - Search in a string, Trim newlines made by Ximon Eighteen.