5. Tekst uniwersalny

5.1. Struktury

MS_STRING

Struktura ciągu znaków, do której odwołują się wszystkie funkcje w module. Każde wywołanie funkcji tworzącej strukturę musi być wieńczone funkcją zwalniającą zasoby przydzielone dla obiektu, aby zapobiec wyciekom pamięci. Jest to spowodowane tym, że funkcje tworzące przydzielają pamięć dla unii oraz, w zależności od typu ciągu znaków, również dla pola zawierającego informacje o znakach w ciągu wielobajtowym. Szczegóły na temat struktury znajdują się w opisach poszczególnych pól.

Wartości domyślne pól struktury ustawiane podczas tworzenia tablicy:

Pole Wartość domyślna
Data unia
Length obliczany
Capacity parametr lub obliczany
Hash 0
Modifier 2.f
Wide automatycznie
Destroy automatycznie
Hashed false
MBInfo automatycznie
FuncIncrease MSS_ARRAYFUNCTIONS.IncMultiply
union Data

Unia dla trzech typów znaków, z czego jeden z nich jest typem automatycznym. Struktura dzięki temu polu jest uniwersalna, co oznacza, że może się w niej znajdować ciąg znaków typu char lub wchar_t, ale nigdy oba na raz. Wszystkie elementy w unii zajmują tą samą pamięć, więc możliwy jest bezkonfliktowy dostęp tylko do jednego pola.

char* Char

Ciąg znaków typu char. Pole to jest wykorzystywane w przypadku, gdy ciąg znaków posiada znaki jednobajtowe lub wielobajtowe. Dzięki temu polu, do ciągu można dostać się bezpośrednio bez rzutowania danych na typ.

wchar_t* Wide

Ciąg znaków typu wchar_t. Pole to jest wykorzystywane w przypadku, gdy ciąg znaków posiada znaki o typie wchar_t. Rozmiar znaków może być różny w zależności od systemu, więc mogą to być 2 lub 4 bajty. Dzięki temu polu, do ciągu można dostać się bezpośrednio bez rzutowania danych na typ.

tchar Auto

Ciąg znaków o typie automatycznym. Generalnie pole to nie jest wykorzystywane przez bibliotekę. Może być wykorzystane przez użytkownika, używającego typu tchar, który przyjmuje typ char lub wchar_t w zależności od ustawień biblioteki. Dzięki temu polu, do ciągu można dostać się bezpośrednio bez rzutowania danych na typ.

size_t Length

Ilość znaków w ciągu. Wartość ta reprezentuje aktualną długość tablicy i jest porównywana z pojemnością podczas dodawania znaków. Każdy ciąg znaków powinien kończyć się znakiem \0, który reprezentuje wartość NULL. Samodzielna zmiana tej wartości może wpływać na wyświetlanie i operacje na ciągu, dlatego nie należy jej modyfikować.

size_t Capacity

Pojemność tablicy, zawierającej ciąg znaków. Wartość ta odpowiada za ilość znaków, które mogą się jeszcze zmieścić w ciągu bez ponownego przydzielania miejsca na dodawane znaki. Wartość ta jest porównywana z wartością pola MS_STRING.Length. Gdy wartość jest za mała, uruchamiany zostaje podany inkreator, czyli funkcja zawierająca sposób obliczania nowej pamięci do alokacji. Wartość ta zarządzana jest wyłącznie przez bibliotekę i nie może być zmieniana samodzielnie.

size_t Hash

Skrót ciągu znaków w postaci 32 lub 64 bitowej liczby naturalnej. Ilość bitów dla skrótu można zmienić w ustawieniach biblioteki. Skrót wykorzystywany jest przy porównywaniu dwóch struktur, zawierających tablice znaków. Najczęściej przedstawiany jest w postaci szesnastkowej. Skrót tworzony jest bezpośrednio ze znaków i powinien być zmieniany w trakcie ich modyfikacji. Choć skrót powinien być unikalny dla dwóch różnych ciągów znaków, to niestety możliwe są konflikty. Stosowanie odpowiedniej funkcji skrótu zmniejsza ryzyko ich wystąpienia, ale nie niweluje go w całości. Domyślną funkcją skrótu jest funkcja o nazwie ms_hash_32_sdbm(). Wartość tego pola zmieniana jest automatycznie.

float Modifier

Modyfikator kontrolujący powiększenie pojemności tablicy zawierającej ciąg znaków. Zastosowanie modyfikatora, jak i również przyjmowane przez niego wartości, są uzależnione od aktualnie ustawionej funkcji zwiększającej pojemność tablicy, do której zmienna jest zawsze przekazywana. Ustawienie złej wartości może spowodować błędne obliczenia nowej pojemności w inkreatorze.

bool Wide

Informacja o tym, czy ciąg posiada znaki o typie wchar_t. Znaki o tym typie są znakami zapisanymi zawsze na tylu bajtach, ilu bajtowy jest typ wchar_t. W przypadku znaków o typie char, ilość bajtów składających się na znak zależy od użytego kodowania. Wartość tego pola ustawiana jest automatycznie i nie może być zmieniana samodzielnie.

bool Destroy

