0
# String Manipulation
1

2
Enhanced string processing capabilities for ASCII art including reversing, flipping, and whitespace normalization. FigletString extends standard string functionality with ASCII art-specific operations.
3

4
## Capabilities
5

6
### FigletString Class
7

8
Enhanced string class that inherits from the standard string type while adding ASCII art manipulation methods.
9

10
```python { .api }
11
class FigletString:
12
    """
13
    ASCII art string with manipulation methods.
14
    
15
    Inherits from unicode string type, providing all standard string methods
16
    plus additional ASCII art manipulation capabilities.
17
    """
18
```
19

20
### Text Reversal
21

22
Creates a horizontal mirror image of the ASCII art by reversing each line and translating characters to their mirrored equivalents.
23

24
```python { .api }
25
def reverse(self) -> FigletString:
26
    """
27
    Create horizontal mirror image of ASCII art.
28
    
29
    Returns:
30
    FigletString: Horizontally reversed ASCII art
31
    
32
    Behavior:
33
    - Reverses character order in each line
34
    - Translates characters using reverse mapping (/->\\, etc.)
35
    - Preserves line count and overall structure
36
    """
37
```
38

39
#### Usage Example
40

41
```python
42
import pyfiglet
43

44
# Create ASCII art
45
text = pyfiglet.figlet_format("Hello", font="standard")
46
print("Original:")
47
print(text)
48

49
# Reverse the text
50
reversed_text = text.reverse()
51
print("Reversed:")
52
print(reversed_text)
53
```
54

55
### Text Flipping
56

57
Creates a vertical mirror image of the ASCII art by flipping lines upside down and translating characters to their flipped equivalents.
58

59
```python { .api }
60
def flip(self) -> FigletString:
61
    """
62
    Create vertical mirror image of ASCII art.
63
    
64
    Returns:
65
    FigletString: Vertically flipped ASCII art
66
    
67
    Behavior:
68
    - Reverses line order (top becomes bottom)
69
    - Translates characters using flip mapping (^->v, etc.)
70
    - Preserves character positions within lines
71
    """
72
```
73

74
#### Usage Example
75

76
```python
77
import pyfiglet
78

79
# Create ASCII art
80
text = pyfiglet.figlet_format("Hello", font="standard")
81
print("Original:")
82
print(text)
83

84
# Flip the text
85
flipped_text = text.flip()
86
print("Flipped:")
87
print(flipped_text)
88
```
89

90
### Whitespace Normalization
91

92
Removes surrounding empty lines while preserving internal structure and leading whitespace within the ASCII art.
93

94
```python { .api }
95
def strip_surrounding_newlines(self) -> str:
96
    """
97
    Remove empty leading and trailing lines.
98
    
99
    Returns:
100
    str: ASCII art with surrounding empty lines removed
101
    
102
    Behavior:
103
    - Removes empty lines at start and end
104
    - Preserves internal empty lines within the art
105
    - Preserves leading whitespace on each line
106
    - Returns regular string (not FigletString)
107
    """
108
```
109

110
#### Usage Example
111

112
```python
113
import pyfiglet
114

115
# Create ASCII art (often has surrounding newlines)
116
text = pyfiglet.figlet_format("Hi", font="standard")
117
print(f"Original length: {len(text.splitlines())} lines")
118
print(repr(text))
119

120
# Strip surrounding newlines
121
stripped = text.strip_surrounding_newlines()
122
print(f"Stripped length: {len(stripped.splitlines())} lines")
123
print(repr(stripped))
124
```
125

126
### Whitespace Standardization
127

128
Ensures ASCII art has exactly one empty line before and after the content.
129

130
```python { .api }
131
def normalize_surrounding_newlines(self) -> str:
132
    """
133
    Ensure exactly one empty line before and after content.
134
    
135
    Returns:
136
    str: ASCII art with normalized surrounding whitespace
137
    
138
    Behavior:
139
    - Adds one newline at start
140
    - Adds one newline at end
141
    - Removes any existing surrounding empty lines first
142
    """
143
```
144

145
#### Usage Example
146

147
```python
148
import pyfiglet
149

150
# Create ASCII art
151
text = pyfiglet.figlet_format("Test", font="standard")
152

153
# Normalize surrounding newlines
154
normalized = text.normalize_surrounding_newlines()
155
print("Normalized output:")
156
print(repr(normalized))
157
```
158

159
### List-Based Construction
160

161
Creates new FigletString instances from lists of strings representing lines.
162

163
```python { .api }
164
def newFromList(self, list: list[str]) -> FigletString:
165
    """
166
    Create new FigletString from list of lines.
167
    
168
    Parameters:
169
    - list (list[str]): List of strings representing lines
170
    
171
    Returns:
172
    FigletString: New FigletString instance with manipulation methods
173
    
174
    Behavior:
175
    - Joins lines with newlines
176
    - Adds trailing newline to match FIGlet format
177
    """
178
```
179

180
#### Usage Example
181

182
```python
183
import pyfiglet
184

185
# Get original FigletString
186
text = pyfiglet.figlet_format("ABC", font="standard")
187

188
# Modify lines manually
189
lines = text.splitlines()
190
modified_lines = [line.replace('A', '@') for line in lines]
191

192
# Create new FigletString
193
modified_text = text.newFromList(modified_lines)
194
print(modified_text)
195
```
196

197
## Character Translation Maps
198

199
FigletString uses internal translation maps for reverse and flip operations:
200

201
### Reverse Map
202
- Mirrors characters horizontally: `/` ↔ `\`, `(` ↔ `)`, `[` ↔ `]`, `{` ↔ `}`, `<` ↔ `>`
203
- Preserves most characters unchanged
204
- Used by the `reverse()` method
205

206
### Flip Map  
207
- Mirrors characters vertically: `^` ↔ `v`, Some character substitutions for visual flipping
208
- Used by the `flip()` method
209

210
## Combined Operations
211

212
FigletString methods can be chained for complex transformations:
213

214
```python
215
import pyfiglet
216

217
# Create ASCII art
218
text = pyfiglet.figlet_format("Hello", font="standard")
219

220
# Apply multiple transformations
221
result = text.reverse().flip().strip_surrounding_newlines()
222
print(result)
223

224
# Or step by step
225
reversed_text = text.reverse()
226
flipped_text = reversed_text.flip()  
227
final_text = flipped_text.strip_surrounding_newlines()
228
```
229

230
## Integration with Standard String Methods
231

232
Since FigletString inherits from the standard string type, all regular string methods are available:
233

234
```python
235
import pyfiglet
236

237
text = pyfiglet.figlet_format("Hello", font="standard")
238

239
# Standard string methods work
240
lines = text.splitlines()
241
upper_text = text.upper()
242
replaced_text = text.replace('H', '@')
243

244
# Combined with FigletString methods
245
modified = text.replace('#', '*').reverse()
246
```
247

248
## Return Types
249

250
- `reverse()` and `flip()` return `FigletString` instances
251
- `strip_surrounding_newlines()` and `normalize_surrounding_newlines()` return regular `str`
252
- `newFromList()` returns `FigletString` instance
253

254
This design allows for method chaining while providing clean string output when needed.