StrConcatWrap█ OVERVIEW
Contains functions for concatenation and wrapping of the strings:
- concatTrunc() / concatTrunc2() - Concatenate via a separator up to a given length truncating from left or right. concatTrunc2 returns also the number of overflowing chars (in a tuple)
- print() - A powerful concatenate function truncating chars from left or right and/or lines from top or bottom. By default just adds new lines respecting max length.
- wrap() - Wraps each line of the text adding prefix/postfix. If resulting string exceeds max length truncates from the end adding " "
- scroll() Returns a range of lines from the source string.
█ FUNCTIONS
method concatTrunc2(this, txt, separator, max_length, truncate_left, ignore_empty_strings)
Concatenates two strings leaving _max_length chars truncating from left/right. (Truncates from the end of the string by default).
this String to which txt is added
txt String to be added
max_length (int) (Optional) max length of string, default: 4096
separator (string) (Optional) If both this and txt are non empty separator is added in between. Usually " " is used.
truncate_left (bool) (Optional) if true truncates left string (this), if false - txt. Default - false (truncates txt)
ignore_empty_strings (bool) (Optional) if true and one of `this` or `txt` is empty just returns the other, if false - adds separator.
Returns: (tuple ) A tuple . E.g. if `this` is 4095 chars and separator is 2 chars then 4095+2=4097 exceeds default max_length = 4096 by 1, so will be returned, even if , e.g. `txt` is empty and `ignore_empty_strings` is true.
method concatTrunc(this, txt, separator, max_length, truncate_left, ignore_empty_strings)
Concatenates two strings leaving _max_length chars truncating from left/right. (Truncates from the end of the string by default).
this : string to which txt is added
txt : string to be added to this
max_length : max length of string, default: 4096
separator : If both this and txt are non empty separator is added in between. Usually " " is used.
truncate_left : if true truncates left string (this), if false - txt. Default - false (truncates txt)
ignore_empty_strings : (bool) (Optional) if true and one of `this` or `txt` is empty just returns the other, if false - adds separator.
Returns: (string) Resulting string
method printLines( this, txt, max_length, max_lines, line_break_regex, line_break, truncate_left, ignore_empty_strings, add_line_numbers, line_number_format, start_line_number, print_to_last_line)
Adds up to `max_lines` lines from `txt` to `this` observing `max_length`, truncating from left or right (truncating source strings `this` and/or `txt` themselves if necessary).
this : (string) Print outputs `txt` to the end of `this`
txt : (string) Print outputs `txt` to the end of `this`
max_length : (int) (Optional) Chars in excess of `max_length` will be truncated (ending chars by default, see `truncate_left` arg). Default: 4096
max_lines : (int) (Optional) Lines in excess of `max_lines` will be truncated (from end by default, see `truncate_left` arg). Default: 4096
line_break_regex : (string) (Optional) A regex expression used to search for linebrakes. Default is "( |\\r|\\r )"
line_break : (string) (Optional) A string added as a line break. Default is " ".
truncate_left : (bool) (Optional) If true chars in excess of `max_length` will be truncated from the beginning , if false - from the end. Default: false.
ignore_empty_strings : (bool) (Optional) If false a line break will be added (as an empty string), if false `this` will not change.
add_line_numbers : (bool) (Optional) If true adds number before each line. Default format: "LN0001". Custom fomat can be set with `line_number_format'.
line_numbers_format : (string) (Optional) Line number format (like in `str.format()`). Default: `"LN{0000: }"`
print_to_last_line : (string) (Optional) If true will add text to the last line (notwithout adding line break before the first added line). Default: false.
Returns: ` ` where `outS` = `this` + added lines, `intLenthOverflow` = number of truncated chars (including separator), e.g. if `this` is 4095 chars and separator is 2 chars then 4095+2=4097 exceeds default max_length = 4096 by 1, so will be returned, even if , e.g. `txt` is empty and `ignore_empty_strings` is true, and n - number of added lines
method print( this, txt, max_length, max_lines, truncate_left, truncate_top, truncate_lines_src, add_line_numbers, line_number_format, print_to_last_line)
Powerful concatenate function. In simplest form (`this.print(txt)`) just adds `txt` to the end of `this` starting from new line. If `print_to_last_line` is true then concatenates. Can truncate for _max_length (from right by default) and max_lines (truncating from top or bottom). (First removes excessive lines (over `max_lines`) then concatenates truncating for `max_length`.) `print()` looks for all kinds of line breaks (`\r`, ` ` or `\r `) and replaces them with ` `.
this : (string) Print outputs `txt` to the end of `this`
txt : (string) Print outputs `txt` to the end of `this`
max_length : (int) (Optional) Chars in excess of `max_length` will be truncated (ending chars by default, see `truncate_left` arg). Default: 4096
max_lines : (int) (Optional) Lines in excess of `max_lines` will be truncated (from end by default, see `truncate_left` arg). Default: 4096
truncate_left : (bool) (Optional) If true chars in excess of `max_length` will be truncated from the beginning , if false - from the end. Default: false.
truncate_top : (bool) (Optional) If true lines in excess of `max_lines` will be truncated from the top, if false - from the bottom. Default: false.
truncate_lines_src : (bool) (Optional) If true and either `this` or `txt` exceed `max_lines` they will be truncated (excessive lines removed). (Characters in excess of max_length will be truncated regardless). If truncate_top and txt has more than max_lines lines excessive lines will be truncated from the top. (if truncate_top escessive lines from `this` will be truncated regardless of truncate_src). If not truncate_top and this has more than max_lines lines excessive lines will be truncated from the bottom. (if not truncate_top escessive lines from `txt` will be truncated regardless of truncate_src)
add_line_numbers : (bool) (Optional) If true adds number before each line. Default format: "LN0001". Custom fomat can be set with `line_number_format'.
line_numbers_format : (string) (Optional) Line number format (like in `str.format()`). Default: `"LN{0000: }"`
print_to_last_line : (string) (Optional) If true will add text to the last line (notwithout adding line break before the first added line). Default: false.
Returns: ` ` where `outS` = `this` + added lines.
method wrap(this, wrap_width, breaker_prefix, breaker_postfix, line_postfix, max_length)
Wraps each line of `this` to wrap_width adding breaker_prefix to the end of each line (before " ") and breaker_postfix to the beginning of each line (after " ")" (i.e. breaker_prefix'es are effectively added to the end of each line (but the last) and breaker_postfix'es to the beginning of new line starting from second). If with breakers the line exceeds 4096 it is truncated from the right and " " is added at the end.
wrap_width : (series int) Width of each line (chars).
breaker_prefix : (series string) (Optional) Text to add at the end of each line. (Default = "")
breaker_postfix : (series string) (Optional) Text to add after the each added line break at the beginning of next line. (Default = "")
Returns: the wrapped text
export method scroll(this, start_line, lines_in_window, show_line_numbers, show_header)
Scrolls the text (this) by returning a given number of lines (`lines_in_window`) starting from `start_line`. Can add line numbers and/or a header line in the form "Starting from line ... out of total ... lines, ... chars"
start_line : (int) (Optional) Start line
lines_in_window : (int) (Optional) Number of lines to read and return
show_line_numbers : (bool) (Optional) If true preceeds each line with a line number in the form "LN0001}: "
show_header : (bool) (Optional) If true shows the header string in the form "Starting from line {0} out of total {1} lines, {2} chars" followed by a separator line "----------".
Returns: (string) Range of strings.