Informacja o tym, czy zmienna przechowująca strukturę ciągu znaków ma zostać zniszczona. Pole to wykorzystywane jest tylko i wyłącznie w funkcji ms_string_free(), odpowiedzialnej za zwalnianie przydzielonych zasobów przeznaczonych na ciąg znaków. Wartość ustawiana jest na TRUE tylko w funkcjach, zwracających wskaźnik do struktury ciągu. Samodzielna zmiana tej wartości może prowadzić do wycieków lub naruszenia ochrony pamięci.

bool Hashed

Informacja o tym, czy dla zawartości struktury utworzony został skrót. Do sprawdzenia czy skrót został utworzony, potrzeba osobnej zmiennej. Jest to konieczne, ponieważ wartość 0 również może być skrótem danych, zawartych w strukturze, więc każda wartość dla pola MS_STRING.Hash jest poprawna. Wartość tego pola zmieniana jest automatycznie podczas jakiejkolwiek zmiany w strukturze. Można jednak samodzielnie ustawić wartość na FALSE, aby wymusić ponowne utworzenie skrótu dla struktury.

MS_ARRAY* MBInfo

Tablica zawierająca szczegóły dotyczące każdego znaku w ciągu. Pole uzupełniane jest tylko w przypadku gdy ciąg posiada znaki wielobajtowe. W przeciwnym wypadku pole zawiera wartość NULL. Tablica ta wykorzystywana jest podczas podstawowych operacji na znakach, gdzie pobierany jest lub potrzebny indeks znaku lub cały zakres znaków do modyfikacji. Ilość elementów w tablicy jest różna od ilości znaków w ciągu, obliczanych za pomocą funkcji strlen(). Ilość elementów odpowiada rzeczywistej ilości znaków, wyświetlanych na ekranie, dzięki czemu w prosty sposób można się dostać do indeksu modyfikowanego znaku i jego rozmiaru w bajtach. Zarówno indeks jak i rozmiar obliczane są funkcją mblen(). Aby funkcja ta działała poprawnie, należy ustawić poprawną lokalizację w programie, wykorzystując funkcję setlocale().

size_t FuncIncrease(size_t capacity, float modifier)

Funkcja zwana inaczej inkreatorem, zwiększająca pojemność tablicy, używana podczas przydzielania pamięci dla jej nowych elementów. Dzięki temu polu można przypisać własną funkcję obliczającą nową ilość pamięci. Wszystkie wskaźniki wbudowanych inkreatorów znajdują się w stałej MSC_ArrayFunctions mając w nazwie przedrostek Inc. Funkcje te zawsze po obliczeniach zaokrąglają wynik w dół. Do wnętrza funkcji pod parametrem modifier przekazywana jest wartość pola MS_STRING.Modifier. Zmienna ta może być zarówno dodatnia jak i ujemna, jednak wynik końcowy teoretycznie nie może być mniejszy niż wprowadzony do funkcji w zmiennej capacity. W praktyce jednak, w przypadku gdy funkcja zwraca wynik o mniejszej wartości niż aktualna pojemność tablicy, nowa ustawiona zostaje jako capacity + 1.

Zestawienie wbudowanych funkcji inkreatora i ich wyniki przy takich samych parametrach:

Funkcja inkreatora Pojemność Mnożnik Wynik
IncAdd 3 4.5 7
IncMultiply 3 4.5 13
IncPower 3 4.5 140
Parametry:
  • capacity – Aktualna pojemność ciągu znaków.
  • modifier – Modyfikator pojemności.
Zwraca:

Nową pojemność ciągu znaków, przekazywaną do przydzielenia pamięci.
MS_MBINFO

Struktura przechowująca informacje o pojedynczym znaku w wielobajtowym ciągu znaków. Ciągi wielobajtowe mają to do siebie, że mogą reprezentować pojedynczy znak na kilku bajtach. Zatem każdy znak w ciągu może posiadać rzeczywistą długość zależną od użytego kodowania. Poprzez długość rzeczywistą ma się rozumieć ilość znaków, wyświetlanych na ekranie. Struktura została utworzona, aby przyspieszyć niektóre operacje, wykonywane na wielobajtowych ciągach znaków. Używana w strukturze MS_STRING. Aby informacje w strukturze były poprawne, należy wcześniej ustawić odpowiednią lokalizację, używając funkcji setlocale().

size_t Offset

Prawdziwy indeks, na którym leży znak w ciągu. Indeks ten jest sumą ilości bajtów wszystkich znaków, poprzedzających aktualny. Pole reprezentuje przesunięcie od którego wielobajtowy ma się rozpoczynać.

char Bytes

Ilość bajtów przypadająca na sprawdzany znak. Znaki w wielobajtowych ciągach w zależności od kodowania mogą być różnej długości. Względem powyższego stwierdzenia, to samo kodowanie potrafi zakodować znak n na 1 bajcie, zaś znak ń już 2 bajtach. To pole, wraz z polem MS_MBINFO.Offset, umożliwia obliczenie zakresu, który okupuje pojedynczy znak w ciągu. Wartość pola obliczana jest poprzez funkcję mblen().

5.2. Tworzenie i inicjalizacja

MS_STRING* ms_string_alloc_cs(const char* cstr, size_t capacity)

