1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 | package Torello.Java; import Torello.Java.Function.IntTFunction; import static Torello.Java.C.*; // Needed for a few JavaDoc Comments import Torello.JavaDoc.Field; import Torello.JavaDoc.Constructor; import Torello.JavaDoc.Method; import Torello.JavaDoc.AnnotationElem; /** * This class provides several {@code String} printing utilities such as abbreviation and list * printing. */ @Torello.JavaDoc.StaticFunctional public class StrPrint { private StrPrint() { } // ******************************************************************************************** // ******************************************************************************************** // HELPER & BASIC // ******************************************************************************************** // ******************************************************************************************** /** * Converts every line-character ({@code '\n'}) - <I>and any white-space before or after * that character</I>, into the {@code String} - {@code "\\n"} - which is the actual two * character sequence of a back-slash ({@code '\'}), followed by the letter {@code 'n'}. * * <BR /><BR />After new-line characters are replaced, the method will remove any duplicate * spaces that are present in the {@code String}, and reduce them to a single space character * * <BR /><TABLE CLASS=JDBriefTable> * <TR><TH>Input {@code String}</TH><TH>Returned {@code String}</TH></TR> * <TR><TD>"Hello World"</TD><TD>"Hello World"</TD></TR> * <TR><TD>"Hello \t World"</TD><TD>"Hello World"</TD></TR> * <TR><TD>"Hello World\n"</TD><TD>"Hello World\\n"</TD></TR> * <TR><TD>"Hello World \n\t \n"</TD><TD>"Hello World\\n\\n"</TD></TR> * <TR> * <TD>"Hello Today!\nHow Are You?"</TD> * <TD>"Hello Today!\\nHow Are You?"</TD> * </TR> * <TR> * <TD>"Hello,\n Testing 1, 2, 3\n"</TD> * <TD>"Hello,\\nTesting 1, 2, 3\\n"</TD> * </TR> * <TR> * <TD>"Hello,\n Testing 1, 2, 3 \n\t\t\t"</TD> * <TD>"Hello,\\nTesting 1, 2, 3\\n"</TD> * </TR> * <TR><TD>"\n"</TD><TD>"\\n"</TD></TR> * <TR><TD>"\n \t"</TD><TD>"\\n"</TD></TR> * <TR><TD>"\n\t \n\t \n\t "</TD><TD>"\\n\\n\\n"</TD></TR> * </TABLE> * * <BR />This method is used in printing Java Source Code to a terminal - in an abbreviated * way! After this method is finished, java-source-as-text is actually <B><I>still</I></B> * look readable, and can be printed in a table of methods on a page. It is used in the Java * Doc Upgrader tool, and makes printing up <B><I>both</I></B> method-signatures * <B><I>and</I></B> method bodies quite a bit easier. * * <BR /><BR />For a better understanding of the use and application of this function, please * take a look at the <B>{@code 'toString'}</B> methods: <B>{@link Method#toString()}, * {@link Constructor#toString()}, {@link Field#toString()} and * {@link AnnotationElem#toString()}</B> * * <BR /><BR /><B CLASS=JDDescLabel>Regular Expressions:</B> * * <BR />This method uses regular-expressions, rather performing an optimized, in-place, * {@code String} replacement (such as one with a {@code for} or {@code while} loop). This * means that there is a little efficiency sacrificed in the name of brevity. * * <BR /><BR />The replacement used in the {@code String.replaceAll} method was thouroughly * tested. The quadruple-backslash {@code '\n'} <I>is actually necessary!</I> The first * escape used is to communicate with the Java-Compiler, and the second round of escaping is * communicating with the Regular Expression Processor. * * @param s Any {@code java.lang.String}, preferably one with multiple lines of text. * * @return A {@code String}, where each line of text has been "trimmed", and the two * character sequence {@code "\\n"} inserted in-between each line. * * @see #abbrevStartRDSF(String, int, boolean) * @see #abbrevEndRDSF(String, int, boolean) */ public static String newLinesAsText(String s) { return s .replaceAll( // White-Space-Except-Newline, THEN newline, THEN White-SpaceExcept-Newline "[ \t\r\f\b]*\n[ \t\r\f\b]*", // Replace Each Occurence of that with: // == COMPILES-TO ==> "\\n" == REG-EX-READS ==> BackSlash and letter 'n' "\\\\n" ) // == COMPILES-TO ==> "\s+" == REG-EX-READS ==> 'spaces' .replaceAll("\\s+", " ") // Don't forget about leading and trailing stuff... .trim(); } // ******************************************************************************************** // ******************************************************************************************** // Abbreviating Text, with "newLinesAsText" - Helper // ******************************************************************************************** // ******************************************************************************************** /** * Convenience Method. * <BR /><B STYLE='color: red;'>RDSF: Remove Duplicate Spaces First</B> * <BR />Invokes: {@link StringParse#removeDuplicateSpaces(String)} * <BR />Or Invokes: {@link #newLinesAsText(String)} * <BR />Finally: {@link #abbrevStart(String, boolean, int)} */ public static String abbrevStartRDSF (String s, int maxLength, boolean seeEscapedNewLinesAsText) { // false is passed to 'abbrevStart' parameter 'escapeNewLines' because in both scenarios // of this conditional-statement, the new-lines have already been removed by the previous // method call. // // both 'removeDuplicateSpaces' and 'newLinesAsText' remove the new-lines return seeEscapedNewLinesAsText ? abbrevStart(newLinesAsText(s), false, maxLength) : abbrevStart(StringParse.removeDuplicateSpaces(s), false, maxLength); } /** * Convenience Method. * <BR /><B STYLE='color: red;'>RDSF: Remove Duplicate Spaces First</B> * <BR />Invokes: {@link StringParse#removeDuplicateSpaces(String)} * <BR />Or Invokes: {@link #newLinesAsText(String)} * <BR />Finally: {@link #abbrevEnd(String, boolean, int)} */ public static String abbrevEndRDSF (String s, int maxLength, boolean seeEscapedNewLinesAsText) { // false is passed to 'abbrevStart' parameter 'escapeNewLines' because in both scenarios // of this conditional-statement, the new-lines have already been removed by the previous // method call. // // both 'removeDuplicateSpaces' and 'newLinesAsText' remove the new-lines return seeEscapedNewLinesAsText ? abbrevEnd(newLinesAsText(s), false, maxLength) : abbrevEnd(StringParse.removeDuplicateSpaces(s), false, maxLength); } /** * Convenience Method. * <BR />Passes: {@code '0'} to parameter {@code 'abbrevPos'}, forcing the abbreviation to * occur at the <B>start</B> of the {@code String} (if long enough to be abbreviated) * @see #abbrev(String, int, boolean, String, int) */ public static String abbrevStart(String s, boolean escNewLines, int maxLength) { return Abbrev.print(s, 0, escNewLines, null, maxLength); } /** * This will abbreviate any {@code String} using either the ellipsis ({@code '...'}), or some * other use provided abbreviation-{@code String} - <I>as long as the provided {@code String} * is longer than {@code 'maxLength'}.</I> When {@code 's'} is, indeed, longer than * {@code 'maxLength'} the returned-{@code String} will contain the ellipsis abbreviation * beginning at {@code String}-index {@code 'abbrevPos'}. * * <BR /><BR />You have the option of asking that new-line characters ({@code '\n'}) be * escaped into the two-character {@code String: "\\n"}. This optional is provided so that * the output may fit on a single-line, for readability purposes. It will look somewhat like * an escaped {@code JSON} file, which also substitues {@code '\n'} characters for the * 'escaped' version {@code "\\n"}. <I>Note that when this occurs, the replaced-{@code String} * actually only contains two characters, <B>not three,</B> since the first back-slash your are * looking right here is, itself, an escape character!</I> * * @param s This may be any Java (non-null) {@code String} * * @param abbrevPos This parameter is used to indicate where the abbreviation-{@code String} * should occur - <I>if this {@code String 's'} is long enough to be abbreviated.</I> For * instance, if {@code '0'} (zero) were passed to this parameter, and {@code 's'} were longer * than parameter {@code 'maxLength'}, then an ellipsis would be appended to the beginning of * the returned-{@code 'String'}. (Or, if some other {@code 'abbrevStr'} were specified, that * other abbreviation would be appended to the beginning of the returned-{@code String}) * * @param escapeNewLines <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_ENL> * @param abbrevStr <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_STR> * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_MXL> * * @return If the input {@code String} has a <I>length less-than {@code 'maxLength'}</I>, then * it is returned, unchanged. If the input contained new-line characters, and you have * requested to escape them, that replacement is performed first (which makes the original * {@code String}} longer). Then, if the {@code String} is longer than {@code 'maxLength'}, * it is abbreviated, and either the default ellipsis <I>or the user-provided * {@code 'abbrevStr'}</I> are inserted at location {@code 'abbrevPos'} and returned. * * <BR /><BR />If, after the new-line escape-replacement, the returned-{@code String} would not * be longer than {@code 'maxLength'}, then that escaped-{@code String} is returned, as is * (without any elliptical-characters). * * @throws IllegalArgumentException If the value for {@code 'maxLength'} is negative, or if it * is less than the length of the abbreviation. * * <BR /><BR />Specifically, if {@code 'maxLength'} isn't even long enough to fit the abbreviation * itself, then this exception will throw. * * <BR /><BR />If the value passed to {@code 'abbrevPos'} is negative or longer than the value * passed to {@code 'maxLength'} minus the length of the ellipsis-{@code String}, then this * exception will also throw. */ public static String abbrev( String s, int abbrevPos, boolean escapeNewLines, String abbrevStr, int maxLength ) { return Abbrev.print(s, abbrevPos, escapeNewLines, abbrevStr, maxLength); } /** * Convenience Method. * <BR />Parameter: {@code spaceBeforeAbbrev} set to {@code FALSE} * <BR />Abbreviates: Default ellipsis ({@code '...'}) are placed at the end of the * {@code String} * @see #abbrev(String, boolean, boolean, String, int) */ public static String abbrevEnd(String s, boolean escapeNewLines, int maxLength) { return Abbrev.print(s, false, escapeNewLines, null, maxLength); } /** * This will abbreviate any {@code String} using either the ellipsis ({@code '...'}), or some * other use provided abbreviation-{@code String}, if the provided {@code String} is longer * than {@code 'maxLength'}. If the returned-{@code String} is, indeed, abbreviated then the * elliptical-abbreviation {@code String} will be placed <I>at the end of the * returned-{@code String}</I> * * <BR /><BR />You have the option of asking that new-line characters ({@code '\n'}) be * escaped into the two-character {@code String: "\\n"}. This optional is provided so that * the output may fit on a single-line, for readability purposes. It will look somewhat like * an escaped {@code JSON} file, which also substitues {@code '\n'} characters for the * 'escaped' version {@code "\\n"}. <I>Note that when this occurs, the replaced-{@code String} * actually only contains two characters, <B>not three,</B> since the first back-slash your are * looking right here is, itself, an escape character!</I> * * @param s This may be any Java (non-null) {@code String} * * @param spaceBeforeAbbrev This ensures that for whatever variant of ellipsis being used, the * space-character is inserted directly before appending the ellipsis {@code "..."} or the * user-provided {@code 'abbrevStr'}. * * @param escapeNewLines <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_ENL> * @param abbrevStr <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_STR> * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_MXL> * * @return If the input {@code String} has a <I>length less-than {@code 'maxLength'}</I>, then * it is returned, unchanged. If the input contained new-line characters, and you have * requested to escape them, that replacement is performed first (which makes the original * {@code String}} longer). Then, if the {@code String} is longer than {@code 'maxLength'}, * it is abbreviated, and either the default ellipsis <I>or the user-provided * {@code 'abbrevStr'}</I> are are appended to the end and returned. * * @throws IllegalArgumentException If the value for {@code 'maxLength'} is negative, or if it * is less than the length of the abbreviation plus the value of {@code 'spaceBeforeAbbrev'}. * <BR /><BR />Specifically, if {@code 'maxLength'} isn't even long enough to fit the abbreviation * itself, then this exception will throw. */ public static String abbrev( String s, boolean spaceBeforeAbbrev, boolean escapeNewLines, String abbrevStr, int maxLength ) { return Abbrev.print(s, spaceBeforeAbbrev, escapeNewLines, abbrevStr, maxLength); } // ******************************************************************************************** // ******************************************************************************************** // Abbreviated List Printing // ******************************************************************************************** // ******************************************************************************************** /** * Convenience Method. * <BR />Passes: {@code Object.toString()} to {@code 'listItemPrinter'} * @see #printListAbbrev(Iterable, IntTFunction, int, int, boolean, boolean, boolean) */ public static <ELEM> String printListAbbrev( Iterable<ELEM> list, int lineWidth, int indentation, boolean seeEscapedNewLinesAsText, boolean printNulls, boolean showLineNumbers ) { return PrintListAbbrev.print( list, (int i, Object o) -> o.toString(), lineWidth, indentation, seeEscapedNewLinesAsText, printNulls, showLineNumbers ); } /** * <EMBED CLASS=defs DATA-LIST_TYPE=Array> * <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_DESCRIPTION> * @param list Any iterable-list of Java Object's * @param listItemPrinter <EMBED CLASS='extenal-html' DATA-FILE-ID=SP_PLA_LIST_ITEM_PR> * @param lineWidth <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_LINE_WIDTH> * @param indentation <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_INDENTATION> * @param seeEscapedNewLinesAsText <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SEE_ESC_NL> * @param printNulls <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_PRINT_NULLS> * @param showLineNumbers <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SHOW_LNUMS> * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_RETURNS> * @see StringParse#zeroPad10e2(int) * @see #abbrevEndRDSF(String, int, boolean) * @see StringParse#nChars(char, int) * @see StringParse#trimLeft(String) */ public static <ELEM> String printListAbbrev( Iterable<ELEM> list, IntTFunction<? super ELEM, String> listItemPrinter, int lineWidth, int indentation, boolean seeEscapedNewLinesAsText, boolean printNulls, boolean showLineNumbers ) { return PrintListAbbrev.print( list, listItemPrinter, lineWidth, indentation, seeEscapedNewLinesAsText, printNulls, showLineNumbers ); } /** * Convenience Method. * <BR />Passes: {@code Object.toString()} to {@code 'listItemPrinter'} * @see #printListAbbrev(Object[], IntTFunction, int, int, boolean, boolean, boolean)} */ public static <ELEM> String printListAbbrev( ELEM[] arr, int lineWidth, int indentation, boolean seeEscapedNewLinesAsText, boolean printNulls, boolean showLineNumbers ) { return PrintListAbbrev.print( arr, (int i, Object o) -> o.toString(), lineWidth, indentation, seeEscapedNewLinesAsText, printNulls, showLineNumbers ); } /** * <EMBED CLASS=defs DATA-LIST_TYPE=Array> * <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_DESCRIPTION> * @param list Any iterable-list of Java Object's * @param listItemPrinter <EMBED CLASS='extenal-html' DATA-FILE-ID=SP_PLA_LIST_ITEM_PR> * @param lineWidth <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_LINE_WIDTH> * @param indentation <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_INDENTATION> * @param seeEscapedNewLinesAsText <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SEE_ESC_NL> * @param printNulls <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_PRINT_NULLS> * @param showLineNumbers <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SHOW_LNUMS> * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_RETURNS> * @see StringParse#zeroPad10e2(int) * @see #abbrevEndRDSF(String, int, boolean) * @see StringParse#trimLeft(String) */ public static <ELEM> String printListAbbrev( ELEM[] list, IntTFunction<? super ELEM, String> listItemPrinter, int lineWidth, int indentation, boolean seeEscapedNewLinesAsText, boolean printNulls, boolean showLineNumbers ) { return PrintListAbbrev.print( list, listItemPrinter, lineWidth, indentation, seeEscapedNewLinesAsText, printNulls, showLineNumbers ); } // ******************************************************************************************** // ******************************************************************************************** // Line(s) of Text // ******************************************************************************************** // ******************************************************************************************** /** * This will return the complete text-lines of character data for the line identified by * token-substring position parameters {@code pos} and {@code len}. This method will search, * in the left-direction (decreasing {@code String} index) for the first new-line character * identified. It will also search, starting at position {@code pos + len}, for the first * new-line character in the right-direction (increasing {@code String} index). * * <BR /><BR />If the token-substring identified by {@code s.substring(pos, len)} itself * contains any new-line characters, these will neither affect the prepended, nor the * post-pended search {@code String}. To be precise, any newline characters between * {@code 'pos'} and {@code 'len'} will be irrelevant to the left-wards and right-wards * newlines searches for new-line characters. * * @param s This may be any valid Java {@code String}. It ought to be some variant of a * text-file. It will be searched for the nearest {@code '\n'} character - <I>in both * directions, left and right</I> - from parameter {@code int 'pos'} and parameter * {@code int 'len'} * * @param pos This is a position in the input-parameter {@code String 's'}. The nearest * {@code '\n'} (new-line) character, <I>to the left</I> of this position, will be found and * identified. If the {@code char} at {@code s.charAt(pos)} is, itself, a {@code '\n'} * (newline) character, then no left-direction search will be performed. The left-most * position of the returned substring would then be {@code pos + 1}. * * @param len The search for the 'right-most' {@code '\n'} (newline-character) will begin at * position {@code 'len'}. If the character at {@code s.charAt(pos + len)} is, itself, a * new-line character, then no right-direction search will be performed. The right-most * position of the returned substring would be {@code pos + len - 1}. * * @param unixColorCode If this {@code String} is null, it will be ignored. If this * {@code String} is non-null, it will be inserted before the "Matching {@code String}" * indicated by the index-boundaries {@code pos} <I>TO</I> {@code pos + len}. * * <BR /><BR /><B>NOTE:</B> No Validity Check shall be performed on this {@code String}, and * the user is not obligated to provide a {@link C} valid UNIX Color-Code {@code String}. * Also, a closing {@code C.RESET} is inserted after the terminus of the match. * * @return The {@code String} demarcated by the first new-line character PLUS 1 * <I><B>BEFORE</I></B> index {@code 'pos'}, and the first new-line character MINUS 1 * <I><B>AFTER</I></B> index {@code pos + len}. * * <BR /><BR /><B>NOTE:</B> The above does mean, indeed, that the starting and ending * new-lines <B>WILL NOT</B> be included in the returned {@code String}. * * <BR /><BR /><B>ALSO:</B> Also, if there are no new-line characters before position * {@code 'pos'}, then every character beginning at position zero will be included in the * returned {@code String} result. Also, if there are no new-line characters after position * {@code pos + len} then every character after position {@code pos + len} will be appended to * the returned {@code String} result. * * @throws StringIndexOutOfBoundsException If either {@code 'pos'}, or {@code 'pos + len'} are * not within the bounds of the input {@code String 's'} * * @throws IllegalArgumentException If the value passed to parameter {@code 'len'} is zero or * negative. */ public static String lineOrLines(String s, int pos, int len, String unixColorCode) { if ((pos >= s.length()) || (pos < 0)) throw new StringIndexOutOfBoundsException( "The integer passed to parameter 'pos' [" + pos + "], is past the bounds of the end " + "of String 's', which has length [" + s.length() + "]" ); if (len <= 0) throw new IllegalArgumentException ("The value passed to parameter 'len' [" + len + "], may not be negative."); if ((pos + len) > s.length()) throw new StringIndexOutOfBoundsException( "The total of parameter 'pos' [" + pos + "], and parameter 'len' [" + len + "], is: " + "[" + (pos + len) + "]. Unfortunately, String parameter 's' only has length " + "[" + s.length() + "]" ); int linesStart, linesEnd, temp; if (pos == 0) linesStart = 0; else if (s.charAt(pos) == '\n') linesStart = pos + 1; else if ((temp = StrIndexOf.left(s, pos, '\n')) != -1) linesStart = temp + 1; else linesStart = 0; if ((pos + len) == s.length()) linesEnd = s.length(); else if (s.charAt(pos + len) == '\n') linesEnd = pos + len; else if ((temp = s.indexOf('\n', pos + len)) != -1) linesEnd = temp; else linesEnd = s.length(); /* // VERY USEFUL FOR DEBUGGING. DO NOT DELETE... // NOTE: This method is the one that GREP uses. System.out.println("s.charAt(pos)\t\t= " + "[" + s.charAt(pos) + "]"); System.out.println("s.charAt(pos+len)\t= " + "[" + s.charAt(pos+len) + "]"); System.out.println("s.length()\t\t= " + s.length()); System.out.println("pos\t\t\t= " + pos); System.out.println("pos + len\t\t= " + (pos + len)); System.out.println("linesStart\t\t= " + linesStart); System.out.println("linesEnd\t\t= " + linesEnd); */ return (unixColorCode != null) ? s.substring(linesStart, pos) + unixColorCode + s.substring(pos, pos + len) + RESET + s.substring(pos + len, linesEnd) : s.substring(linesStart, linesEnd); /* OOPS.... For Posterity, this shall remain, here, but commented s.substring(linesStart, pos) + s.substring(pos, pos + len) + s.substring(pos + len, linesEnd); */ } /** * This will return the complete text-line of character data from 'inside' the input-parameter * {@code String s}. The meaning of {@code 'complete text-line'}, in this method, is that any * and all character data between the first {@code '\n'} (new-line character) when scanning * towards <I>the right</I> (increasing {@code String}-index) and the first {@code '\n'} * character when scanning towards <I>the left</I> (decreasing index) constitutes * {@code 'a line'} (of text-data). * * <BR /><BR />This scan shall for the left-most and right-most new-line shall begin at * {@code String}-index parameter {@code pos}. If either the left-direction or * right-direction scan does not find any new-line characters, then start and end indices of * the returned line of text shall be demarcated by input-{@code String} index {@code '0'} and * index {@code String.length()}, <I><B>respectively</B></I> * * @param s This may be any valid Java {@code String}. It ought to be some variant of a * text-file. It will be searched for the nearest {@code '\n'} character - <I>in both * directions, left and right</I> - from parameter {@code int 'pos'}. * * @param pos This is a position in the input-parameter {@code String 's'}. The nearest * new-line character both to the left of this position, and to the right, will be found and * identified. If the character at {@code s.charAt(pos)} is itself a newline {@code '\n'} * character, then <I>an exception shall throw</I>. * * @return The {@code String} identified by the first new-line character PLUS 1 * <I><B>BEFORE</I></B> index {@code 'pos'}, and the first new-line character MINUS 1 * <I><B>AFTER</I></B> index {@code 'pos + len'}. * * <BR /><BR /><B>NOTE:</B> The above means, that the starting and ending new-lines, * themselves, will not be included in the {@code String} that is returned. * * <BR /><BR /><B>ALSO:</B> Also, if there are no new-line characters before position * {@code 'pos'}, then every character beginning at position zero will be included in the * returned {@code String} result. Also, if there are no new-line characters after position * {@code 'pos + len'} then every character after position {@code 'pos + len'} will be appended * to the returned {@code String} result. * * @throws StringIndexOutOfBoundsException If {@code 'pos'} is not within the bounds of the * input {@code String 's'} * * @throws IllegalArgumentException If the character in {@code String 's'} at position * {@code 'pos'} is a newline {@code '\n'}, itself. */ public static String line(String s, int pos) { if ((pos > s.length()) || (pos < 0)) throw new StringIndexOutOfBoundsException( "The integer passed to parameter 'pos' [" + pos + "], is past the bounds of the end of " + "String 's', which has length [" + s.length() + "]" ); if (s.charAt(pos) == '\n') throw new IllegalArgumentException( "The position-index for string-parameter 's' contains, itself, a new line character " + "'\\n.' This is not allowed here." ); int lineStart, lineEnd; // Prevents StrIndexOf from throwing StringINdexOutOfBounds if (pos == 0) lineStart = 0; // Also prevent lineStart equal-to '-1' else if ((lineStart = StrIndexOf.left(s, pos, '\n')) == -1) lineStart = 0; // Prevent lineEnd equal to '-1' if ((lineEnd = s.indexOf('\n', pos)) == -1) lineEnd = s.length(); // if this is the first line, there was no initial '\n', so don't skip it! return (lineStart == 0) // This version returns the String from the position-0 (Pay Attention!) ? s.substring(0, lineEnd) // This version simply eliminates the '\n' that is in the directly-preceeding character : s.substring(lineStart + 1, lineEnd); } /** * This will retrieve the first {@code 'n'} lines of a {@code String} - where a line is defined * as everything up to and including the next newline {@code '\n'} character. * * @param s Any java {@code String}. * * @param n This is the number of lines of text to retrieve. * * @return a substring of s where the last character in the {@code String} is a {@code '\n'}. * The last character should be the nth {@code '\n'} character found in s. If there is no such * character, then the original {@code String} shall be returned instead. * * @throws NException This exception shall throw if parameter {@code 'n'} is less than 1, or * longer than {@code s.length()}. */ public static String firstNLines(String s, int n) { NException.check(n, s); int pos = StrIndexOf.nth(s, n, '\n'); if (pos != -1) return s.substring(0, pos + 1); else return s; } /** * This will retrieve the last 'n' lines of a {@code String} - where a line is defined as * everything up to and including the next newline {@code '\n'} character. * * @param s Any java {@code String}. * * @param n This is the number of lines of text to retrieve. * * @return a substring of {@code 's'} where the last character in the {@code String} is a * new-line character {@code '\n'}, and the first character is the character directly before * the nth newline {@code '\n'} found in {@code 's'} - starting the count at the end of the * {@code String}. If there is no such substring, then the original {@code String} shall be * returned. * * @throws NException This exception shall throw if {@code 'n'} is less than 1, or longer * {@code s.length()}. */ public static String lastNLines(String s, int n) { NException.check(n, s); int pos = StrIndexOf.nthFromEnd(s, n, '\n'); if (pos != -1) return s.substring(pos + 1); else return s; } /** * This is used for "trimming each line" of an input {@code String}. Generally, when dealing * with HTML there may be superfluous white-space that is useful in some places, but not * necessarily when HTML is copied and pasted to other sections of a page (or to another page, * altogether). This will split a {@code String} by new-line characters, and then trim each * line, and afterward rebuild the {@code String} and return it. * * <BR /><BR /><B CLASS=JDDescLabel>CRLF Issues:</B> * * <BR />This will only split the {@code String} using the standard {@code '\n'} character. If * the {@code String} being used uses {@code '\r'} or {@code '\n\r'}, use a different trim * method. * * @param str This may be any {@code String}. It will be split by new-line characters * {@code '\n'} * * @return Returns the rebuilt {@code String}, with each line having a {@code String.trim();} * operation performed. */ public static String trimEachLine(String str) { StringBuilder sb = new StringBuilder(); for (String s : str.split("\\n")) if ((s = s.trim()).length() == 0) continue; else sb.append(s + '\n'); return sb.toString().trim(); } /** * Interprets an input {@code String} as one which was read out of a Text-File. Counts the * number of new-line ({@code '\n'}) characters between {@code String} indices {@code '0'} and * {@code 'pos'} * * <BR /><BR />This is intended be the Line-Number where {@code String}-Index parameter * {@code 'pos'} is located inside the {@code 'str'} (presuming {@code 'str'} was retrieved * from a Text-File). * * @param str Any Java {@code String}, preferably one with multiple lines of text. * @param pos Any valid {@code String}-Index that occurs ithin {@code 'str'} * * @return The Line-Number within Text-File parameter {@code 'str'} which contains * {@code String}-Index parameter {@code 'pos'} * * @throws StringIndexOutOfBoundsException If integer-parameter {@code 'pos'} is negative or * past the length of the {@code String}-Parameter {@code 'str'}. * * @see #lineNumberSince(String, int, int, int) */ public static int lineNumber(String str, int pos) { if (pos < 0) throw new StringIndexOutOfBoundsException ("The number provided to index parameter 'pos' : [" + pos + "] is negative."); if (pos >= str.length()) throw new StringIndexOutOfBoundsException( "The number provided to index parameter 'pos' : [" + pos + "] is greater than the " + "length of the input String-Parameter 'str' [" + str.length() + "]." ); int lineNum = 1; for (int i=0; i <= pos; i++) if (str.charAt(i) == '\n') lineNum++; return lineNum; } /** * This methe may be used, iteratively, inside of a loop for finding the location of any * subsequent {@code String}-Index within a Text-File, based on the information obtained from * a previous Line-Number retrieval. * * <BR /><BR /><B CLASS=JDDescLabel>Use inside For-Loop:</B> * * <BR />This method is designed to be used within a {@code 'for'} or {@code 'while'} loop. * Though it is true that the exception-check which occurs inside this method is superfluous * and redundant, the cost incurred by the two {@code if}-statements is minimal. These checks * are used here, in the code, primarily for readability. * * <BR /><BR />If maximum efficiency is needed, then copy and paste the bottom two lines of * code into your editor, and use that instead, without the exception-checks. * * <BR />In the example below, it should be noted how to use both methods to iterate through * the line numbers in a Text-File, efficiently. * * <DIV CLASS=EXAMPLE>{@code * * int[] posArr = findIndices(myString, "Raindrops on Roses", "Whiskers on Kittens"); * int lineNumber = StrPrint.lineNumber(myString, posArr[0]); * int prevPos = posArr[0]; * * System.out.println("There is a match on line: " + lineNumber); * * for (int i=1; i < posArr.length; i++) * { * lineNumber = StrPrint.lineNumberSince(myString, posArr[i], lineNumber, prevPos); * System.out.println("There is a match on line: " + lineNumber); * * prevPos = posArr[i]; * } * }</DIV> * * @param str Any Java {@code String}. This {@code String} will be interpreted as a Text-File * whose newline characters ({@code '\n'} chars) represent lines of text. * * @param pos Any valid {@code String}-index within {@code 'str'} * * @param prevLineNum This should be the Line-Number that contains the {@code String}-index * {@code 'prevPos'} * * @param prevPos This may be any index contained by {@code String} parameter {@code 'str'}. * It is expected that this parameter be an index that occured on Line-Number * {@code 'prevLineNum'} of the Text-File {@code 'str'} * * @return The Line-Number within Text-File parameter {@code 'str'} that contains * {@code String}-index {@code 'pos'} * * @throws IllegalArgumentException If {@code 'pos'} is less than or equal to * {@code 'prevPos'}, or if {@code 'prevLineNum'} is less than zero. * * @see #lineNumber(String, int) */ public static int lineNumberSince(String str, int pos, int prevLineNum, int prevPos) { if (pos <= prevPos) throw new IllegalArgumentException( "The number provided to index parameter 'pos' : [" + pos + "] is less than or equal " + "to previous-match index-parameter prevPos : [" + prevPos + "]" ); if (prevLineNum < 0) throw new IllegalArgumentException( "You have provided a negative number to Line-Number parameter 'prevLineNum' : " + "[" + prevLineNum + "]" ); for (int i = (prevPos + 1); i <= pos; i++) if (str.charAt(i) == '\n') prevLineNum++; return prevLineNum; } // ******************************************************************************************** // ******************************************************************************************** // Abbreviation: Line-Length **AND** Number of Lines // ******************************************************************************************** // ******************************************************************************************** /** * This method allows for printing an abbreviation of a {@code String} such that * <B STYLE='color: red;'><I>BOTH</I></B> the number of lines (height), * <B STYLE='color: red;'><I>AND</I></B> the length of each line of text (width) can both be * abbreviated. There is even a third abbreviation that is possible, and that is where * blank-links can be compacted / flattened first (before the abbreviation process starts). * * <BR /><BR />This method is being used for printing JSON-Response Objects that contain large * HTML-Page {@code String's}. Primarily, if you want to see a message, but do not want * hundreds or even thousands of lines of HTML blasted across your terminal, then this method is * for you! * * <BR /><BR />The package {@code Torello.Browser's} Web-Sockets Communications is making use * of this for printing Chrome-Browser Messages to the terminal. * * @param s Any Java {@code String} * * @param horizAbbrevStr If you have a specific Abbreviation-{@code String} that you would like * to see used in Horizontally-Abbreviated Lines, please pass it here. * * <BR /><BR />Note that this value is directly passed to the {@code 'abbrevStr'} parameters * in the Standard {@code String}-Abbreviation methods. This means that when this parameter is * null, it will be ignored - <I>and if any horizontal (line-length) abbreviattions occur, then * the 'Default-Abbreviation {@code String}' {@code "..."} will be used</I>. * * <BR ><BR />Also note that if parameter {@code 'maxLineLength'} is passed null, then lines of * text will not be shortened. In that case, each line of text will retain its exact length * that occured prior to the internal {@code String.split()} invocation. * * @param maxLineLength If you would like to shorten each line of text which is appended to the * returned {@code String}, then pass a positive value to this parameter. * * <BR /><BR />This parameter may be null, and if it is, it will be ignored. In such cases, * individual lines of text will retain their original length. * * @param maxNumLines This is the maximum number of lines of text that will appear in the * returned {@code String}. Note, under normal operation, if this parameter is passed * {@code '3'}, then there will be exactly three lines of text. Furthermore there will be * exactly {@code '2'} newline {@code '\n'} characters. * * @param compactConsecutiveBlankLines When this parameter is passed {@code TRUE}, any * series of Empty-Lines, or lines only containing White-Space will be compacted to a single * line of text that simply states {@code "[Compacted 10 Blank Lines]"} (or however many * White-Space-Only Lines were actually compacted, if that number isn't {@code '10'}) * * @return The modified {@code String}. * * @throws IllegalArgumentException If parameter {@code 'maxNumLines'} is less than 3. The * returned {@code String} must be long enough to keep the first line, the last line and the * abbreviation note. * * <BR /><BR />This exception will also throw if the internal invocation of the standard * {@code String}-abbreviation method is passed a {@code 'maxLineLength'} that is less than * the minimum line-length requirements for a successful horizontal abbreviation. * * <BR /><BR />Finally, this exception throws if {@code 'maxLineLength'} and * {@code 'maxNumLines'} are both passed null, and {@code 'compactConsecutiveBlankLines'}. * This scenario is considered an error-case because there it would exact a situation where * there is nothing for this method to do. */ public static String widthHeightAbbrev( final String s, final String horizAbbrevStr, final Integer maxLineLength, final Integer maxNumLines, final boolean compactConsecutiveBlankLines ) { return VertAndHorizAbbrev.print (s, horizAbbrevStr, maxLineLength, maxNumLines, compactConsecutiveBlankLines); } } |