BigStringWalker.lss

%REM
	Class BigStringWalker
	Created Aug 17, 2017 by Sam Sirry
	Description: Very fast Mid$() alternative for LotusScript for working with large Strings.
%END REM
Public Class BigStringWalker
	Private Chars() As String
	Private ElementSize As Long	'the minimum length of each array element, in order to contain the whole big string.
	Private LenBSTotal As Long
	Private HighestUsedIndex As Long	'the index of the last used element in the internal array (Chars).
	
	'const:
	Private MinBound As Long
	Private MaxBound As Long
	
	
	Sub New(BigString As String)
		ReDim Chars(0 To 0)
		MinBound = -32768
		MaxBound =  32767
		
		Call Load(BigString)
	End Sub
	
	Public Sub Load(BigString As String)
		LenBSTotal = Len(BigString)
		If LenBSTotal = 0 Then
			ElementSize = 1
			ReDim Chars(MinBound To MinBound)
			HighestUsedIndex = MinBound
			Exit Sub
		End If
		
		ElementSize = Fix(LenBSTotal/(MaxBound - MinBound +1))
		If Fraction(LenBSTotal/(MaxBound - MinBound +1)) > 0 Then
			ElementSize = ElementSize +1
		End If
		
		If ElementSize = 1 Then
			ReDim Chars(MinBound To (MinBound + LenBSTotal - 1))
		Else
			ReDim Chars(MinBound To MaxBound)
		End If
		
		Dim LastIndex As Long
		Lastindex = MinBound -1
		Call Load_Internal(BigString, LastIndex, 1)
		HighestUsedIndex = LastIndex
	End Sub
	
%REM
		Sub Load_Internal
		Created Aug 17, 2017 by Sam Sirry
		Description: Recursive proc for chunking the big string and filling up the array
%END REM
	Private Sub Load_Internal(BigString As String, LastIndex As Long, ByVal HowDeep As Long)
		
		'MinChunkSize determines at which length we stop recursive calling and start processing the part in hand using Mid$() in a loop.
		' smaller number means more iterations and recursive calls, but less Mid$() calls.
		' so, it's call-stack vs Mid$()-calls balance. If set too small, may cause an Out of Stack Space error.
		Const MinChunkSize = 128	
		
		Dim LenBS As Long
		Dim PartsCount
		
		LenBS = Len(BigString)
		
		If LenBS <= ElementSize Then GoTo SplitToChars
		If LenBS <= MinChunkSize Then GoTo SplitToChars
		
		If HowDeep < 1 Then HowDeep = 1
		PartsCount = 8 * HowDeep
		
		Dim Part As String
		Dim PartSize As Long
		
		Dim SizeInSingle As Single
		SizeInSingle = LenBS/PartsCount
		
		PartSize = Fix(SizeInSingle)
		If Fraction(SizeInSingle) > 0 Then
			PartSize = PartSize + 1
		End If
		
		Dim i As Long
		Dim start As Long
		start = 1
		For i = 1 To PartsCount
			If start > LenBS Then Exit For
			Part = Mid$(BigString, start, PartSize)
			Call Me.Load_Internal(Part, LastIndex, HowDeep +1)
			Part = "" 'free mem
			start = start + PartSize
		Next
		
		GoTo Quit
		
SplitToChars:
		'When we're here BigString isn't really big anymore.
		Part = BigString	'make a local copy to work on
		Dim LenLastIndex As Long
		Dim LenPart As Long
		
		If LastIndex < MinBound Then
			LenLastIndex = ElementSize
		Else
			LenLastIndex = Len(Chars(LastIndex))
		End If
		
		'fill up any remaining space in the last used array element.
		LenPart = Len(Part)
		If LenLastIndex < ElementSize Then
			Dim remaining As Long
			remaining = ElementSize-LenLastIndex
			If LenPart > remaining Then
				Chars(LastIndex) = Chars(LastIndex) & Left$(Part, ElementSize-LenLastIndex)
				Part = Right$(Part, LenPart - (ElementSize-LenLastIndex))
				LenPart = Len(Part)
			Else
				Chars(LastIndex) = Chars(LastIndex) & Part
				Part = ""
				LenPart = 0
			End If
		End If
		
		If LenPart = 0 Then GoTo Quit
		
		Dim PartsInSingle As Single
		PartsInSingle = LenPart / ElementSize
		
		PartsCount = Fix(LenPart / ElementSize)
		If Fraction(PartsInSingle) > 0 Then
			PartsCount = PartsCount + 1
		End If
		
		start = 1
		For i = 1 To PartsCount
			LastIndex = LastIndex + 1
			Chars(LastIndex) = Mid$(Part, start, ElementSize)
			
			start = start + ElementSize
		Next
Quit:
		
	End Sub
	
%REM
		Property Get Size
		Created Aug 17, 2017 by Sam Sirry
		Description: The number of characters in the string.
%END REM
	Public Property Get Size As Long
		Size = LenBSTotal
	End Property
	
%REM
		Function FullString
		Created Aug 17, 2017 by Sam Sirry
		Description: Returns the full original string