Tworzy nowy ciąg jednobajtowych znaków o typie char oraz rezerwuje początkowe miejsce na dane. W odróżnieniu od inicjalizacji, funkcja zwraca wskaźnik do utworzonego ciągu. W przypadku błędu podczas tworzenia, zwrócona zostaje wartość NULL. Funkcja jako jedna z nielicznych ustawia pole MS_STRING.Destroy na wartość TRUE. Przydzielone przez funkcję zasoby zawsze należy zwalniać, co umożliwia funkcja ms_string_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją strlen().

Parametry:
  • cstr – Początkowy ciąg jednobajtowych znaków.
  • capacity – Początkowa ilość rezerwowanego miejsca na znaki.
Zwraca:

Wskaźnik na utworzony ciąg lub wartość NULL w przypadku błędu.
MS_STRING* ms_string_alloc_mbs(const char* mbstr, size_t capacity)

Tworzy nowy ciąg znaków wielobajtowych o typie char oraz rezerwuje początkowe miejsce na dane. W odróżnieniu od inicjalizacji, funkcja zwraca wskaźnik do utworzonego ciągu. W przypadku błędu podczas tworzenia, zwrócona zostaje wartość NULL. Funkcja dodatkowo tworzy tablicę informacyjną dla znaków w ciągu dla pola MS_STRING.MBInfo. Znajdują się w niej informacje o położeniu i rozmiarze każdego znaku w ciągu. Funkcja jako jedna z nielicznych ustawia pole MS_STRING.Destroy na wartość TRUE. Przydzielone przez funkcję zasoby zawsze należy zwalniać, co umożliwia funkcja ms_string_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją strlen(). Wartość capacity dla tej funkcji nie oznacza tak jak w przypadku pozostałych funkcji tworzących ilość znaków, lecz ilość bajtów, które może zajmować ciąg znaków. Jest to spowodowane tym, że znaki tworzące mogą być zarówno 1 jak i 3 bajowe.

Parametry:
  • mbstr – Początkowy ciąg wielobajtowych znaków.
  • capacity – Początkowa ilość bajtów rezerwowanego miejsca na znaki.
Zwraca:

Wskaźnik na utworzony ciąg lub wartość NULL w przypadku błędu.
MS_STRING* ms_string_alloc_wcs(const wchar_t* wcstr, size_t capacity)

Tworzy nowy ciąg znaków o typie wchar_t oraz rezerwuje początkowe miejsce na dane. W odróżnieniu od inicjalizacji, funkcja ta zwraca wskaźnik do utworzonego ciągu. W przypadku błędu podczas tworzenia, zwracana jest wartość NULL. Funkcja jako jedna z nielicznych ustawia pole MS_STRING.Destroy na wartość TRUE. Przydzielone przez funkcję zasoby zawsze należy zwalniać, co umożliwia funkcja ms_string_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją wcslen().

Parametry:
  • wcstr – Początkowy ciąg znaków.
  • capacity – Początkowa ilość rezerwowanego miejsca na znaki.
Zwraca:

Wskaźnik na utworzony ciąg lub wartość NULL w przypadku błędu.
int ms_string_init_cs(MS_STRING* str, const char* cstr, size_t capacity)

Inicjalizuje istniejącą strukturę ciągu jednobajtowych znaków i rezerwuje początkowe miejsce na dane. Wszystkie funkcje tworzące ciąg jednobajtowych znaków odwołują się bezpośrednio do tej funkcji. W przypadku błędu zwracany jest jego kod, w przeciwnym razie wartość MSE_ERROR_CODES.MSEC_OK. Przydzielone przez funkcję zasoby zawsze należy zwalniać, co umożliwia funkcja ms_string_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją strlen().

Parametry:
  • str – Struktura ciągu znaków do uzupełnienia.
  • cstr – Początkowy ciąg jednobajtowych znaków.
  • capacity – Początkowa ilość rezerwowanego miejsca na znaki.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_init_mbs(MS_STRING* str, const char* mbstr, size_t capacity)

Inicjalizuje istniejącą strukturę ciągu znaków wielobajtowych i rezerwuje początkowe miejsce na dane. Wszystkie funkcje tworzące ciąg wielobajtowych znaków odwołują się bezpośrednio do tej funkcji. Funkcja dodatkowo tworzy tablicę informacyjną dla znaków w ciągu dla pola MS_STRING.MBInfo. Znajdują się w niej informacje o położeniu i rozmiarze każdego znaku w ciągu. W przypadku błędu zwracany jest jego kod, w przeciwnym razie wartość MSE_ERROR_CODES.MSEC_OK. Przydzielone przez funkcję zasoby zawsze należy zwalniać, co umożliwia funkcja ms_string_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją strlen(). Wartość capacity dla tej funkcji nie oznacza tak jak w przypadku pozostałych funkcji tworzących ilość znaków, lecz ilość bajtów, które może zajmować ciąg znaków. Jest to spowodowane tym, że znaki tworzące mogą być zarówno 1 jak i 3 bajowe.

Parametry:
  • str – Struktura ciągu znaków do uzupełnienia.
  • mbstr – Początkowy ciąg wielobajtowych znaków.
  • capacity – Początkowa ilość bajtów rezerwowanego miejsca na znaki.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_init_wcs(MS_STRING* str, const wchar_t* wcstr, size_t capacity)

