4 #include "lib/global.h" /* include glib.h */
8 #include <assert.h> /* assert() */
10 /* Header file for strutil.c, strutilascii.c, strutil8bit.c, strutilutf8.c.
11 * There are two sort of functions:
12 * 1. functions for working with growing strings and conversion strings between
13 * different encodings.
14 * (implemented directly in strutil.c)
15 * 2. functions, that hide differences between encodings derived from ASCII.
16 * (implemented separately in strutilascii.c, strutil8bit.c, strutilutf8.c)
17 * documentation is made for UTF-8 version of functions.
21 * function, that works with invalid strings are marked with "I"
23 * invalid bytes of string are handled as one byte characters with width 1, they
24 * are displayed as questionmarks, I-maked comparing functions try to keep
25 * the original value of these bytes.
28 /* combining characters
29 * displaynig: all handled as zero with characters, expect combing character
30 * at the begin of string, this character has with one (space add before),
31 * so str_term_width is not good for computing width of singles characters
32 * (never return zero, expect emtpy string)
33 * for compatibility are strings composed before displaynig
34 * comparing: comparing decompose all string before comparing, n-compare
35 * functions do not work as is usual, because same strings do not have to be
36 * same length in UTF-8. So they return 0 if one string is prefix of the other
38 * str_prefix is used to determine, how many characters from one string are
39 * prefix in second string. However, str_prefix return number of characters in
40 * decompose form. (used in do_search (screen.c))
43 /*** typedefs(not structures) and defined constants **********************************************/
45 #define IS_FIT(x) ((x) & 0x0010)
46 #define MAKE_FIT(x) ((x) | 0x0010)
47 #define HIDE_FIT(x) ((x) & 0x000f)
49 #define INVALID_CONV ((GIConv) (-1))
51 /*** enums ***************************************************************************************/
53 /* results of conversion function
57 /* success means, that convertion has been finished successully
60 /* problem means, that not every characters was successfully converted (They are
61 * replaced with questionmark). So is impossible convert string back.
64 /* failure means, that conversion is not possible (example: wrong encoding
70 /* alignment strings on terminal
77 /* if there is enough space for string on terminal,
78 * string is centered otherwise is aligned to left */
80 /* fit alignment, if string is to long, is truncated with '~' */
84 J_CENTER_LEFT_FIT
= 0x14
87 /*** structures declarations (and typedefs of structures)*****************************************/
89 /* all functions in str_class must be defined for every encoding */
92 gchar
*(*conv_gerror_message
) (GError
* error
, const char *def_msg
);
93 /*I*/ estr_t (*vfs_convert_to
) (GIConv coder
, const char *string
, int size
, GString
* buffer
);
94 /*I*/ void (*insert_replace_char
) (GString
* buffer
);
95 int (*is_valid_string
) (const char *);
96 /*I*/ int (*is_valid_char
) (const char *, size_t);
97 /*I*/ void (*cnext_char
) (const char **);
98 void (*cprev_char
) (const char **);
99 void (*cnext_char_safe
) (const char **);
100 /*I*/ void (*cprev_char_safe
) (const char **);
101 /*I*/ int (*cnext_noncomb_char
) (const char **text
);
102 /*I*/ int (*cprev_noncomb_char
) (const char **text
, const char *begin
);
103 /*I*/ int (*isspace
) (const char *);
104 /*I*/ int (*ispunct
) (const char *);
105 /*I*/ int (*isalnum
) (const char *);
106 /*I*/ int (*isdigit
) (const char *);
107 /*I*/ int (*isprint
) (const char *);
108 /*I*/ int (*iscombiningmark
) (const char *);
109 /*I*/ int (*length
) (const char *);
110 /*I*/ int (*length2
) (const char *, int);
111 /*I*/ int (*length_noncomb
) (const char *);
112 /*I*/ int (*toupper
) (const char *, char **, size_t *);
113 int (*tolower
) (const char *, char **, size_t *);
114 void (*fix_string
) (char *);
115 /*I*/ const char *(*term_form
) (const char *);
116 /*I*/ const char *(*fit_to_term
) (const char *, int, align_crt_t
);
117 /*I*/ const char *(*term_trim
) (const char *text
, int width
);
118 /*I*/ void (*msg_term_size
) (const char *, int *, int *);
119 /*I*/ const char *(*term_substring
) (const char *, int, int);
120 /*I*/ int (*term_width1
) (const char *);
121 /*I*/ int (*term_width2
) (const char *, size_t);
122 /*I*/ int (*term_char_width
) (const char *);
123 /*I*/ const char *(*trunc
) (const char *, int);
124 /*I*/ int (*offset_to_pos
) (const char *, size_t);
125 /*I*/ int (*column_to_pos
) (const char *, size_t);
126 /*I*/ char *(*create_search_needle
) (const char *, int);
127 void (*release_search_needle
) (char *, int);
128 const char *(*search_first
) (const char *, const char *, int);
129 const char *(*search_last
) (const char *, const char *, int);
130 int (*compare
) (const char *, const char *);
131 /*I*/ int (*ncompare
) (const char *, const char *);
132 /*I*/ int (*casecmp
) (const char *, const char *);
133 /*I*/ int (*ncasecmp
) (const char *, const char *);
134 /*I*/ int (*prefix
) (const char *, const char *);
135 /*I*/ int (*caseprefix
) (const char *, const char *);
136 /*I*/ char *(*create_key
) (const char *text
, int case_sen
);
137 /*I*/ char *(*create_key_for_filename
) (const char *text
, int case_sen
);
138 /*I*/ int (*key_collate
) (const char *t1
, const char *t2
, int case_sen
);
139 /*I*/ void (*release_key
) (char *key
, int case_sen
);
142 /*** global variables defined in .c file *********************************************************/
144 /* standard convertors */
145 extern GIConv str_cnv_to_term
;
146 extern GIConv str_cnv_from_term
;
147 /* from terminal encoding to terminal encoding */
148 extern GIConv str_cnv_not_convert
;
150 /*** declarations of public functions ************************************************************/
152 struct str_class
str_utf8_init (void);
153 struct str_class
str_8bit_init (void);
154 struct str_class
str_ascii_init (void);
156 /* create convertor from "from_enc" to terminal encoding
157 * if "from_enc" is not supported return INVALID_CONV
159 GIConv
str_crt_conv_from (const char *);
161 /* create convertor from terminal encoding to "to_enc"
162 * if "to_enc" is not supported return INVALID_CONV
164 GIConv
str_crt_conv_to (const char *);
166 /* close convertor, do not close str_cnv_to_term, str_cnv_from_term,
167 * str_cnv_not_convert
169 void str_close_conv (GIConv
);
171 /* return on of not used buffers (.used == 0) or create new
172 * returned buffer has set .used to 1
175 /* convert string using coder, result of conversion is appended at end of buffer
176 * return ESTR_SUCCESS if there was no problem.
177 * otherwise return ESTR_PROBLEM or ESTR_FAILURE
179 estr_t
str_convert (GIConv
, const char *, GString
*);
180 estr_t
str_nconvert (GIConv
, const char *, int, GString
*);
182 /* convert GError message (which in UTF-8) to terminal charset
183 * def_char is used if result of error->str conversion if ESTR_FAILURE
184 * return new allocated null-terminated string, which is need to be freed
187 gchar
*str_conv_gerror_message (GError
* error
, const char *def_msg
);
189 /* return only ESTR_SUCCESS or ESTR_FAILURE, because vfs must be able to convert
190 * result to original string. (so no replace with questionmark)
191 * if coder is str_cnv_from_term or str_cnv_not_convert, string is only copied,
192 * so is possible to show file, that is not valid in terminal encoding
194 estr_t
str_vfs_convert_from (GIConv
, const char *, GString
*);
196 /* if coder is str_cnv_to_term or str_cnv_not_convert, string is only copied,
197 * does replace with questionmark
200 estr_t
str_vfs_convert_to (GIConv
, const char *, int, GString
*);
202 /* printf functin for str_buffer, append result of printf at the end of buffer
204 void str_printf (GString
*, const char *, ...);
206 /* add standard replacement character in terminal encoding
208 void str_insert_replace_char (GString
*);
210 /* init strings and set terminal encoding,
211 * if is termenc NULL, detect terminal encoding
212 * create all str_cnv_* and set functions for terminal encoding
214 void str_init_strings (const char *termenc
);
216 /* free all str_buffer and all str_cnv_*
218 void str_uninit_strings (void);
220 /* try convert characters in ch to output using conv
221 * ch_size is size of ch, can by (size_t)(-1) (-1 only for ASCII
222 * compatible encoding, for other must be set)
223 * return ESTR_SUCCESS if conversion was successfully,
224 * ESTR_PROBLEM if ch contains only part of characters,
225 * ESTR_FAILURE if conversion is not possible
227 estr_t
str_translate_char (GIConv conv
, const char *ch
, size_t ch_size
,
228 char *output
, size_t out_size
);
230 /* test, if text is valid in terminal encoding
233 int str_is_valid_string (const char *text
);
235 /* test, if first char of ch is valid
236 * size, how many bytes characters occupied, could be (size_t)(-1)
237 * return 1 if it is valid, -1 if it is invalid or -2 if it is only part of
238 * multibyte character
241 int str_is_valid_char (const char *ch
, size_t size
);
243 /* return next characters after text, do not call on the end of string
245 char *str_get_next_char (char *text
);
246 const char *str_cget_next_char (const char *text
);
248 /* return previous characters before text, do not call on the start of strings
250 char *str_get_prev_char (char *text
);
251 const char *str_cget_prev_char (const char *text
);
253 /* set text to next characters, do not call on the end of string
255 void str_next_char (char **text
);
256 void str_cnext_char (const char **text
);
258 /* set text to previous characters, do not call on the start of strings
260 void str_prev_char (char **text
);
261 void str_cprev_char (const char **text
);
263 /* return next characters after text, do not call on the end of string
264 * works with invalid string
267 char *str_get_next_char_safe (char *text
);
268 const char *str_cget_next_char_safe (const char *text
);
270 /* return previous characters before text, do not call on the start of strings
271 * works with invalid string
274 char *str_get_prev_char_safe (char *text
);
275 const char *str_cget_prev_char_safe (const char *text
);
277 /* set text to next characters, do not call on the end of string
278 * works with invalid string
281 void str_next_char_safe (char **text
);
282 void str_cnext_char_safe (const char **text
);
284 /* set text to previous characters, do not call on the start of strings
285 * works with invalid string
288 void str_prev_char_safe (char **text
);
289 void str_cprev_char_safe (const char **text
);
291 /* set text to next noncombining characters, check the end of text
292 * return how many characters was skipped
293 * works with invalid string
296 int str_next_noncomb_char (char **text
);
297 int str_cnext_noncomb_char (const char **text
);
299 /* set text to previous noncombining characters, search stop at begin
300 * return how many characters was skipped
301 * works with invalid string
304 int str_prev_noncomb_char (char **text
, const char *begin
);
305 int str_cprev_noncomb_char (const char **text
, const char *begin
);
307 /* if first characters in ch is space, tabulator or new lines
310 int str_isspace (const char *ch
);
312 /* if first characters in ch is punctuation or symbol
315 int str_ispunct (const char *ch
);
317 /* if first characters in ch is alphanum
320 int str_isalnum (const char *ch
);
322 /* if first characters in ch is digit
325 int str_isdigit (const char *ch
);
327 /* if first characters in ch is printable
330 int str_isprint (const char *ch
);
332 /* if first characters in ch is a combining mark (only in utf-8)
333 * combining makrs are assumed to be zero width
336 int str_iscombiningmark (const char *ch
);
338 /* write lower from of fisrt characters in ch into out
339 * decrase remain by size of returned characters
340 * if out is not big enough, do nothing
342 int str_toupper (const char *ch
, char **out
, size_t * remain
);
344 /* write upper from of fisrt characters in ch into out
345 * decrase remain by size of returned characters
346 * if out is not big enough, do nothing
348 int str_tolower (const char *ch
, char **out
, size_t * remain
);
350 /* return length of text in characters
353 int str_length (const char *text
);
355 /* return length of text in characters, limit to size
358 int str_length2 (const char *text
, int size
);
360 /* return length of one char
363 int str_length_char (const char *);
365 /* return length of text in characters, count only noncombining characters
368 int str_length_noncomb (const char *text
);
370 /* replace all invalid characters in text with questionmark
371 * after return, text is valid string in terminal encoding
374 void str_fix_string (char *text
);
376 /* replace all invalid characters in text with questionmark
377 * replace all unprintable characters with '.'
378 * return static allocated string, "text" is not changed
379 * returned string do not need to be freed
382 const char *str_term_form (const char *text
);
384 /* like str_term_form, but text can be alignment to width
385 * alignment is specified in just_mode (J_LEFT, J_LEFT_FIT, ...)
386 * result is completed with spaces to width
389 const char *str_fit_to_term (const char *text
, int width
, align_crt_t just_mode
);
391 /* like str_term_form, but when text is wider than width, three dots are
392 * inserted at begin and result is completed with suffix of text
393 * no additional spaces are inserted
396 const char *str_term_trim (const char *text
, int width
);
398 /* return how many lines and columns will text occupy on terminal
401 void str_msg_term_size (const char *text
, int *lines
, int *columns
);
403 /* like str_term_form, but return only specified substring
404 * start - column (position) on terminal, where substring begin
405 * result is completed with spaces to width
408 const char *str_term_substring (const char *text
, int start
, int width
);
410 /* return width, that will be text occupied on terminal
413 int str_term_width1 (const char *text
);
415 /* return width, that will be text occupied on terminal
416 * text is limited by length in characters
419 int str_term_width2 (const char *text
, size_t length
);
421 /* return width, that will be character occupied on terminal
422 * combining characters are always zero width
425 int str_term_char_width (const char *text
);
427 /* convert position in characters to position in bytes
430 int str_offset_to_pos (const char *text
, size_t length
);
432 /* convert position on terminal to position in characters
435 int str_column_to_pos (const char *text
, size_t pos
);
437 /* like str_fit_to_term width just_mode = J_LEFT_FIT,
438 * but do not insert additional spaces
441 const char *str_trunc (const char *text
, int width
);
443 /* create needle, that will be searched in str_search_fist/last,
444 * so needle can be reused
445 * in UTF-8 return normalized form of needle
447 char *str_create_search_needle (const char *needle
, int case_sen
);
449 /* free needle returned by str_create_search_needle
451 void str_release_search_needle (char *needle
, int case_sen
);
453 /* search for first occurrence of search in text
455 const char *str_search_first (const char *text
, const char *needle
, int case_sen
);
457 /* search for last occurrence of search in text
459 const char *str_search_last (const char *text
, const char *needle
, int case_sen
);
461 /* case sensitive compare two strings
464 int str_compare (const char *t1
, const char *t2
);
466 /* case sensitive compare two strings
467 * if one string is prefix of the other string, return 0
470 int str_ncompare (const char *t1
, const char *t2
);
472 /* case insensitive compare two strings
475 int str_casecmp (const char *t1
, const char *t2
);
477 /* case insensitive compare two strings
478 * if one string is prefix of the other string, return 0
481 int str_ncasecmp (const char *t1
, const char *t2
);
483 /* return, how many bytes are are same from start in text and prefix
484 * both strings are decomposed befor comapring and return value is counted
485 * in decomposed form, too. caling with prefix, prefix, you get size in bytes
486 * of prefix in decomposed form,
489 int str_prefix (const char *text
, const char *prefix
);
491 /* case insensitive version of str_prefix
494 int str_caseprefix (const char *text
, const char *prefix
);
496 /* create a key that is used by str_key_collate
499 char *str_create_key (const char *text
, int case_sen
);
501 /* create a key that is used by str_key_collate
502 * should aware dot '.' in text
505 char *str_create_key_for_filename (const char *text
, int case_sen
);
507 /* compare two string using LC_COLLATE, if is possible
508 * if case_sen is set, comparing is case sensitive,
509 * case_sen must be same for str_create_key, str_key_collate and str_release_key
512 int str_key_collate (const char *t1
, const char *t2
, int case_sen
);
514 /* release_key created by str_create_key, only rigth way to release key
517 void str_release_key (char *key
, int case_sen
);
519 /* return 1 if codeset_name is utf8 or utf-8
522 int str_isutf8 (const char *codeset_name
);
524 const char *str_detect_termencoding (void);
526 int str_verscmp (const char *s1
, const char *s2
);
528 /*** inline functions ****************************************************************************/
531 str_replace (char *s
, char from
, char to
)
533 for (; *s
!= '\0'; s
++)
541 * strcpy is unsafe on overlapping memory areas, so define memmove-alike
543 * Have sense only when:
546 * * dest and str are pointers to one object (as Roland Illig pointed).
548 * We can't use str*cpy funs here:
549 * http://kerneltrap.org/mailarchive/openbsd-misc/2008/5/27/1951294
552 str_move (char *dest
, const char *src
)
556 assert (dest
<= src
);
558 n
= strlen (src
) + 1; /* + '\0' */
560 return (char *) memmove (dest
, src
, n
);
563 #endif /* MC_STRUTIL_H */