%END REM
	Public Function FullString As String
		FullString = Join(Chars, "")
	End Function
	
%REM
		Function IsValidStringIndex
		Created Aug 18, 2017 by Sam Sirry
		Description: 
%END REM
	Private Function IsValidStringIndex(ByVal StringIndex As Long) As Boolean
		If LenBSTotal = 0 And Stringindex = 0 Then
			IsValidStringIndex = True
			
		ElseIf ElementSize = 0 Then
			IsValidStringIndex = False
			
		ElseIf StringIndex < 0 Then
			IsValidStringIndex = False
			
		ElseIf StringIndex > (LenBSTotal-1) Then
			IsValidStringIndex = False
			
		Else
			IsValidStringIndex = True
		End If
	End Function
%REM
		Function ArrayIndexOfStringIndex
		Created Aug 18, 2017 by Sam Sirry
		Description: This proc does no validation of input. Caller must valdate before calling.
%END REM
	Private Function ArrayIndexOfStringIndex(ByVal StringIndex As Long) As Long
		ArrayIndexOfStringIndex = MinBound + Fix(StringIndex/ElementSize)
	End Function
	
%REM
		Function CharAt
		Created Aug 17, 2017 by Sam Sirry
		Description: Returns a single character ***Index is Zero-Based***
%END REM
	Public Function CharAt(ByVal StringIndex As Long) As String
%REM
		If LenBSTotal = 0 Then Exit Function
		If index < 0 Then Error 5, "The index may not be negative."
%END REM
		If Not IsValidStringIndex(StringIndex) Then
			Error 5, "The StringIndex value is not valid, or this object's instance is not initialized."
			Exit Function
		End If
		
		
		If StringIndex > LenBSTotal-1 Then Exit Function
		
		If ElementSize = 1 Then
			CharAt = Chars(ArrayIndexOfStringIndex(StringIndex))
		Else
			Dim charindex As Long
			charindex = StringIndex Mod ElementSize
			
			CharAt = Mid$(Chars(ArrayIndexOfStringIndex(StringIndex)), charindex+1, 1)
		End If
	End Function
	
	
%REM
		Function SubString
		Created Aug 18, 2017 by Sam Sirry
		Description: Returns a part of the BigString. indexes are zero-based. when start index = end index the return is empty string.
%END REM
	Public Function SubString(ByVal start_idx As Long, ByVal end_idx As Long) As String
		Dim firstElement As Long
		Dim lastElement As Long
		
		If Not IsValidStringIndex(start_idx) Then
			Error 5, "The start_idx value is not valid."
			Exit Function
		End If
		
		If start_idx = end_idx Then Exit Function	'return empty string.
		If end_idx > LenBSTotal Then
			end_idx = LenBSTotal-1 +1	'+1 is added because when start=end the return is nothing.
		End If
		If end_idx < start_idx Then Error 5, "end_idx may not be smaller than start_idx."	'start_idx can't be past the bigstring length coz it's been validated earlier.
		If end_idx - start_idx = 1 Then
			SubString = Me.CharAt(start_idx)
		End If
		
		firstElement = ArrayIndexOfStringIndex(start_idx)
		lastElement = ArrayIndexOfStringIndex(end_idx)
		
		Dim charindex As Long
		
		If firstElement = lastElement Then
			charindex = start_idx Mod ElementSize
			SubString = Mid$(Chars(firstElement), charindex+1, (end_idx - start_idx))
		Else
			Dim i As Long
			'only use Buffer when necessary. This makes a big difference if the caller requests too many small substrings in a loop.
			If lastElement - firstElement > 128 Then	'128 wasn't selected with any imperical study. it's purely based on personal estimation.
				Dim sb As Buffer
				Set sb = New Buffer
				
				charindex = start_idx Mod ElementSize
				Call sb.append(Mid$(Chars(firstElement), charindex+1))
				
				For i = (firstElement+1) To (lastElement-1)
					Call sb.append(Chars(i))
				Next
				
				charindex = end_idx Mod ElementSize
				If charindex > 0 Then Call sb.append(Left$(Chars(lastElement), charindex))
				SubString = sb.toString()
				
			Else
				Dim s_out As String
				
				charindex = start_idx Mod ElementSize
				s_out = Mid$(Chars(firstElement), charindex+1)
				
				For i = (firstElement+1) To (lastElement-1)
					s_out = s_out & Chars(i)
				Next
				
				charindex = end_idx Mod ElementSize
				If charindex > 0 Then s_out = s_out & Left$(Chars(lastElement), charindex)
				SubString = s_out
			End If
		End If
		
	End Function
	
%REM
		Function Slice
		Created Aug 18, 2017 by Sam Sirry
		Description: Returns a part of the BigString. start index is zero-based. size is the number of characters to be returned.
%END REM
	Public Function Slice(ByVal start_idx As Long, ByVal size As Long) As String
		Dim end_idx As Long
		end_idx = start_idx + size
		Slice = SubString(start_idx, end_idx)
	End Function
	
End Class