Inicjalizuje istniejącą strukturę ciągu znaków o typie wchar_t i rezerwuje początkowe miejsce na dane. Wszystkie funkcje tworzące ciąg znaków o typ typie odwołują się bezpośrednio do tej funkcji. W przypadku błędu zwracany jest jego kod, w przeciwnym razie wartość MSE_ERROR_CODES.MSEC_OK. Przydzielone przez funkcję zasoby zawsze należy zwalniać, co umożliwia funkcja ms_string_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją wcslen().

Parametry:
  • str – Struktura ciągu znaków do uzupełnienia.
  • wcstr – Początkowy ciąg znaków.
  • capacity – Początkowa ilość rezerwowanego miejsca na znaki.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
MS_STRING ms_string_return_cs(const char *cstr, size_t capacity)

Tworzy nowy ciąg jednobajtowych znaków o typie char oraz rezerwuje początkowe miejsce na dane. Odmiana tej funkcji pozwala na ustawienie rozmiaru pojedynczego elementu. W przypadku błędu podczas tworzenia, każde pole unii MS_STRING.Data jest równe NULL. Utworzony w ten sposób ciąg znaków nadal wymaga zwolnienia przydzielonych zasobów poprzez wywołanie funkcji ms_array_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją strlen().

Parametry:
  • cstr – Początkowy ciąg jednobajtowych znaków.
  • capacity – Początkowa ilość rezerwowanego miejsca na znaki.
Zwraca:

Utworzony lokalny ciąg znaków.
MS_STRING ms_string_return_mbs(const char *mbstr, size_t capacity)

Tworzy nowy ciąg znaków wielobajtowych o typie char oraz rezerwuje początkowe miejsce na dane. Odmiana tej funkcji pozwala na ustawienie rozmiaru pojedynczego elementu. W przypadku błędu podczas tworzenia, każde pole unii MS_STRING.Data jest równe NULL. Funkcja dodatkowo tworzy tablicę informacyjną dla znaków w ciągu dla pola MS_STRING.MBInfo. Znajdują się w niej informacje o położeniu i rozmiarze każdego znaku w ciągu. Utworzony w ten sposób ciąg znaków nadal wymaga zwolnienia przydzielonych zasobów poprzez wywołanie funkcji ms_array_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją strlen(). Wartość capacity dla tej funkcji nie oznacza tak jak w przypadku pozostałych funkcji tworzących ilość znaków, lecz ilość bajtów, które może zajmować ciąg znaków. Jest to spowodowane tym, że znaki tworzące mogą być zarówno 1 jak i 3 bajowe.

Parametry:
  • mbstr – Początkowy ciąg wielobajtowych znaków.
  • capacity – Początkowa ilość bajtów rezerwowanego miejsca na znaki.
Zwraca:

Utworzony lokalny ciąg znaków.
MS_STRING ms_string_return_wcs(const wchar_t *wcstr, size_t capacity)

Tworzy nowy ciąg znaków o typie wchar_t oraz rezerwuje początkowe miejsce na dane. Odmiana tej funkcji pozwala na ustawienie rozmiaru pojedynczego elementu. W przypadku błędu podczas tworzenia, każde pole unii MS_STRING.Data jest równe NULL. Utworzony w ten sposób ciąg znaków nadal wymaga zwolnienia przydzielonych zasobów poprzez wywołanie funkcji ms_array_free(). Podanie wartości 0 lub mniejszej niż długość podanego ciągu znaków w miejsce parametru capacity powoduje zmianę tej wartości przez funkcję na długość ciągu, obliczonego funkcją wcslen().

Parametry:
  • wcstr – Początkowy ciąg znaków.
  • capacity – Początkowa ilość rezerwowanego miejsca na znaki.
Zwraca:

Utworzony lokalny ciąg znaków.

5.3. Zmiana pojemności

int ms_string_realloc(MS_STRING* str, size_t capacity)

Zmniejsza lub zwiększa pojemność ciągu znaków.

Funkcja posiada dwa wbudowane tryby zwiększania pojemności - automatyczny i ręczny. Tryb automatyczny można uruchomić, podając pod zmienną capacity wartość 0. Obliczaniem pojemności w takim wypadku zajmuje się funkcja inkreatora podpięta pod przekazaną tablicę do pola MS_STRING.FuncIncrease. Gdy inkreator nie jest podpięty, zwracany jest błąd, gdyż funkcja nie wie ile ma przydzielić pamięci. W przypadku zwrócenia przez inkreator pojemności mniejszej niż aktualna, wartość ta jest odrzucana i jako nowa przyjmowana jest suma capacity + 1. Tryb ręczny uruchamiany jest w przypadku wpisania wartości innej niż 0 w parametrze capacity. W tym trybie pojemność może być zarówno zwiększana jak i zmniejszana. Próba przydziału pojemności mniejszej niż ilość znaków zapisanych w ciągu skutkuje błędem i natychmiastowym zakończeniem działania funkcji. W przypadku ciągu znaków wielobajtowych o typie char, parametr capacity oznacza ilość bajtów a nie ilość znaków, jak to ma miejsce w przypadku innych ciągów.

