smartjoin 1.0.0
An enhanced string join library with advanced features for Python developers.
Requires Python: >=3.6


# **SmartJoin**

**SmartJoin**, created by **Khalid Sulaiman Al-Mulaify**, is a Python library that reimagines the traditional `join` function by adding advanced features for more flexible and dynamic string manipulation. Whether you're building dynamic outputs, enhancing readability, or working with complex lists, SmartJoin provides the tools to handle it effortlessly.



## **Features**

### 1. **Conditional Joining**
Join only elements that satisfy a given condition, such as non-empty strings or strings matching a specific pattern.

#### Example:
```python
from smartjoin import SmartJoin

result = SmartJoin.join(
    ["apple", "", "banana", "cherry"],
    separator=", ",
    condition=lambda s: len(s) > 0
)
print(result)
# Output: "apple, banana, cherry"
```

---

### 2. **Customizable Padding**
Add padding to each element, such as enclosing each string in quotes or wrapping it with special characters.

#### Example:
```python
result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separator=", ",
    pad="'"
)
print(result)
# Output: "'apple', 'banana', 'cherry'"
```

---

### 3. **Indexed Join**
Include the index of each element in the joined string for tracking or formatting purposes.
#### Example:
```python
result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separator=" | ",
    with_index=True
)
print(result)
# Output: "0: apple | 1: banana | 2: cherry"
```

---

### 4. **Mixed Separators**
Use different separators between elements based on position or other criteria.

#### Example:
```python
result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separators=[" - ", " ~ "]
)
print(result)
# Output: "apple - banana ~ cherry"
```

---

### 5. **Transform Function**
Apply a transformation to each element before joining, such as uppercasing, reversing, or formatting strings dynamically.

#### Example:
```python
result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separator=", ",
    transform=str.upper
)
print(result)
# Output: "APPLE, BANANA, CHERRY"
```

---

### 6. **Recursive Joining**
Automatically flatten nested lists and join all elements into a single string.

#### Example:
```python
result = SmartJoin.join(
    ["apple", ["banana", "cherry"], "date"],
    separator=" - "
)
print(result)
# Output: "apple - banana - cherry - date"
```

---

### 7. **Localized Join**
Add a natural language conjunction like "and" or "or" before the last element for better readability. The default conjunction is `"and"`, but you can customize it.

#### Example 1: Using "and" (default)
```python
result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separator=", ",
    localized=True
)
print(result)
# Output: "apple, banana, and cherry"
```

#### Example 2: Using "or"
```python
result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separator=", ",
    localized=True,
    localized_word="or"
)
print(result)
# Output: "apple, banana, or cherry"
```

---

### 8. **Dynamic Separator**
Define a custom separator function to decide the separator based on the element's index or value.

#### Example:
```python
result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separator_function=lambda i, _: " - " if i % 2 == 0 else " ~ "
)
print(result)
# Output: "apple - banana ~ cherry"
```

---

## **Installation**

Install SmartJoin via pip:

```bash
pip install smartjoin
```

---

## **Usage**

Import the `SmartJoin` class and use its `join` method with the desired arguments. Hereâ€™s a basic example:

```python
from smartjoin import SmartJoin

result = SmartJoin.join(
    ["apple", "banana", "cherry"],
    separator=", ",
    localized=True
)
print(result)
# Output: "apple, banana, and cherry"
```

---

## **License**

This library is provided "as is", without warranty of any kind, express or implied.

---

## **Support**

For questions, feedback, or support, feel free to reach out to **Khalid Sulaiman Al-Mulaify** via:

- Email: [khalidmfy@gmail.com](mailto:khalidmfy@gmail.com)
- X (Twitter): [@Python__Task](https://x.com/Python__Task)

---