' Recieves OMR group zones information (e.g.: 0|1|0|0|0) and returns the mapped text of a dictionary
' the item with index 0 in the omrValues will be mapped with the item with index 0 in the dictionary
' if indicateError = true, then the first 3 values are reserved and must be present in the dictionary:
' item 1: error text if at least one uncertain marking is present -->   e.g. "- uncertain -"
' item 2: error text if more than one zone were selected -->            e.g. "- invalid multiple selection -"
' item 3: error text if no zone is marked (nothing is selected) -->     e.g. "- nothing selected -"

Public Function OMRSingleChoiceText(omrValues As String, markedZoneChar As String, delimiterChar As String, uncertainChar As String, indicateError As Boolean, indicateErrorText As String, dictionaryName As String) As String

   Dim dictItems() As String
   Dim tmpArray() As String

   Dim i As Integer
   Dim idx As Integer
   Dim countOfMarkedZones As Integer
   Dim markedIndex As Integer

   ' get dictionary items and store them into an array
   dictItems = DictionaryToArray(dictionaryName)
   tmpArray = Split(omrValues, delimiterChar)
   countOfMarkedZones = 0

   For i = 0 To UBound(tmpArray)
      ' count each marked zone and store last marked position
      If tmpArray(i) = markedZoneChar Then
         countOfMarkedZones += 1
         markedIndex = i
      End If
   Next

   idx = markedIndex
   If countOfMarkedZones = 0 Then idx = -1
   If countOfMarkedZones > 1 Then idx = -2
   If InStr(omrValues, uncertainChar) <> 0 Then idx = -3

   If indicateError Then
      ' easy - just increase the index as the amount of items within the dictionary have to match anyway
      idx += 3
   Else
      ' if the error text is not contained in the dictionary, then give back the error description set by the user
      If idx < 0 Then
         OMRSingleChoiceText = indicateErrorText
         Exit Function
      End If
   End If

   OMRSingleChoiceText = dictItems(idx)

End Function