Parametry:
  • str – Wskaźnik na strukturę ciągu.
  • capacity – Nowa pojemność ciągu lub 0 w przypadku automatu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_realloc_min(MS_STRING* str, size_t min)

Zwiększa pojemność ciągu do co najmniej podanej wartości.

Zwiększa pojemność ciągu znaków do najbliższej wartości następującej po wartości podanej w parametrze min. Podanie wartości mniejszej niż aktualna pojemność nie kończy się błędem, ale również nie zmienia pojemności całego ciągu, ponieważ minimum zostało już osiągnięte. Funkcja wywołuje inkreatora dopóty, dopóki wartość przez niego zwracana nie będzie większa lub równa wartości zmiennej min, przekazanej w parametrze. W przypadku gdy pole MS_STRING.FuncIncrease będzie równe wartości NULL, jako nowa pojemność przyjęta zostanie wartość minimalna. Funkcja przydaje się szczególnie w trakcie wstawiania wielu znaków, gdzie za jednym razem przydzielana jest odpowiednia ilość pamięci, która pozwoli zmieścić wszystkie znaki w ciągu i w miarę możliwości pozostawić miejsce na nowe.

Parametry:
  • str – Wskaźnik na strukturę ciągu.
  • min – Minimalna wartość do której zwiększona zostanie pojemność ciągu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:

5.4. Dodawanie elementów

int ms_string_insert_cs(MS_STRING* str, size_t index, const char *cstr, size_t count)

Wstawia tekst o znakach jednobajtowych do podanego ciągu w wybrane miejsce.

Funkcja pozwala na wstawienie podanego tekstu do przekazanego w parametrze ciągu znaków. Gdy sposób zapisu dwóch tekstów się różni, wstawiany tekst konwertowany jest automatycznie do sposobu zapisu tekstu uniwersalnego. Pojemność ciągu zwiększana jest automatycznie w przypadku gdy brakuje miejsca dla wstawianych danych. Podanie indeksu różnego od długości ciągu powoduje przesunięcie elementów następujących po indeksie dokładnie o ilość znaków podawanych w parametrze count lub o całą długość wstawianego tekstu.

Można ograniczyć ilość wstawianych znaków, podając ją w parametrze count. Gdy do parametru przekazana zostanie wartość 0, funkcja wstawia do ciągu cały podany tekst.

Parametry:
  • str – Wskaźnik na uniwersalną strukturę tekstu.
  • index – Indeks od którego dane będą wstawiane.
  • cstr – Standardowy teskt o znakach jednobajtowych.
  • count – Ilość znaków do wstawienia z podanego tekstu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_insert_mbs(MS_STRING* str, size_t index, const char *mbstr, size_t bytes)

Wstawia tekst o znakach wielobajtowych do podanego ciągu w wybrane miejsce.

Funkcja pozwala na wstawienie podanego tekstu do przekazanego w parametrze ciągu znaków. Gdy sposób zapisu dwóch tekstów się różni, wstawiany tekst konwertowany jest automatycznie do sposobu zapisu tekstu uniwersalnego. Pojemność ciągu zwiększana jest automatycznie w przypadku gdy brakuje miejsca dla wstawianych danych. Podanie indeksu różnego od długości ciągu powoduje przesunięcie elementów następujących po indeksie dokładnie o ilość bajtów podawanych w parametrze bytes lub o cały rozmiar wstawianego tekstu.

Można ograniczyć ilość wstawianych bajtów, podając ją w parametrze bytes. Gdy do parametru przekazana zostanie wartość 0, funkcja wstawia do ciągu cały podany tekst.

Parametry:
  • str – Wskaźnik na uniwersalną strukturę tekstu.
  • index – Indeks od którego dane będą wstawiane.
  • mbstr – Standardowy teskt o znakach wielobajtowych.
  • bytes – Ilość bajtów do wstawienia z podanego tekstu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_insert_wcs(MS_STRING* str, size_t index, const wchar_t *wcstr, size_t count)

Wstawia tekst o znakach unicode do podanego ciągu w wybrane miejsce.

Funkcja pozwala na wstawienie podanego tekstu do przekazanego w parametrze ciągu znaków. Gdy sposób zapisu dwóch tekstów się różni, wstawiany tekst konwertowany jest automatycznie do sposobu zapisu tekstu uniwersalnego. Pojemność ciągu zwiększana jest automatycznie w przypadku gdy brakuje miejsca dla wstawianych danych. Podanie indeksu różnego od długości ciągu powoduje przesunięcie elementów następujących po indeksie dokładnie o ilość znaków podawanych w parametrze count lub o całą długość wstawianego tekstu.

Można ograniczyć ilość wstawianych znaków, podając ją w parametrze count. Gdy do parametru przekazana zostanie wartość 0, funkcja wstawia do ciągu cały podany tekst.

Parametry:
  • str – Wskaźnik na uniwersalną strukturę tekstu.
  • index – Indeks od którego dane będą wstawiane.
  • wcstr – Standardowy teskt o znakach unicode.
  • count – Ilość znaków do wstawienia z podanego tekstu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:

5.5. Czyszczenie danych

void ms_string_clear(MS_STRING* str)

Czyści ciąg usuwając wszystkie znaki.

