# Trimming and Translating

> StringZilla for Python

### Trimming

- `strip(chars=whitespace)` — remove leading and trailing bytes that are in `chars`.
- `lstrip(chars=whitespace)` — remove only leading bytes.
- `rstrip(chars=whitespace)` — remove only trailing bytes.

With no argument, the default character set is ASCII whitespace.
Pass a byteset to trim an arbitrary set of bytes.

```python
import stringzilla as sz

assert sz.String("  hi  ").strip() == "hi"
assert sz.String("xxhi").lstrip("x") == "hi"
assert sz.String("hi!!").rstrip("!") == "hi"
```

### Translating

`translate(table, inplace=False, start=0, end=len)` applies a byte-to-byte mapping in a single pass.
`table` is either a 256-byte string/bytes lookup table or a `dict` mapping bytes to bytes, spelled as characters below U+0100.
A `str` input is translated as its UTF-8 bytes and decoded back, so a table that breaks the encoding raises `UnicodeDecodeError`.
With `inplace=True` the buffer is rewritten in place and `None` is returned; otherwise a new `bytes`/`str` is returned.
A non-256-byte table raises `ValueError`; a non-string, non-dict table raises `TypeError`.

```python
import stringzilla as sz

assert sz.String("abc").translate({"a": "A"}) == b"Abc"

table = bytes(range(256)).translate(bytes.maketrans(b"abc", b"ABC"))
assert sz.String("cabbage").translate(table) == b"CABBAge"
```

`Strings.translate(table)` takes the same tables and maps every string of a collection in one call, returning a new `Strings`, as [Escaping and Normalizing Collections](https://www.unum.cloud/docs/stringzilla/python/sorting-and-sets.md#escaping-and-normalizing-collections) describes.

### Decoding

`decode(encoding='utf-8', errors='strict')` decodes the bytes to a Python `str`, mirroring `bytes.decode`.

```python
import stringzilla as sz

assert sz.String("abc").decode() == "abc"
```

`import stringzilla`

## lstrip

Remove leading characters from a string.

```python
def lstrip(
    text: _StringLike,
    chars: _StringLike | None = None,
    *,
    capabilities: Capability | None = None,
) -> String
```

Returns:
String: A new string with leading characters removed.

- `text`: The string object.
- `chars`: Characters to remove, defaulting to whitespace.
- `capabilities`: Capabilities to run, defaulting to the CPU's enabled ones.

Examples: ```
>>> sz.String('  hi').lstrip() == 'hi'
True
```

## rstrip

Remove trailing characters from a string.

```python
def rstrip(
    text: _StringLike,
    chars: _StringLike | None = None,
    *,
    capabilities: Capability | None = None,
) -> String
```

Returns:
String: A new string with trailing characters removed.

- `text`: The string object.
- `chars`: Characters to remove, defaulting to whitespace.
- `capabilities`: Capabilities to run, defaulting to the CPU's enabled ones.

Examples: ```
>>> sz.String('hi  ').rstrip() == 'hi'
True
```

## strip

Remove leading and trailing characters from a string.

```python
def strip(
    text: _StringLike,
    chars: _StringLike | None = None,
    *,
    capabilities: Capability | None = None,
) -> String
```

Returns:
String: A new string with leading and trailing characters removed.

- `text`: The string object.
- `chars`: Characters to remove, defaulting to whitespace.
- `capabilities`: Capabilities to run, defaulting to the CPU's enabled ones.

Examples: ```
>>> sz.String('  hi  ').strip() == 'hi'
True
```

## decode

Decode the bytes into a Unicode string with a given encoding.

```python
def decode(
    text: _StringLike,
    encoding: str = 'utf-8',
    errors: str = 'strict',
) -> str
```

Returns:
str: The decoded Unicode string.
Raises:
UnicodeDecodeError: If decoding fails.

- `text`: The string object.
- `encoding`: The encoding to use, defaulting to 'utf-8'.
- `errors`: Error handling scheme, defaulting to 'strict'.

Examples: ```
>>> sz.String('abc').decode() == 'abc'
True
```

## write_to

Write the string to a file.

```python
def write_to(text: _StringLike, filename: str) -> None
```

Returns:
None.

- `text`: The string object.
- `filename`: The file path to write to.

Examples: ```
>>> import os, tempfile
>>> path = os.path.join(tempfile.gettempdir(), 'sz_demo.bin')
>>> sz.String('payload').write_to(path)
```

## offset_within

Return the raw byte offset of this StringZilla string within a larger StringZilla string.

```python
def offset_within(text: _StringLike, larger: String) -> int
```

Returns:
int: The byte offset where 'self' is found within 'larger', or -1 if not found.

- `text`: The substring.
- `larger`: The larger string to search within.

Examples: ```
>>> big = sz.String('hello world')
>>> big[6:].offset_within(big)
6
```

## translate

Perform transformation of a string using a look-up table.

```python
def translate(
    text: _StringLike,
    table: str | bytes | dict[str, str],
    inplace: bool = False,
    start: int = 0,
    end: int | None = None,
    *,
    capabilities: Capability | None = None,
) -> None | str | bytes
```

Returns:
Union[None, str, bytes]: If inplace is False, a translated copy of the [start, end) slice is
returned, otherwise None.
Raises:
ValueError: If the table is not 256 bytes long, or a dict names a character above U+00FF.
UnicodeDecodeError: If a str input translates into malformed UTF-8.
TypeError: If the table is not a string or dictionary.

- `text`: The string object.
- `table`: A 256-byte string, or a dict mapping characters below U+0100 to such.
- `inplace`: If True, the string is modified in place, defaulting to False.
- `start`: The starting index for translation, defaulting to 0.
- `end`: The ending index for translation, defaulting to the string length.
- `capabilities`: Capabilities to run, defaulting to the CPU's enabled ones.

Examples: ```
>>> sz.String('abc').translate({'a': 'A'}) == b'Abc'
True
```