Commit | Line | Data |
---|---|---|
a3b510ab NR |
1 | /* |
2 | * This file is part of lanterna (http://code.google.com/p/lanterna/). | |
3 | * | |
4 | * lanterna is free software: you can redistribute it and/or modify | |
5 | * it under the terms of the GNU Lesser General Public License as published by | |
6 | * the Free Software Foundation, either version 3 of the License, or | |
7 | * (at your option) any later version. | |
8 | * | |
9 | * This program is distributed in the hope that it will be useful, | |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
12 | * GNU Lesser General Public License for more details. | |
13 | * | |
14 | * You should have received a copy of the GNU Lesser General Public License | |
15 | * along with this program. If not, see <http://www.gnu.org/licenses/>. | |
16 | * | |
17 | * Copyright (C) 2010-2015 Martin | |
18 | */ | |
19 | package com.googlecode.lanterna; | |
20 | ||
21 | import java.util.ArrayList; | |
22 | import java.util.Arrays; | |
23 | import java.util.LinkedList; | |
24 | import java.util.List; | |
25 | ||
26 | /** | |
27 | * This class contains a number of utility methods for analyzing characters and | |
28 | * strings in a terminal context. The main purpose is to make it easier to work | |
29 | * with text that may or may not contain double-width text characters, such as | |
30 | * CJK (Chinese, Japanese, Korean) and other special symbols. This class assumes | |
31 | * those are all double-width and in case the terminal (-emulator) chooses to | |
32 | * draw them (somehow) as single-column then all the calculations in this class | |
33 | * will be wrong. It seems safe to assume what this class considers double-width | |
34 | * really is taking up two columns though. | |
35 | * | |
36 | * @author Martin | |
37 | */ | |
38 | public class TerminalTextUtils { | |
39 | private TerminalTextUtils() { | |
40 | } | |
41 | ||
42 | /** | |
43 | * Given a character, is this character considered to be a CJK character? | |
44 | * Shamelessly stolen from <a href="http://stackoverflow.com/questions/1499804/how-can-i-detect-japanese-text-in-a-java-string" | |
45 | * >StackOverflow</a> where it was contributed by user Rakesh N | |
46 | * | |
47 | * @param c | |
48 | * Character to test | |
49 | * @return {@code true} if the character is a CJK character | |
50 | * | |
51 | */ | |
52 | public static boolean isCharCJK(final char c) { | |
53 | Character.UnicodeBlock unicodeBlock = Character.UnicodeBlock.of(c); | |
54 | return (unicodeBlock == Character.UnicodeBlock.HIRAGANA) | |
55 | || (unicodeBlock == Character.UnicodeBlock.KATAKANA) | |
56 | || (unicodeBlock == Character.UnicodeBlock.KATAKANA_PHONETIC_EXTENSIONS) | |
57 | || (unicodeBlock == Character.UnicodeBlock.HANGUL_COMPATIBILITY_JAMO) | |
58 | || (unicodeBlock == Character.UnicodeBlock.HANGUL_JAMO) | |
59 | || (unicodeBlock == Character.UnicodeBlock.HANGUL_SYLLABLES) | |
60 | || (unicodeBlock == Character.UnicodeBlock.CJK_UNIFIED_IDEOGRAPHS) | |
61 | || (unicodeBlock == Character.UnicodeBlock.CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A) | |
62 | || (unicodeBlock == Character.UnicodeBlock.CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B) | |
63 | || (unicodeBlock == Character.UnicodeBlock.CJK_COMPATIBILITY_FORMS) | |
64 | || (unicodeBlock == Character.UnicodeBlock.CJK_COMPATIBILITY_IDEOGRAPHS) | |
65 | || (unicodeBlock == Character.UnicodeBlock.CJK_RADICALS_SUPPLEMENT) | |
66 | || (unicodeBlock == Character.UnicodeBlock.CJK_SYMBOLS_AND_PUNCTUATION) | |
67 | || (unicodeBlock == Character.UnicodeBlock.ENCLOSED_CJK_LETTERS_AND_MONTHS) | |
68 | || (unicodeBlock == Character.UnicodeBlock.HALFWIDTH_AND_FULLWIDTH_FORMS && c < 0xFF61); // The | |
69 | // magic | |
70 | // number | |
71 | // here | |
72 | // is | |
73 | // the | |
74 | // separating | |
75 | // index | |
76 | // between | |
77 | // full-width | |
78 | // and | |
79 | // half-width | |
80 | } | |
81 | ||
82 | /** | |
83 | * Checks if a character is expected to be taking up two columns if printed | |
84 | * to a terminal. This will generally be {@code true} for CJK (Chinese, | |
85 | * Japanese and Korean) characters. | |
86 | * | |
87 | * @param c | |
88 | * Character to test if it's double-width when printed to a | |
89 | * terminal | |
90 | * @return {@code true} if this character is expected to be taking up two | |
91 | * columns when printed to the terminal, otherwise {@code false} | |
92 | */ | |
93 | public static boolean isCharDoubleWidth(final char c) { | |
94 | return isCharCJK(c); | |
95 | } | |
96 | ||
97 | /** | |
98 | * @deprecated Call {@code getColumnWidth(s)} instead | |
99 | */ | |
100 | @Deprecated | |
101 | public static int getTrueWidth(String s) { | |
102 | return getColumnWidth(s); | |
103 | } | |
104 | ||
105 | /** | |
106 | * Given a string, returns how many columns this string would need to occupy | |
107 | * in a terminal, taking into account that CJK characters takes up two | |
108 | * columns. | |
109 | * | |
110 | * @param s | |
111 | * String to check length | |
112 | * @return Number of actual terminal columns the string would occupy | |
113 | */ | |
114 | public static int getColumnWidth(String s) { | |
115 | return getColumnIndex(s, s.length()); | |
116 | } | |
117 | ||
118 | /** | |
119 | * Given a string and a character index inside that string, find out what | |
120 | * the column index of that character would be if printed in a terminal. If | |
121 | * the string only contains non-CJK characters then the returned value will | |
122 | * be same as {@code stringCharacterIndex}, but if there are CJK characters | |
123 | * the value will be different due to CJK characters taking up two columns | |
124 | * in width. If the character at the index in the string is a CJK character | |
125 | * itself, the returned value will be the index of the left-side of | |
126 | * character. | |
127 | * | |
128 | * @param s | |
129 | * String to translate the index from | |
130 | * @param stringCharacterIndex | |
131 | * Index within the string to get the terminal column index of | |
132 | * @return Index of the character inside the String at {@code | |
133 | * stringCharacterIndex} when it has been writted to a terminal | |
134 | * @throws StringIndexOutOfBoundsException | |
135 | * if the index given is outside the String length or negative | |
136 | */ | |
137 | public static int getColumnIndex(String s, int stringCharacterIndex) | |
138 | throws StringIndexOutOfBoundsException { | |
139 | int index = 0; | |
140 | for (int i = 0; i < stringCharacterIndex; i++) { | |
141 | if (isCharCJK(s.charAt(i))) { | |
142 | index++; | |
143 | } | |
144 | index++; | |
145 | } | |
146 | return index; | |
147 | } | |
148 | ||
149 | /** | |
150 | * This method does the reverse of getColumnIndex, given a String and | |
151 | * imagining it has been printed out to the top-left corner of a terminal, | |
152 | * in the column specified by {@code columnIndex}, what is the index of that | |
153 | * character in the string. If the string contains no CJK characters, this | |
154 | * will always be the same as {@code columnIndex}. If the index specified is | |
155 | * the right column of a CJK character, the index is the same as if the | |
156 | * column was the left column. So calling {@code | |
157 | * getStringCharacterIndex("英", 0)} and {@code getStringCharacterIndex("英", | |
158 | * 1)} will both return 0. | |
159 | * | |
160 | * @param s | |
161 | * String to translate the index to | |
162 | * @param columnIndex | |
163 | * Column index of the string written to a terminal | |
164 | * @return The index in the string of the character in terminal column | |
165 | * {@code columnIndex} | |
166 | */ | |
167 | public static int getStringCharacterIndex(String s, int columnIndex) { | |
168 | int index = 0; | |
169 | int counter = 0; | |
170 | while (counter < columnIndex) { | |
171 | if (isCharCJK(s.charAt(index++))) { | |
172 | counter++; | |
173 | if (counter == columnIndex) { | |
174 | return index - 1; | |
175 | } | |
176 | } | |
177 | counter++; | |
178 | } | |
179 | return index; | |
180 | } | |
181 | ||
182 | /** | |
183 | * Given a string that may or may not contain CJK characters, returns the | |
184 | * substring which will fit inside <code>availableColumnSpace</code> | |
185 | * columns. This method does not handle special cases like tab or new-line. | |
186 | * <p> | |
187 | * Calling this method is the same as calling {@code fitString(string, 0, | |
188 | * availableColumnSpace)}. | |
189 | * | |
190 | * @param string | |
191 | * The string to fit inside the availableColumnSpace | |
192 | * @param availableColumnSpace | |
193 | * Number of columns to fit the string inside | |
194 | * @return The whole or part of the input string which will fit inside the | |
195 | * supplied availableColumnSpace | |
196 | */ | |
197 | public static String fitString(String string, int availableColumnSpace) { | |
198 | return fitString(string, 0, availableColumnSpace); | |
199 | } | |
200 | ||
201 | /** | |
202 | * Given a string that may or may not contain CJK characters, returns the | |
203 | * substring which will fit inside <code>availableColumnSpace</code> | |
204 | * columns. This method does not handle special cases like tab or new-line. | |
205 | * <p> | |
206 | * This overload has a {@code fromColumn} parameter that specified where | |
207 | * inside the string to start fitting. Please notice that {@code fromColumn} | |
208 | * is not a character index inside the string, but a column index as if the | |
209 | * string has been printed from the left-most side of the terminal. So if | |
210 | * the string is "日本語", fromColumn set to 1 will not starting counting from | |
211 | * the second character ("本") in the string but from the CJK filler | |
212 | * character belonging to "日". If you want to count from a particular | |
213 | * character index inside the string, please pass in a substring and use | |
214 | * fromColumn set to 0. | |
215 | * | |
216 | * @param string | |
217 | * The string to fit inside the availableColumnSpace | |
218 | * @param fromColumn | |
219 | * From what column of the input string to start fitting (see | |
220 | * description above!) | |
221 | * @param availableColumnSpace | |
222 | * Number of columns to fit the string inside | |
223 | * @return The whole or part of the input string which will fit inside the | |
224 | * supplied availableColumnSpace | |
225 | */ | |
226 | public static String fitString(String string, int fromColumn, | |
227 | int availableColumnSpace) { | |
228 | if (availableColumnSpace <= 0) { | |
229 | return ""; | |
230 | } | |
231 | ||
232 | StringBuilder bob = new StringBuilder(); | |
233 | int column = 0; | |
234 | int index = 0; | |
235 | while (index < string.length() && column < fromColumn) { | |
236 | char c = string.charAt(index++); | |
237 | column += TerminalTextUtils.isCharCJK(c) ? 2 : 1; | |
238 | } | |
239 | if (column > fromColumn) { | |
240 | bob.append(" "); | |
241 | availableColumnSpace--; | |
242 | } | |
243 | ||
244 | while (availableColumnSpace > 0 && index < string.length()) { | |
245 | char c = string.charAt(index++); | |
246 | availableColumnSpace -= TerminalTextUtils.isCharCJK(c) ? 2 : 1; | |
247 | if (availableColumnSpace < 0) { | |
248 | bob.append(' '); | |
249 | } else { | |
250 | bob.append(c); | |
251 | } | |
252 | } | |
253 | return bob.toString(); | |
254 | } | |
255 | ||
256 | /** | |
257 | * This method will calculate word wrappings given a number of lines of text | |
258 | * and how wide the text can be printed. The result is a list of new rows | |
259 | * where word-wrapping was applied. | |
260 | * | |
261 | * @param maxWidth | |
262 | * Maximum number of columns that can be used before | |
263 | * word-wrapping is applied | |
264 | * @param lines | |
265 | * Input text | |
266 | * @return The input text word-wrapped at {@code maxWidth}; this may contain | |
267 | * more rows than the input text | |
268 | */ | |
269 | public static List<String> getWordWrappedText(int maxWidth, String... lines) { | |
270 | List<String> result = new ArrayList<String>(); | |
271 | LinkedList<String> linesToBeWrapped = new LinkedList<String>(Arrays | |
272 | .asList(lines)); | |
273 | while (!linesToBeWrapped.isEmpty()) { | |
274 | String row = linesToBeWrapped.removeFirst(); | |
275 | int rowWidth = getColumnWidth(row); | |
276 | if (rowWidth <= maxWidth) { | |
277 | result.add(row); | |
278 | } else { | |
279 | // Now search in reverse and find the first possible line-break | |
280 | int characterIndex = getStringCharacterIndex(row, maxWidth); | |
281 | while (!Character.isSpaceChar(row.charAt(characterIndex)) | |
282 | && !isCharCJK(row.charAt(characterIndex)) | |
283 | && characterIndex > 0) { | |
284 | characterIndex--; | |
285 | } | |
286 | ||
287 | if (characterIndex == 0) { | |
288 | // Failed! There was no 'nice' place to cut so just cut it | |
289 | // at maxWidth | |
290 | result.add(row.substring(0, maxWidth)); | |
291 | linesToBeWrapped.addFirst(row.substring(maxWidth)); | |
292 | } else { | |
293 | // Ok, split the row, add it to the result and continue | |
294 | // processing the second half on a new line | |
295 | result.add(row.substring(0, characterIndex)); | |
296 | int spaceCharsToSkip = 0; | |
297 | while (characterIndex < row.length() | |
298 | && Character | |
299 | .isSpaceChar(row.charAt(characterIndex))) { | |
300 | characterIndex++; | |
301 | } | |
302 | ; | |
303 | linesToBeWrapped.addFirst(row.substring(characterIndex)); | |
304 | } | |
305 | } | |
306 | } | |
307 | return result; | |
308 | } | |
309 | } |