Funkcja nie zwalnia pamięci po elementach i nie zmniejsza aktualnej pojemności tablicy dla ciągu. Dzięki temu wprowadzanie kolejnych znaków nie uruchamia ponownie funkcji zwiększającej pamięć dla zmiennej. Pojemność ciągu znaków zawsze można zmniejszyć samodzielnie, wywołując funkcję ms_string_realloc().

Przykład użycia funkcji:

MS_STRING str = ms_string_return_cs( "Local string", 0 );

printf( "Chars: %" PFSIZET " >> Capacity: %" PFSIZET "\n",
    str.Length, str.Capacity );
ms_string_clear( &str );
printf( "Chars: %" PFSIZET " >> Capacity: %" PFSIZET "\n",
    str.Length, str.Capacity );

ms_string_free( &str );

Chars: 12 >> Capacity: 13
Chars: 0 >> Capacity: 13
Parametry:
  • aptr – Wskaźnik na ciąg znaków.
void ms_string_free(MS_STRING* str)

Zwalnia pamięć przydzieloną przez funkcję tworzącą ciąg znaków.

Każdy blok kodu w którym wystąpiło wywołanie konstruktora ciągu znaków, niezależnie od tego czy struktura jest lokalna czy nie, powinien uruchamiać funkcję czyszczącą pamięć przydzieloną przez konstruktor. Pominięcie tego kroku w danym bloku lub w całym programie przed jego zakończeniem spowoduje wyciek pamięci. Informacje dotyczące wykrywania wycieków pamięci w programie znajdują się w rozdziale zatytułowanym “Wycieki pamięci”.

Przykład użycia funkcji:

MS_STRING  str1 = ms_string_return_wcs( L"Żółta gęś", 0 );
MS_STRING *str2 = ms_string_alloc_mbs( "Zielona paproć", 0 );

ms_string_free( &str1 );
ms_string_free( str2 );

str2 = NULL;
Parametry:
  • aptr – Wskaźnik na ciąg znaków.

5.6. Obliczenia i informacje

size_t ms_string_length_mbs(const char* mbstr, size_t bytes)

Oblicza ilość znaków w ciągu wielobajtowym.

Ciąg wielobajtowy typu char może posiadać znaki o różnych rozmiarach, dlatego funkcja strlen() nie jest wystarczająca do sprawdzenia ich ilości. Do sprawdzenia ilości znaków wewnątrz funkcji używana jest funkcja mblen(), wywoływana dla każdego znaku w ciągu.

Ilość sprawdzanych znaków w ciągu można ograniczyć, podając rozmiar do drugiego parametru. W przypadku podania błędnego rozmiaru, funkcja zwróci wartość 0. Podanie wartości 0 w ostatnim parametrze jest równoznaczne z podaniem długości obliczonej funkcją strlen(). Gdy ciąg znaków zakończony jest znakiem \0 oraz w parametrze bytes podana będzie wartość większa niż ilość bajtów ciągu, obliczenia zostaną przerwane zaraz po napotkaniu znaku \0.

Przykład użycia funkcji:

int retval;
MS_STRING str;

size_t len1, len2, len3, len4,
       byt1, byt2, byt3, byt4;

/* locale must be set */
setlocale( LC_ALL, "pl_PL.utf8" );

if( (retval = ms_string_init_mbs(&str, "Zażółć gęślą jaźń", 0)) )
    return retval;

len1 = ms_string_length_mbs( str.Data.Char, 0 );
len2 = ms_string_length_mbs( "Żółte źdźbła trawy na koszyku wiklinowym.", 0 );
len3 = ms_string_length_mbs( "Jámbor célú, öv ügyű ex-qwan ki dó-s főz.", 0 );

/* limit - only 26 bytes */
len4 = ms_string_length_mbs( "Jámbor célú, öv ügyű ex-qwan ki dó-s főz.", 26 );

byt1 = strlen( str.Data.Char );
byt2 = strlen( "Żółte źdźbła trawy na koszyku wiklinowym." );
byt3 = strlen( "Jámbor célú, öv ügyű ex-qwan ki dó-s főz." );
byt4 = strlen( "Jámbor célú, öv ügyű" );

printf( "POL/1: %" PFSIZET " chars and %" PFSIZET " bytes.\n", len1, byt1 );
printf( "POL/2: %" PFSIZET " chars and %" PFSIZET " bytes.\n", len2, byt2 );
printf( "HUN/3: %" PFSIZET " chars and %" PFSIZET " bytes.\n", len3, byt3 );
printf( "HUN/4: %" PFSIZET " chars and %" PFSIZET " bytes.\n", len4, byt4 );

ms_string_free( &str );

POL/1: 17 chars and 26 bytes.
POL/2: 41 chars and 47 bytes.
HUN/3: 41 chars and 49 bytes.
HUN/4: 20 chars and 26 bytes.
Parametry:
  • mbstr – Wielobajtowy ciąg znaków.
  • bytes – Ilość bajtów do sprawdzenia.
Zwraca:

Ilość znaków w ciągu.
size_t ms_string_length_wcstombs(const wchar_t* wstr, size_t count)

Oblicza ilość bajtów zajmowanych przez ciąg po konwersji na mbs.

