po/ru.po: fixed plural forms.
[midnight-commander.git] / lib / strutil.h
blob35a26f921b1ad3fe70d59e47ce3f62b3ff294121
1 #ifndef MC_STRUTIL_H
2 #define MC_STRUTIL_H
4 #include "lib/global.h" /* include glib.h */
6 #include <sys/types.h>
7 #include <string.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.
20 /* invalid strings
21 * function, that works with invalid strings are marked with "I"
22 * in documentation
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
37 * one.
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
55 typedef enum
57 /* success means, that convertion has been finished successully
59 ESTR_SUCCESS = 0,
60 /* problem means, that not every characters was successfully converted (They are
61 * replaced with questionmark). So is impossible convert string back.
63 ESTR_PROBLEM = 1,
64 /* failure means, that conversion is not possible (example: wrong encoding
65 * of input string)
67 ESTR_FAILURE = 2
68 } estr_t;
70 /* alignment strings on terminal
72 typedef enum
74 J_LEFT = 0x01,
75 J_RIGHT = 0x02,
76 J_CENTER = 0x03,
77 /* if there is enough space for string on terminal,
78 * string is centered otherwise is aligned to left */
79 J_CENTER_LEFT = 0x04,
80 /* fit alignment, if string is to long, is truncated with '~' */
81 J_LEFT_FIT = 0x11,
82 J_RIGHT_FIT = 0x12,
83 J_CENTER_FIT = 0x13,
84 J_CENTER_LEFT_FIT = 0x14
85 } align_crt_t;
87 /*** structures declarations (and typedefs of structures)*****************************************/
89 /* all functions in str_class must be defined for every encoding */
90 struct str_class
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*/ const char *(*term_substring) (const char *, int, int);
119 /*I*/ int (*term_width1) (const char *);
120 /*I*/ int (*term_width2) (const char *, size_t);
121 /*I*/ int (*term_char_width) (const char *);
122 /*I*/ const char *(*trunc) (const char *, int);
123 /*I*/ int (*offset_to_pos) (const char *, size_t);
124 /*I*/ int (*column_to_pos) (const char *, size_t);
125 /*I*/ char *(*create_search_needle) (const char *, int);
126 void (*release_search_needle) (char *, int);
127 const char *(*search_first) (const char *, const char *, int);
128 const char *(*search_last) (const char *, const char *, int);
129 int (*compare) (const char *, const char *);
130 /*I*/ int (*ncompare) (const char *, const char *);
131 /*I*/ int (*casecmp) (const char *, const char *);
132 /*I*/ int (*ncasecmp) (const char *, const char *);
133 /*I*/ int (*prefix) (const char *, const char *);
134 /*I*/ int (*caseprefix) (const char *, const char *);
135 /*I*/ char *(*create_key) (const char *text, int case_sen);
136 /*I*/ char *(*create_key_for_filename) (const char *text, int case_sen);
137 /*I*/ int (*key_collate) (const char *t1, const char *t2, int case_sen);
138 /*I*/ void (*release_key) (char *key, int case_sen);
139 /*I*/};
141 /*** global variables defined in .c file *********************************************************/
143 /* standard convertors */
144 extern GIConv str_cnv_to_term;
145 extern GIConv str_cnv_from_term;
146 /* from terminal encoding to terminal encoding */
147 extern GIConv str_cnv_not_convert;
149 /*** declarations of public functions ************************************************************/
151 struct str_class str_utf8_init (void);
152 struct str_class str_8bit_init (void);
153 struct str_class str_ascii_init (void);
155 /* create convertor from "from_enc" to terminal encoding
156 * if "from_enc" is not supported return INVALID_CONV
158 GIConv str_crt_conv_from (const char *);
160 /* create convertor from terminal encoding to "to_enc"
161 * if "to_enc" is not supported return INVALID_CONV
163 GIConv str_crt_conv_to (const char *);
165 /* close convertor, do not close str_cnv_to_term, str_cnv_from_term,
166 * str_cnv_not_convert
168 void str_close_conv (GIConv);
170 /* return on of not used buffers (.used == 0) or create new
171 * returned buffer has set .used to 1
174 /* convert string using coder, result of conversion is appended at end of buffer
175 * return ESTR_SUCCESS if there was no problem.
176 * otherwise return ESTR_PROBLEM or ESTR_FAILURE
178 estr_t str_convert (GIConv, const char *, GString *);
179 estr_t str_nconvert (GIConv, const char *, int, GString *);
181 /* convert GError message (which in UTF-8) to terminal charset
182 * def_char is used if result of error->str conversion if ESTR_FAILURE
183 * return new allocated null-terminated string, which is need to be freed
186 gchar *str_conv_gerror_message (GError * error, const char *def_msg);
188 /* return only ESTR_SUCCESS or ESTR_FAILURE, because vfs must be able to convert
189 * result to original string. (so no replace with questionmark)
190 * if coder is str_cnv_from_term or str_cnv_not_convert, string is only copied,
191 * so is possible to show file, that is not valid in terminal encoding
193 estr_t str_vfs_convert_from (GIConv, const char *, GString *);
195 /* if coder is str_cnv_to_term or str_cnv_not_convert, string is only copied,
196 * does replace with questionmark
199 estr_t str_vfs_convert_to (GIConv, const char *, int, GString *);
201 /* printf functin for str_buffer, append result of printf at the end of buffer
203 void str_printf (GString *, const char *, ...);
205 /* add standard replacement character in terminal encoding
207 void str_insert_replace_char (GString *);
209 /* init strings and set terminal encoding,
210 * if is termenc NULL, detect terminal encoding
211 * create all str_cnv_* and set functions for terminal encoding
213 void str_init_strings (const char *termenc);
215 /* free all str_buffer and all str_cnv_*
217 void str_uninit_strings (void);
219 /* try convert characters in ch to output using conv
220 * ch_size is size of ch, can by (size_t)(-1) (-1 only for ASCII
221 * compatible encoding, for other must be set)
222 * return ESTR_SUCCESS if conversion was successfully,
223 * ESTR_PROBLEM if ch contains only part of characters,
224 * ESTR_FAILURE if conversion is not possible
226 estr_t str_translate_char (GIConv conv, const char *ch, size_t ch_size,
227 char *output, size_t out_size);
229 /* test, if text is valid in terminal encoding
232 int str_is_valid_string (const char *text);
234 /* test, if first char of ch is valid
235 * size, how many bytes characters occupied, could be (size_t)(-1)
236 * return 1 if it is valid, -1 if it is invalid or -2 if it is only part of
237 * multibyte character
240 int str_is_valid_char (const char *ch, size_t size);
242 /* return next characters after text, do not call on the end of string
244 char *str_get_next_char (char *text);
245 const char *str_cget_next_char (const char *text);
247 /* return previous characters before text, do not call on the start of strings
249 char *str_get_prev_char (char *text);
250 const char *str_cget_prev_char (const char *text);
252 /* set text to next characters, do not call on the end of string
254 void str_next_char (char **text);
255 void str_cnext_char (const char **text);
257 /* set text to previous characters, do not call on the start of strings
259 void str_prev_char (char **text);
260 void str_cprev_char (const char **text);
262 /* return next characters after text, do not call on the end of string
263 * works with invalid string
266 char *str_get_next_char_safe (char *text);
267 const char *str_cget_next_char_safe (const char *text);
269 /* return previous characters before text, do not call on the start of strings
270 * works with invalid string
273 char *str_get_prev_char_safe (char *text);
274 const char *str_cget_prev_char_safe (const char *text);
276 /* set text to next characters, do not call on the end of string
277 * works with invalid string
280 void str_next_char_safe (char **text);
281 void str_cnext_char_safe (const char **text);
283 /* set text to previous characters, do not call on the start of strings
284 * works with invalid string
287 void str_prev_char_safe (char **text);
288 void str_cprev_char_safe (const char **text);
290 /* set text to next noncombining characters, check the end of text
291 * return how many characters was skipped
292 * works with invalid string
295 int str_next_noncomb_char (char **text);
296 int str_cnext_noncomb_char (const char **text);
298 /* set text to previous noncombining characters, search stop at begin
299 * return how many characters was skipped
300 * works with invalid string
303 int str_prev_noncomb_char (char **text, const char *begin);
304 int str_cprev_noncomb_char (const char **text, const char *begin);
306 /* if first characters in ch is space, tabulator or new lines
309 int str_isspace (const char *ch);
311 /* if first characters in ch is punctuation or symbol
314 int str_ispunct (const char *ch);
316 /* if first characters in ch is alphanum
319 int str_isalnum (const char *ch);
321 /* if first characters in ch is digit
324 int str_isdigit (const char *ch);
326 /* if first characters in ch is printable
329 int str_isprint (const char *ch);
331 /* if first characters in ch is a combining mark (only in utf-8)
332 * combining makrs are assumed to be zero width
335 int str_iscombiningmark (const char *ch);
337 /* write lower from of fisrt characters in ch into out
338 * decrase remain by size of returned characters
339 * if out is not big enough, do nothing
341 int str_toupper (const char *ch, char **out, size_t * remain);
343 /* write upper from of fisrt characters in ch into out
344 * decrase remain by size of returned characters
345 * if out is not big enough, do nothing
347 int str_tolower (const char *ch, char **out, size_t * remain);
349 /* return length of text in characters
352 int str_length (const char *text);
354 /* return length of text in characters, limit to size
357 int str_length2 (const char *text, int size);
359 /* return length of one char
362 int str_length_char (const char *);
364 /* return length of text in characters, count only noncombining characters
367 int str_length_noncomb (const char *text);
369 /* replace all invalid characters in text with questionmark
370 * after return, text is valid string in terminal encoding
373 void str_fix_string (char *text);
375 /* replace all invalid characters in text with questionmark
376 * replace all unprintable characters with '.'
377 * return static allocated string, "text" is not changed
378 * returned string do not need to be freed
381 const char *str_term_form (const char *text);
383 /* like str_term_form, but text can be alignment to width
384 * alignment is specified in just_mode (J_LEFT, J_LEFT_FIT, ...)
385 * result is completed with spaces to width
388 const char *str_fit_to_term (const char *text, int width, align_crt_t just_mode);
390 /* like str_term_form, but when text is wider than width, three dots are
391 * inserted at begin and result is completed with suffix of text
392 * no additional spaces are inserted
395 const char *str_term_trim (const char *text, int width);
398 /* like str_term_form, but return only specified substring
399 * start - column (position) on terminal, where substring begin
400 * result is completed with spaces to width
403 const char *str_term_substring (const char *text, int start, int width);
405 /* return width, that will be text occupied on terminal
408 int str_term_width1 (const char *text);
410 /* return width, that will be text occupied on terminal
411 * text is limited by length in characters
414 int str_term_width2 (const char *text, size_t length);
416 /* return width, that will be character occupied on terminal
417 * combining characters are always zero width
420 int str_term_char_width (const char *text);
422 /* convert position in characters to position in bytes
425 int str_offset_to_pos (const char *text, size_t length);
427 /* convert position on terminal to position in characters
430 int str_column_to_pos (const char *text, size_t pos);
432 /* like str_fit_to_term width just_mode = J_LEFT_FIT,
433 * but do not insert additional spaces
436 const char *str_trunc (const char *text, int width);
438 /* create needle, that will be searched in str_search_fist/last,
439 * so needle can be reused
440 * in UTF-8 return normalized form of needle
442 char *str_create_search_needle (const char *needle, int case_sen);
444 /* free needle returned by str_create_search_needle
446 void str_release_search_needle (char *needle, int case_sen);
448 /* search for first occurrence of search in text
450 const char *str_search_first (const char *text, const char *needle, int case_sen);
452 /* search for last occurrence of search in text
454 const char *str_search_last (const char *text, const char *needle, int case_sen);
456 /* case sensitive compare two strings
459 int str_compare (const char *t1, const char *t2);
461 /* case sensitive compare two strings
462 * if one string is prefix of the other string, return 0
465 int str_ncompare (const char *t1, const char *t2);
467 /* case insensitive compare two strings
470 int str_casecmp (const char *t1, const char *t2);
472 /* case insensitive compare two strings
473 * if one string is prefix of the other string, return 0
476 int str_ncasecmp (const char *t1, const char *t2);
478 /* return, how many bytes are are same from start in text and prefix
479 * both strings are decomposed befor comapring and return value is counted
480 * in decomposed form, too. caling with prefix, prefix, you get size in bytes
481 * of prefix in decomposed form,
484 int str_prefix (const char *text, const char *prefix);
486 /* case insensitive version of str_prefix
489 int str_caseprefix (const char *text, const char *prefix);
491 /* create a key that is used by str_key_collate
494 char *str_create_key (const char *text, int case_sen);
496 /* create a key that is used by str_key_collate
497 * should aware dot '.' in text
500 char *str_create_key_for_filename (const char *text, int case_sen);
502 /* compare two string using LC_COLLATE, if is possible
503 * if case_sen is set, comparing is case sensitive,
504 * case_sen must be same for str_create_key, str_key_collate and str_release_key
507 int str_key_collate (const char *t1, const char *t2, int case_sen);
509 /* release_key created by str_create_key, only rigth way to release key
512 void str_release_key (char *key, int case_sen);
514 /* return 1 if codeset_name is utf8 or utf-8
517 int str_isutf8 (const char *codeset_name);
519 const char *str_detect_termencoding (void);
521 int str_verscmp (const char *s1, const char *s2);
523 /* return how many lines and columns will text occupy on terminal
525 void str_msg_term_size (const char *text, int *lines, int *columns);
527 /*** inline functions ****************************************************************************/
529 static inline void
530 str_replace (char *s, char from, char to)
532 for (; *s != '\0'; s++)
534 if (*s == from)
535 *s = to;
540 * strcpy is unsafe on overlapping memory areas, so define memmove-alike
541 * string function.
542 * Have sense only when:
543 * * dest <= src
544 * AND
545 * * dest and str are pointers to one object (as Roland Illig pointed).
547 * We can't use str*cpy funs here:
548 * http://kerneltrap.org/mailarchive/openbsd-misc/2008/5/27/1951294
550 static inline char *
551 str_move (char *dest, const char *src)
553 size_t n;
555 assert (dest <= src);
557 n = strlen (src) + 1; /* + '\0' */
559 return (char *) memmove (dest, src, n);
562 #endif /* MC_STRUTIL_H */