# Класс `StringExtension`

Этот класс предназначен для расширения базовых возможностей работы со строками на Python. Основной целью является
поддержка удобной обработки текста на русском языке и предоставление функций для нормирования и трансформирования строк.
Методы класса реализуют проверку на пустоту, работу с русскими символами, транслитерацию, замену фрагментов текста и
работу с кодировкой.

## Основная информация

- **Имя файла**: anb_python_components\extensions\string_extension.py
- **Автор**: Александр Бабаев
- **Версия**: 1.0.0
- **Дата начала поддержки**: с версии 1.0

## Атрибуты и методы класса

### Метод `is_none_or_empty`

Проверяет, является ли строка пустой или None. Это удобно для быстрой предварительной обработки перед дальнейшими
действиями.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

result = StringExtension.is_none_or_empty("")

print(result)  # True
```

### Метод `is_none_or_whitespace`

Проверяет, содержит ли строка только пробельные символы или пустые места. Полезно для очистки вводимых значений.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

result = StringExtension.is_none_or_whitespace("\t\n ")

print(result)  # True
```

### Метод `is_russian_letter`

Проверяет, является ли символ русской буквой. Удобно для фильтраций и анализа текста на предмет наличия кириллицы.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

char = 'П'
result = StringExtension.is_russian_letter(char)
print(result)  # True
```

### Метод `get_russian_letter_transliteration`

Возвращает транслитерированное представление русской буквы. Это полезно для интеграций с иностранными сервисами и API,
которые требуют текст в латинском представлении.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

letter = 'Ч'
result = StringExtension.get_russian_letter_transliteration(letter)
print(result)  # Ch
```

### Метод `convert_to_latin`

Переводит весь текст в транслитерационное представление. Подходит для ситуаций, когда нужно сохранить содержание текста,
но представить его в другом алфавите.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

text = "Привет мир!"
result = StringExtension.convert_to_latin(text)
print(result)  # Privet mir!
```

### Метод `compare`

Позволяет сравнивать две строки, учитывая возможность игнорирования регистра символов. Очень полезно для проверок
условий в программах, обрабатывающих текстовую информацию.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

result = StringExtension.compare("привет", "Привет", ignore_case=True)
print(result)  # 0
```

### Метод `get_short_text`

Обрезает длинную строку до определённой длины, оставляя указанный символ окончания (например, многоточие). Идеально
подходит для вывода коротких заголовков или аннотаций.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

text = "Это очень длинный текст..."
shortened = StringExtension.get_short_text(text, max_length=10,
                                           end_symbols="...")
print(shortened)  # Это оче...
```

### Метод `to_utf8`

Преобразует строку в кодировку UTF-8. Этот метод необходим, если работа ведётся с другими кодировками, отличающимися от
стандартной (например, Windows-1251).

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

subject = "ТЕКСТ"
utf8_encoded = StringExtension.to_utf8(subject, encoding='windows-1251')
print(utf8_encoded)  # ТЕКСТ
```

### Метод `from_utf8`

Преобразует строку обратно из UTF-8 в требуемую кодировку. Необходимость метода возникает при обработке данных,
полученных из разных источников.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

subject = "ТЕКСТ"
decoded = StringExtension.from_utf8(subject, to_encoding='windows-1251')
print(decoded)  # ТЕКСТ
```

### Метод `replace`

Производит замену указанного шаблона на новую строку внутри исходного текста. Поддерживает использование регулярных
выражений для сложных случаев поиска.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

source = "Меняю слово"
new_source = StringExtension.replace(source, "слово", "текст")
print(new_source)  # Меняю текст
```

### Метод `replace_all`

Производит серию последовательных замен по переданному словарю соответствий. Эффективен для массовой модификации текста.

Пример использования:

```python
from anb_python_components.extensions.string_extension import StringExtension

search_replace = {"слово": "текст", "-": "#"}
source = "Меняю слово-слово"
new_source = StringExtension.replace_all(search_replace, source)
print(new_source)  # Меняю текст#текст
```

## Заключение

Методы класса обеспечивают широкие возможности для обработки и подготовки текстовых данных на русском языке. Эти
инструменты полезны для любых проектов, связанных с обработкой текстовой информации на Python, будь то веб-приложения,
скрипты автоматизации или обработка файлов.

[На главную](../../index.md)