Ciąg wielobajtowy typu char po konwersji może zajmować więcej niż sam ciąg złożony ze znaków wchar_t. Dlatego funkcja wcslen() nie jest wystarczająca przy przewidywaniu rozmiaru ciągu po konwersji. Podczas obliczania długości ciągu, funkcja konwertuje znaki używając funkcji wctomb(), która zwraca rozmiar konwertowanego znaków w bajtach.

Długość ciągu można ograniczyć poprzez podanie ilości konwertowanych znaków w drugim parametrze. Podanie wartości 0 jest równoznaczne z podaniem długości całego ciągu, obliczonej funkcją wcslen(). Gdy ciąg znaków zakończony jest znakiem \0 oraz w parametrze count podana będzie wartość większa niż ilość znaków w ciągu, obliczenia zostaną przerwane zaraz po napotkaniu znaku \0.

Przykład użycia funkcji:

int retval;
MS_STRING str;

size_t len1, len2, len3, len4,
       byt1, byt2, byt3, byt4;

/* locale must be set */
setlocale( LC_ALL, "pl_PL.utf8" );

if( (retval = ms_string_init_wcs(&str, L"Zażółć gęślą jaźń", 0)) )
    return retval;

len1 = ms_string_length_wcstombs( str.Data.Wide, 0 );
len2 = ms_string_length_wcstombs( L"Żółte źdźbła trawy na koszyku wiklinowym.", 0 );
len3 = ms_string_length_wcstombs( L"Эх, чужак, общий съём цен шляп.", 0 );

/* limit - only 16 characters */
len4 = ms_string_length_wcstombs( L"Эх, чужак, общий съём цен шляп.", 16 );

byt1 = wcslen( str.Data.Wide );
byt2 = wcslen( L"Żółte źdźbła trawy na koszyku wiklinowym." );
byt3 = wcslen( L"Эх, чужак, общий съём цен шляп." );
byt4 = wcslen( L"Эх, чужак, общий" );

printf( "POL/1: %" PFSIZET " bytes and %" PFSIZET " chars.\n", len1, byt1 );
printf( "POL/2: %" PFSIZET " bytes and %" PFSIZET " chars.\n", len2, byt2 );
printf( "RUS/3: %" PFSIZET " bytes and %" PFSIZET " chars.\n", len3, byt3 );
printf( "RUS/4: %" PFSIZET " bytes and %" PFSIZET " chars.\n", len4, byt4 );

ms_string_free( &str );

POL/1: 26 bytes and 17 chars.
POL/2: 47 bytes and 41 chars.
RUS/3: 54 bytes and 31 chars.
RUS/4: 28 bytes and 16 chars.
Parametry:
  • wstr – Ciąg znaków unicode.
  • count – Ilość znaków do sprawdzenia.
Zwraca:

Ilość bajtów zajmowanych przez ciąg po konwersji.
int ms_string_info_mbs(const char* mbs, size_t bytes, MS_ARRAY* info)

Pobiera szczegóły dotyczące znaków w ciągu.

Funkcja sprawdza każdy znak w ciągu i zapisuje do tablicy informacje o jego położeniu i rozmiarze. Informacje te tworzone są automatycznie podczas tworzenia ciągu wielobajtowych znaków w polu o nazwie MS_STRING.MBInfo. Tablica przekazywana do funkcji musi być wcześniej utworzona jednym z konstruktorów. Rozmiar tablicy jest jednocześnie ilością znaków w ciągu. Wartość ta jest więc równoznaczna z wartością zwracaną przez funkcję ms_string_length_mbs().

Istnieje możliwość ograniczenia ilości sprawdzanych znaków, poprzez podanie odpowiedniego rozmiaru przetwarzanego ciągu w polu bytes. W przypadku podania wartości dla której ciąg jest błędny, tablica będzie uzupełniona do ostatniego poprawnego znaku występującego w ciągu ograniczonego podaną wartością. Gdy ciąg znaków zakończony jest znakiem \0 oraz w parametrze bytes podana będzie wartość większa niż ilość bajtów ciągu, obliczenia zostaną przerwane zaraz po napotkaniu znaku \0.

Przykład użycia funkcji:

int  retval;
char chr[MB_LEN_MAX + 1];
char str[] = "Эх, чужак.";

MS_ARRAY  array;

setlocale( LC_ALL, "pl_PL.utf8" );

/* initialize array */
array = ms_array_return_local( sizeof(MS_MBINFO), MSD_ARRAY_DEFAULT_SIZE );

/* get info about string */
if( (retval = ms_string_info_mbs(str, 0, &array)) )
    return retval;

/* display info */
for( retval = 0; retval < array.Length; ++retval )
{
    MS_MBINFO info = ms_array_getl( array, MS_MBINFO, retval );

    /* prepare data to display */
    memcpy( chr, &str[info.Offset], info.Bytes );
    chr[info.Bytes] = '\0';

    printf( "Size: %d > Char: %s > Shift: 0x%02" PFSIZETUH "\n",
        info.Bytes, chr, info.Offset );
}

ms_array_free( &array );

