str2d.Str2D
- class str2d.Str2D(data: Any | None = None, min_width: int | None = None, min_height: int | None = None, halign: str | None = 'left', valign: str | None = 'top', fill: str | Tuple[str, int] | None = None, **kwargs)[source]
Str2D is a class that allows you to manipulate 2D strings in Python. I had found myself wanting to paste blocks of text inline with other blocks of text. If you’ve ever tried to do this in a text editor, you’ll know that it can be a bit of a pain. vi and vim have a feature called visual block mode that makes this easier. But I wanted more flexibility and control. So I created Str2D.
Given a multi-line string, Str2D will convert it into something functionally equivalent where each line separated by a newline character will have the same number of characters. These are filled in with whatever character is specified but by default it is a space. This takes care of making sure that each row is the same width and is primed for manipulation.
The simplest example is to show how to create a Str2D object from a multi-line string and add it to another Str2D object.
Let’s start by constructing a new instance of Str2D and assinging it to the variable a.
from str2d import Str2D a = Str2D('a b c d\ne f g\nh i\nj') a
a b c d e f g h i j
It might not be clear but the 2nd, 3rd, and 4th lines are padded with spaces to make each line the same width. We can see this more clearly surrounding the object with a box.
a.box()
╭───────╮ │a b c d│ │e f g │ │h i │ │j │ ╰───────╯
The padded characters are not just spaces. The Str2D object is a structured array with two fields: ‘char’ and ‘alpha’. The ‘char’ field is the character array and the ‘alpha’ field is a boolean array with a of 1 or 0 for every character in the character array. The ‘alpha’ field is used to determine if a character will mask a second Str2D object when layered on top of it. It is analogous to the alpha channel in an image where when layered on top of another image, the alpha channel will indicate which pixels will be visible and which will be transparent. The ‘alpha’ field is used in the same way. A value of 1 means the character will be visible and a value of 0 means the character will be transparent. The padded characters are all given an ‘alpha’ value of 0.
If we use the Str3D object to layer another Str2D object below it, we’ll see that the padded characters will be transparent and the characters from the second Str2D object will be visible.
from str2d import Str3D b = Str2D('''\ ....... ....... ....... ....... ''') Str3D([a, b])
a b c d e f g.. h i.... j......
We can accomplish the same thing by using the fill_with method. This method will fill the padded characters with the specified character. More accurately, it will replace the characters in the ‘char’ field where the ‘alpha’ field is 0 with the specified character.
a.fill_with('.')
a b c d e f g.. h i.... j......
If we wanted to make all spaces transparent, we could use the hide method. This will set the ‘alpha’ field to 0 for all locations where the char field matches the specified character, which defaults to a space.
a.hide().fill_with('.')
a.b.c.d e.f.g.. h.i.... j......
Let’s create a new Str2D object and assign it to the variable c. This time we’ll set the halign parameter to ‘right’ which controls how lines with fewer characters than the maximum width are aligned. By default, it is set to ‘left’ which will align the lines to the left as we’ve seen in the previous example with the variable a.
c = Str2D('0\n1 2\n3 4 5\n6 7 8 9', halign='right') c
0 1 2 3 4 5 6 7 8 9We can now see our simple example of adding two Str2D objects together.
a + c
a b c d 0 e f g 1 2 h i 3 4 5 j 6 7 8 9
All of the transparent characters are preserved and we can fill the result as you’d expect.
(a + c).fill_with('.')
a b c d......0 e f g......1 2 h i......3 4 5 j......6 7 8 9
We’ll save the rest for the documentation of the individual methods.
operations
add(*args, **kwargs)Public method for adding the data without the need to use the + operator.
__add__(other[, right_side])Adding one Str2D object to another or a string to a Str2D object is the main point of this class.
__radd__(other)Dunder method handling the right side of the addition operation.Adding one Str2D object to another or a string to a Str2D object is the main point of this class.
div(*args, **kwargs)Public method for dividing the data without the need to use the / operator.
__truediv__(other[, right_side])Division is the vertical analog of the addition operation.
__rtruediv__(other)Division is the vertical analog of the addition operation.
__mul__(other)It doesn't make sense to multiply a Str2D object by another Str2D object.
__rmul__(other)It doesn't make sense to multiply a Str2D object by another Str2D object.
Construction
__init__([data, min_width, min_height, ...])Create a new Str2D object.
validate_fill([fill])Validate the fill value.
validate_halign(halign)Validate the horizontal alignment.
validate_valign(valign)Validate the vertical alignment.
struct_array_from_bool_array(array, char)Create a structured array from a boolean array.
struct_array_from_char_array(array)Create a structured array from a character array.
struct_array_from_string(string, **kwargs)Create a structured array from a string.
parse([data])Parse the input data into a structured array.
Class Methods
struct_pad(array, *args, **kwargs)Pads a structured array with fields 'char' and 'alpha'.
join_h(*args[, sep])join_h joins any number of Str2D objects horizontally.
join_v(*args[, sep])join_v joins any number of Str2D objects vertically.
equal_height(*args)Expand each Str2D object to have the same height.
equal_width(*args)Expand each Str2D object to have the same width.
equal_shape(*args)Expand each Str2D object to have the same shape.
Information/Documentation
show_with_alignment([expand, box])Show the alignment parameters with object.
transormation_palette([sep, expand, box])Show the transformation palette.
pre(**kwargs)Return HTML prefformatted text.
Special Dunder Methods
__getattr__(name)Enables convenient access to the transpose, horizontal flip, vertical flip, and rotation methods in a concatenated manner.
__getitem__(key)Passing on the indexing to the structured array data.
Methods
box()Wrapper around box_over and box_around methods.
box_around()Create a box around the data.
box_over()Create a box over the data.
circle(radius[, char])Create a circle over object.
hole(radius[, char])Create a hole over the object.
expand([x, y])The expand method expands the data by adding padding to the top, bottom, left, and right of the data.
pad(*args, **kwargs)pad pads the data with the fill value specified in the 'fill' keyword and is a wrapper around the class method struct_pad which in turn is a wrapper around np.pad.
split(indices_or_sections[, axis])split is analogous to np.split and splits the data along an axis.
insert(indices_or_sections[, axis, sep])insert is a wrapper around the split method and is used to visually insert a separator between the split data.
reshape(shape)Reshape the Str2D object.
roll(x, axis)Roll the data along an axis.
roll_h(x)Roll the data horizontally.
roll_v(x)Roll the data vertically.
hide([char])Hide where character array is char.
fill_with([char])Fill the data with the character.
String Methods that return a new Str2D object
lower()Return the lowercase version of the data.
lstrip(*args, **kwargs)Left strip line by line.
replace(old, new)Replace the data.
rstrip(*args, **kwargs)Right strip line by line.
strip(*args, **kwargs)Strip line by line.
strip2d([char])Strip the data 2-dimensionally.
title()Return the title version of the data.
upper()Return the uppercase version of the data.
String Methods that return a boolean array
isdigit()Return whether the data is a digit.
Transformations
This is the identity transformation.
Return the transpose of the Str2D object.
Return the horizontal flip of the data.
Return the vertical flip of the data.
Return the 90 degree rotation of the data.
Attributes
Return the alpha data.
Return the character data.
Return the height of the Str2D object.
Return the width of the Str2D object.
Return the shape of the Str2D object.
Return the keyword arguments used to create the Str2D object.
Fun Methods
pi()Replace the data with digits of pi.
e()Replace the data with digits of e.
phi()Replace the data with digits of phi.