<-- Previous || Up || Next -->

Increment String Function
String Numerics Class

Public Function IncrementString( _
      ByVal vString As Variant _
    , Optional ByVal vFromAsc As Variant _
    , Optional ByVal vThruAsc As Variant _
    ) As Variant

Increments a string within a certain ASCII range.
Lengthens the string if it is already at or above the maximum value.

Examples: 
    IncrementString("ABBA") = "ABBB"
    IncrementString("ABBZ", "A", "Z") = "ABCA"
    IncrementString("ZZZZ", "A", "Z") = "AAAAA"
See also: 
    IncrementStringWithinCharacterSet Function
    AddStringCharacters Function
    IncrementStringSample Subroutine
Algorithm: The least-significant-byte of the string (the character at the end of the string) will have its ASCII value incremented by 1 (one). If that ASCII value is now outside of the range of values for characters at that position, then the overflow will be carried over to the previous character and it will be incremented, etc.

vString: The string which is to be incremented according to the rules described above. Function returns Null if vString is Null or cannot be fixed up to a String.

vFromAsc: String character or numeric ASCII value describing the lower bound of the range of characters which form the alphabet.
To summarize: If vFromAsc is a number, then that number is used as the lower bound of the range for all characters within vString. If vFromAsc is a string, then each character is used as the lower bound for the vString character which is in the same position. If vString is longer than vFromAsc, then the first character in vFromAsc is used as the lower bound for those vString characters which have no corresponding vFromAsc character. Note: Special argument fix-up code.

vFromAsc defaults to the ASCII value of the space character (" "; Chr$(32)) if it is an empty string. If vFromAsc is a non-empty string, then the ASCII value of each character will be used as the lower bound for the characters in that corresponding position in vString.

If vFromAsc is numeric (and not a numeric string) then that ASCII value will be used as the lower bound. vFromAsc defaults to the ASCII value of the space character (" "; Chr$(32)) if it neither string nor numeric.

vThruAsc: String character or numeric ASCII value describing the upper bound of the range of characters to be removed from string vValue.
To summarize: If vThruAsc is a number, then that number is used as the upper bound of the range for all characters within vString. If vThruAsc is a string, then each character is used as the upper bound for the vString character which is in the same position. If vString is longer than vThruAsc, then the first character in vThruAsc is used as the upper bound for those vString characters which have no corresponding vThruAsc character. Note: Special argument fix-up code.

vFromAsc defaults to the ASCII value of the tilde character ("~"; Chr$(126)) if it is an empty string. If vThruAsc is a non-empty string, then the ASCII value of each character will be used as the upper bound for the characters in that corresponding position in vString.

If vThruAsc is numeric (and not a numeric string) then that ASCII value will be used as the upper bound. vThruAsc defaults to the ASCII value of the tilde character ("~"; Chr$(126)) if it neither string nor numeric.

Note: This function assumes that the first string character represents the most-significant-byte within the string (this is the usual interpretation of string values).

Note: In the special case where vString is an empty string, this function will return a string containing the first character in the character set.
v1.1 BugFix: This function was incorrectly setting vFromAsc to the space character when vFromAsc was passed as a numeric value.

Copyright 1996-1999 Entisoft
Entisoft Tools is a trademark of Entisoft.