Size: 2 > Char: Э > Shift: 0x00
Size: 2 > Char: х > Shift: 0x02
Size: 1 > Char: , > Shift: 0x04
Size: 1 > Char:   > Shift: 0x05
Size: 2 > Char: ч > Shift: 0x06
Size: 2 > Char: у > Shift: 0x08
Size: 2 > Char: ж > Shift: 0x0A
Size: 2 > Char: а > Shift: 0x0C
Size: 2 > Char: к > Shift: 0x0E
Size: 1 > Char: . > Shift: 0x10
Parametry:
  • mbs – Ciąg znaków wielobajtowych.
  • bytes – Ilość bajtów przetwarzanych w ciągu.
  • info – Tablica wyjściowa, do której zapisywane będą informacje.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_info_wcstombs(const wchar_t* wstr, size_t count, MS_ARRAY* info)

Pobiera szczegóły dotyczące znaków w ciągu po konwersji na mbs.

Funkcja kowertuje każdy znak i zapisuje jego położenie i rozmiar po konwersji bezpośrednio do tablicy. Tablica przekazywana do funkcji musi być wcześniej utworzona jednym z konstruktorów. Aby uzyskać ilość bajtów dla całego ciągu znaków należy do pozycji ostatniego elementu dodać jego rozmiar. Suma ta jest równoznaczna z wartością zwracaną przez funkcję ms_string_length_wcstombs().

Można ograniczyć ciąg znaków, podając ich ilość w parametrze count. Wartość 0 traktowana jest jako ilość znaków w ciągu. Gdy ciąg znaków zakończony jest znakiem \0 oraz w parametrze count podana będzie wartość większa niż ilość znaków w ciągu, obliczenia zostaną przerwane zaraz po napotkaniu znaku \0.

Przykład użycia funkcji:

int     retval;
char    chr[MB_LEN_MAX + 1];
wchar_t str[] = L"Jámbor célú.";

MS_ARRAY  array;

setlocale( LC_ALL, "pl_PL.utf8" );

/* initialize array */
array = ms_array_return_local( sizeof(MS_MBINFO), MSD_ARRAY_DEFAULT_SIZE );

/* get info about string */
if( (retval = ms_string_info_wcstombs(str, 0, &array)) )
    return retval;

/* display info */
for( retval = 0; retval < array.Length; ++retval )
{
    MS_MBINFO info = ms_array_getl( array, MS_MBINFO, retval );

    printf( "Size: %d > Char: %lc > Shift: 0x%02" PFSIZETUH "\n",
        info.Bytes, str[retval], info.Offset );
}

ms_array_free( &array );

Size: 1 > Char: J > Shift: 0x00
Size: 2 > Char: á > Shift: 0x01
Size: 1 > Char: m > Shift: 0x03
Size: 1 > Char: b > Shift: 0x04
Size: 1 > Char: o > Shift: 0x05
Size: 1 > Char: r > Shift: 0x06
Size: 1 > Char:   > Shift: 0x07
Size: 1 > Char: c > Shift: 0x08
Size: 2 > Char: é > Shift: 0x09
Size: 1 > Char: l > Shift: 0x0B
Size: 2 > Char: ú > Shift: 0x0C
Size: 1 > Char: . > Shift: 0x0E
Parametry:
  • wstr – Ciąg znaków unicode.
  • count – Ilość znaków przetwarzanych w ciągu.
  • info – Tablica wyjściowa, do której zapisywane będą informacje.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:

5.7. Makra

int ms_string_push_cs(MS_STRING* str, const char *cstr, size_t count)

Wstawia tekst o jednobajtowych znakach na sam koniec podanego ciągu.

Makro to jest skrótem do funkcji ms_string_insert_cs(). Różnica w wywołaniu sprowadza się do braku parametru powiązanego z pozycją wstawianego tekstu. Parametr ten uzupełniany jest wartością pobieraną z pola MS_STRING.Length.

Parametry:
  • str – Wskaźnik na uniwersalną strukturę tekstu.
  • cstr – Standardowy teskt o jednobajtowych znakach.
  • count – Ilość znaków do wstawienia z podanego tekstu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_push_mbs(MS_STRING* str, const char *mbstr, size_t bytes)

Wstawia tekst o wielobajtowych znakach na sam koniec podanego ciągu.

Makro to jest skrótem do funkcji ms_string_insert_mbs(). Różnica w wywołaniu sprowadza się do braku parametru powiązanego z pozycją wstawianego tekstu. Parametr ten uzupełniany jest wartością pobieraną z pola MS_STRING.Length.

Parametry:
  • str – Wskaźnik na uniwersalną strukturę tekstu.
  • mbstr – Standardowy teskt o wielobajtowych znakach.
  • bytes – Ilość bajtów do wstawienia z podanego tekstu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy:
int ms_string_push_wcs(MS_STRING* str, const wchar_t *wcstr, size_t count)

Wstawia tekst o znakach unikodu na sam koniec podanego ciągu.

Makro to jest skrótem do funkcji ms_string_insert_wcs(). Różnica w wywołaniu sprowadza się do braku parametru powiązanego z pozycją wstawianego tekstu. Parametr ten uzupełniany jest wartością pobieraną z pola MS_STRING.Length.

Parametry:
  • str – Wskaźnik na uniwersalną strukturę tekstu.
  • wcstr – Standardowy teskt o znakach unicode.
  • count – Ilość znaków do wstawienia z podanego tekstu.
Zwraca:

Kod błędu lub wartość MSE_ERROR_CODES.MSEC_OK.
Błędy: