'**********************************************************************************************************
' Nazwa:                ileWystapien
' Autor:                mielk | 2012-01-17
'
' Opis:                 Funkcja zlicza liczbę wystąpień jednego ciągu znaków w innym ciągu znaków.
'
' Argumenty:
'   tekst               Tekst bazowy, który będzie przeszukiwany pod kątem występowania w nim tekstu
'                       [szukanyTekst].
'                       * Podana wartość powinna być tekstem. Wartości innych typów w miarę możliwości są
'                         konwertowane do typu String.
'
'   szukanyTekst        Poszukiwany tekst, którego liczba wystąpień w tekście bazowym będzie zwrócona
'                       w wyniku tej funkcji.
'                       * Podana wartość powinna być tekstem. Wartości innych typów w miarę możliwości są
'                         konwertowane do typu String.
'
'   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:
'   Integer             Liczba wystąpień ciągu znaków [szukanyTekst] w ciągu znaków [bazowyTekst].
'                       * Fragmenty tekstu bazowego traktowane jako wystąpienie podciągu [szukanyTekst]
'                         mogą się na siebie nakładać.
'                         Przykładowo, przy określaniu liczby wystąpień podciągu 'aa' w tekście 'baaa'
'                         funkcja odnajdzie dwa wystąpienia:
'                           - pierwsze, składające się z drugiego i trzeciego znaku tekstu bazowego,
'                           - drugie, składające się z trzeciego i czwartego znaku tekstu bazowego,
'                         Jak widać znak [a] znajdujący się na trzeciej pozycji w tekście bazowym jest
'                         równocześnie składnikiem obu wystąpień poszukiwanego tekstu.
'                       * Jeżeli parametr [szukanyTekst] jest pustym tekstem, zwracana jest liczba 0.
'
'
' --- Zmiany ----------------------------------------------------------------------------------------------
' 2012-01-17    mielk       Utworzenie funkcji.
'**********************************************************************************************************
Public Function ileWystapien(tekst As String, szukanyTekst As String, _
                                           Optional wielkoscZnakowMaZnaczenie As Boolean = True) As Integer
    Const NAZWA_METODY As String = "ileWystapien"
    '------------------------------------------------------------------------------------------------------
    Dim iPozycja As Integer
    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                                                                                              '|
    '----------------------------------------------------------------------------------------------------|



    'Sprawdza czy oba parametry - tekst i szukanyTekst - mają przynajmniej jeden znak. ------------------|
    'W przeciwnym razie powinna zostać zwrócona wartość 0, więc nie ma sensu kontynuować działania      '|
    'funkcji.                                                                                           '|
    If VBA.Len(tekst) > 0 And VBA.Len(szukanyTekst) > 0 Then                                            '|
                                                                                                        '|
        '--------------------------------------------------------------------------------------------|  '|
        Do                                                                                          '|  '|
            'W każdej iteracji pętli wyszukiwana jest pozycja pierwszego wystąpienia szukanego      '|  '|
            'tekstu w tekście bazowym (za pomocą funkcji VBA.InStr). Za każdym razem                '|  '|
            'przeszukiwanie rozpoczyna się od miejsca, w którym znajdowało się poprzednie           '|  '|
            'wystąpienie szukanego fragmentu (lub od początku tekstu bazowego, jeżeli jest to       '|  '|
            'pierwsza iteracja tej pętli).                                                          '|  '|
            iPozycja = VBA.InStr(iPozycja + 1, tekst, szukanyTekst, uMetodaPorownania)              '|  '|
                                                                                                    '|  '|
            'Jeżeli w tekście bazowym znaleziony został szukany fragment, liczba wystąpień          '|  '|
            'zwiększana jest o 1, a kolejne przeszukiwanie rozpocznie się od tego miejsca.          '|  '|
            'W przeciwnym razie pętla jest opuszczana i funkcja kończy swoje działanie.             '|  '|
            If iPozycja Then ileWystapien = ileWystapien + 1 Else Exit Do                           '|  '|
                                                                                                    '|  '|
        Loop                                                                                        '|  '|
        '--------------------------------------------------------------------------------------------|  '|
                                                                                                        '|
    End If                                                                                              '|
    '----------------------------------------------------------------------------------------------------|


End Function