StrConcatWrap

2 oct

█ 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 "\n" 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 [string, int]) A tuple [concatenated string, number of chars exceeding max_length (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 [this, 1] 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 "\n" 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 "(\\n|\\r|\\r\\n)"
    line_break: (string) (Optional) A string added as a line break. Default is "\n".
    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: `[outS, intLenthOverflow, n]` 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 [this, 1] 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`, `\n` or `\r\n`) and replaces them with `\n`.
    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: `[outS, intLenthOverflow, n]` 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 "\n") and breaker_postfix to the beginning of each line (after "\n")" (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.