'**********************************************************************************************************
' Nazwa:                fragment
' Autor:                mielk | 2011-07-20
'
' Opis:                 Funkcja zwraca fragment tekstu bazowego znajdujący się pomiędzy określonymi
'                       tekstami ograniczającymi.
'
'                       Z technicznego punktu widzenia, funkcja najpierw szuka pierwszego wystąpienia
'                       parametru [lewy]. Następnie wyznacza pierwsze wystąpienie parametru [prawy],
'                       począwszy od miejsca, w którym znalezione zostało lewe ograniczenie.
'                       Na końcu funkcja zwraca fragment tekstu znajdujący się pomiędzy wspomnianymi
'                       ograniczeniami.
'
' Argumenty:
'   tekst               Tekst bazowy.
'
'   lewy                Lewe ograniczenie.
'                       Wynikowy tekst będzie rozpoczynał się od następnego znaku po pierwszym wystąpieniu
'                       tego tekstu.
'                       Jeżeli ten argument jest pusty, tekst wynikowy będzie zawierał znaki od początku
'                       tekstu bazowego.
'
'   prawy               Prawe ograniczenie.
'                       Wynikowy tekst kończy się w miejscu, gdzie znalezione zostanie pierwsze wystąpienie
'                       tego tekstu.
'                       Jeżeli ten argument jest pustym ciągiem znaków, tekst wynikowy będzie zawierał
'                       wszystkie znaki, aż do końca tekstu bazowego.

'   wielkoscZnakowMaZnaczenie
'                       Opcjonalny argument typu Boolean.
'                       * Decyduje o tym, czy wielkość liter ma znaczenie podczas przeszukiwania tekstu
'                         bazowego.
'                       * Jeżeli wartość ta jest ustawiona na False, litery duże i małe są traktowane jako
'                         identyczne (np. a = A).
'                       * Jeżeli wartość ustawiona jest na True, funkcja rozróżnia litery wielkie i
'                         małe (np. a ? A).
'                       * Domyślna wartość tego parametru to True.
'
'
' Zwraca:
'   String              Fragment tekstu bazowego znajdujący się pomiędzy podanymi tekstami ograniczającymi
'                       [lewy] i [prawy].
'
'                       Funkcja zwróci pusty ciąg znaków, jeżeli:
'                           - tekst ograniczający [lewy] nie występuje w tekście bazowym,
'                           - tekst ograniczający [prawy] nie występuje w tekście bazowym, albo występuje
'                             wcześniej niż pierwszy tekst ograniczający.
'
'                       Jeżeli tekst ograniczający [lewy] jest pusty, tekst wynikowy będzie zawierał
'                       znaki od początku tekstu bazowego aż do pierwszego wystąpienia ograniczenia
'                       [prawy].
'
'                       Jeżeli tekst ograniczający [prawy] jest pusty, tekst wynikowy będzie zawierał
'                       znaki od pozycji tuż po pierwszym wystąpieniu ograniczenia [lewy], aż do końca
'                       tekstu bazowego.
'
'                       Przykłady:
'                       ---------------------------------------------------------------------------------
'                                     Funkcja fragment z parametrami       |     Wynik
'                               -------------------------------------------------------------
'                               fragment("abc", "a", "c", True)            |       b
'                               fragment("abC", "a", "c", True)            |
'                               fragment("abC", "a", "c", False)           |       b
'                               fragment("abc", "", "c", True)             |       ab
'                               fragment("abc", "a", "", True)             |       bc
'                               fragment("abC", "", "c", False)            |       ab
'                               fragment("abC", "", "c", True)             |
'                               fragment("[wartosc]", "[", "]", True)      |       wartosc
'                               fragment("[wartosc]", "[", "]", False)     |       wartosc
'                               fragment("aaabbb", "a", "b", True)         |       aa
'                               fragment("aaabbb", "a", "a", True)         |
'                               fragment("aaabbb", "", "ab", True)         |       aa
'                               fragment("aaabbb", "", "a", True)          |
'                               fragment("aaabbb", "b", "", True)          |       bb
'                               fragment("jeden dwa trzy", " ", " ", True) |       dwa
'                               fragment("jeden dwa trzy", " ", "", True)  |       dwa trzy
'
'
' --- Zmiany ----------------------------------------------------------------------------------------------
' 2011-07-20    mielk       Utworzenie funkcji.
'**********************************************************************************************************
Public Function fragment(tekst As String, lewy As String, prawy As String, _
                                                      Optional wielkoscZnakowMaZnaczenie As Boolean = True)
    Const NAZWA_METODY As String = "fragment"
    '------------------------------------------------------------------------------------------------------
    Dim lStart As Long
    Dim lKoniec As Long
    Dim uMetodaPorownania As VBA.VbCompareMethod
    '------------------------------------------------------------------------------------------------------


    'Zamienia podany przez użytkownika parametr typu Boolean [wielkoscZnakowMaZnaczenie] na jedną ze ----|
    'stałych enumeracji [VbCompareMethod].                                                              '|
    If wielkoscZnakowMaZnaczenie Then                                                                   '|
        uMetodaPorownania = VBA.vbBinaryCompare                                                         '|
    Else                                                                                                '|
        uMetodaPorownania = VBA.vbTextCompare                                                           '|
    End If                                                                                              '|
    '----------------------------------------------------------------------------------------------------|


    'Funkcja szuka pozycji podanych tekstów ograniczających [lewy] i [prawy] w tekście bazowym. ---------|
    If VBA.Len(lewy) Then                                                                               '|
        lStart = VBA.InStr(1, tekst, lewy, uMetodaPorownania)                                           '|
        lKoniec = VBA.InStr(lStart + VBA.Len(lewy), tekst, prawy, uMetodaPorownania)                    '|
    Else                                                                                                '|
        lStart = 1                                                                                      '|
        lKoniec = VBA.InStr(1, tekst, prawy, uMetodaPorownania)                                         '|
    End If                                                                                              '|
                                                                                                        '|
    If VBA.Len(prawy) = 0 Then lKoniec = VBA.Len(tekst) + 1                                             '|
                                                                                                        '|
    '----------------------------------------------------------------------------------------------------|




    'Jeżeli oba teksty ograniczające zostały znalezione, zwracany jest fragment tekstu ------------------|
    'znajdujący się pomiędzy nimi.                                                                      '|
    If lStart > 0 And lKoniec > 0 Then                                                                  '|
        fragment = VBA.Mid$(tekst, lStart + VBA.Len(lewy), lKoniec - lStart - VBA.Len(lewy))            '|
    End If                                                                                              '|
    '----------------------------------------------------------------------------------------------------|


End Function