lib/strutil.h

   1 #ifndef MC_STRUTIL_H
   2 #define MC_STRUTIL_H
   3
   4 #include "lib/global.h"         /* include glib.h */
   5
   6 #include <sys/types.h>
   7 #include <inttypes.h>
   8 #include <string.h>
   9 #ifdef HAVE_ASSERT_H
  10 #include <assert.h>             /* assert() */
  11 #endif
  12
  13 /* Header file for strutil.c, strutilascii.c, strutil8bit.c, strutilutf8.c.
  14  * There are two sort of functions:
  15  * 1. functions for working with growing strings and conversion strings between
  16  *    different encodings.
  17  *    (implemented directly in strutil.c)
  18  * 2. functions, that hide differences between encodings derived from ASCII.
  19  *    (implemented separately in strutilascii.c, strutil8bit.c, strutilutf8.c)
  20  * documentation is made for UTF-8 version of functions.
  21  */
  22
  23 /* invalid strings
  24  * function, that works with invalid strings are marked with "I"
  25  * in documentation
  26  * invalid bytes of string are handled as one byte characters with width 1, they
  27  * are displayed as questionmarks, I-maked comparing functions try to keep
  28  * the original value of these bytes.
  29  */
  30
  31 /* combining characters
  32  * displaynig: all handled as zero with characters, expect combing character
  33  * at the begin of string, this character has with one (space add before),
  34  * so str_term_width is not good for computing width of singles characters
  35  * (never return zero, expect emtpy string)
  36  * for compatibility are strings composed before displaynig
  37  * comparing: comparing decompose all string before comparing, n-compare
  38  * functions do not work as is usual, because same strings do not have to be
  39  * same length in UTF-8. So they return 0 if one string is prefix of the other
  40  * one.
  41  * str_prefix is used to determine, how many characters from one string are
  42  * prefix in second string. However, str_prefix return number of characters in
  43  * decompose form. (used in do_search (screen.c))
  44  */
  45
  46 /*** typedefs(not structures) and defined constants **********************************************/
  47
  48 #define IS_FIT(x) ((x) & 0x0010)
  49 #define MAKE_FIT(x) ((x) | 0x0010)
  50 #define HIDE_FIT(x) ((x) & 0x000f)
  51
  52 #define INVALID_CONV ((GIConv) (-1))
  53
  54 /*** enums ***************************************************************************************/
  55
  56 /* results of conversion function
  57  */
  58 typedef enum
  59 {
  60     /* success means, that convertion has been finished successully
  61      */
  62     ESTR_SUCCESS = 0,
  63     /* problem means, that not every characters was successfully converted (They are
  64      * replaced with questionmark). So is impossible convert string back.
  65      */
  66     ESTR_PROBLEM = 1,
  67     /* failure means, that conversion is not possible (example: wrong encoding
  68      * of input string)
  69      */
  70     ESTR_FAILURE = 2
  71 } estr_t;
  72
  73 /* alignment strings on terminal
  74  */
  75 typedef enum
  76 {
  77     J_LEFT = 0x01,
  78     J_RIGHT = 0x02,
  79     J_CENTER = 0x03,
  80     /* if there is enough space for string on terminal,
  81      * string is centered otherwise is aligned to left */
  82     J_CENTER_LEFT = 0x04,
  83     /* fit alignment, if string is to long, is truncated with '~' */
  84     J_LEFT_FIT = 0x11,
  85     J_RIGHT_FIT = 0x12,
  86     J_CENTER_FIT = 0x13,
  87     J_CENTER_LEFT_FIT = 0x14
  88 } align_crt_t;
  89
  90 /* string-to-integer parsing results
  91  */
  92 typedef enum
  93 {
  94     LONGINT_OK = 0,
  95
  96     /* These two values can be ORed together, to indicate that both errors occurred. */
  97     LONGINT_OVERFLOW = 1,
  98     LONGINT_INVALID_SUFFIX_CHAR = 2,
  99
 100     LONGINT_INVALID_SUFFIX_CHAR_WITH_OVERFLOW = (LONGINT_INVALID_SUFFIX_CHAR | LONGINT_OVERFLOW),
 101     LONGINT_INVALID = 4
 102 } strtol_error_t;
 103
 104 /*** structures declarations (and typedefs of structures)*****************************************/
 105
 106 /* all functions in str_class must be defined for every encoding */
 107 struct str_class
 108 {
 109     gchar *(*conv_gerror_message) (GError * error, const char *def_msg);
 110       /*I*/ estr_t (*vfs_convert_to) (GIConv coder, const char *string, int size, GString * buffer);
 111       /*I*/ void (*insert_replace_char) (GString * buffer);
 112     int (*is_valid_string) (const char *);
 113       /*I*/ int (*is_valid_char) (const char *, size_t);
 114       /*I*/ void (*cnext_char) (const char **);
 115     void (*cprev_char) (const char **);
 116     void (*cnext_char_safe) (const char **);
 117       /*I*/ void (*cprev_char_safe) (const char **);
 118       /*I*/ int (*cnext_noncomb_char) (const char **text);
 119       /*I*/ int (*cprev_noncomb_char) (const char **text, const char *begin);
 120       /*I*/ int (*char_isspace) (const char *);
 121       /*I*/ int (*char_ispunct) (const char *);
 122       /*I*/ int (*char_isalnum) (const char *);
 123       /*I*/ int (*char_isdigit) (const char *);
 124       /*I*/ int (*char_isprint) (const char *);
 125       /*I*/ gboolean (*char_iscombiningmark) (const char *);
 126       /*I*/ int (*length) (const char *);
 127       /*I*/ int (*length2) (const char *, int);
 128       /*I*/ int (*length_noncomb) (const char *);
 129       /*I*/ int (*char_toupper) (const char *, char **, size_t *);
 130     int (*char_tolower) (const char *, char **, size_t *);
 131     void (*fix_string) (char *);
 132       /*I*/ const char *(*term_form) (const char *);
 133       /*I*/ const char *(*fit_to_term) (const char *, int, align_crt_t);
 134       /*I*/ const char *(*term_trim) (const char *text, int width);
 135       /*I*/ const char *(*term_substring) (const char *, int, int);
 136       /*I*/ int (*term_width1) (const char *);
 137       /*I*/ int (*term_width2) (const char *, size_t);
 138       /*I*/ int (*term_char_width) (const char *);
 139       /*I*/ const char *(*trunc) (const char *, int);
 140       /*I*/ int (*offset_to_pos) (const char *, size_t);
 141       /*I*/ int (*column_to_pos) (const char *, size_t);
 142       /*I*/ char *(*create_search_needle) (const char *, int);
 143     void (*release_search_needle) (char *, int);
 144     const char *(*search_first) (const char *, const char *, int);
 145     const char *(*search_last) (const char *, const char *, int);
 146     int (*compare) (const char *, const char *);
 147       /*I*/ int (*ncompare) (const char *, const char *);
 148       /*I*/ int (*casecmp) (const char *, const char *);
 149       /*I*/ int (*ncasecmp) (const char *, const char *);
 150       /*I*/ int (*prefix) (const char *, const char *);
 151       /*I*/ int (*caseprefix) (const char *, const char *);
 152       /*I*/ char *(*create_key) (const char *text, int case_sen);
 153       /*I*/ char *(*create_key_for_filename) (const char *text, int case_sen);
 154       /*I*/ int (*key_collate) (const char *t1, const char *t2, int case_sen);
 155       /*I*/ void (*release_key) (char *key, int case_sen);
 156   /*I*/};
 157
 158 /*** global variables defined in .c file *********************************************************/
 159
 160 /* standard convertors */
 161 extern GIConv str_cnv_to_term;
 162 extern GIConv str_cnv_from_term;
 163 /* from terminal encoding to terminal encoding */
 164 extern GIConv str_cnv_not_convert;
 165
 166 /*** declarations of public functions ************************************************************/
 167
 168 struct str_class str_utf8_init (void);
 169 struct str_class str_8bit_init (void);
 170 struct str_class str_ascii_init (void);
 171
 172 /* create convertor from "from_enc" to terminal encoding
 173  * if "from_enc" is not supported return INVALID_CONV
 174  */
 175 GIConv str_crt_conv_from (const char *);
 176
 177 /* create convertor from terminal encoding to "to_enc"
 178  * if "to_enc" is not supported return INVALID_CONV
 179  */
 180 GIConv str_crt_conv_to (const char *);
 181
 182 /* close convertor, do not close str_cnv_to_term, str_cnv_from_term,
 183  * str_cnv_not_convert
 184  */
 185 void str_close_conv (GIConv);
 186
 187 /* return on of not used buffers (.used == 0) or create new
 188  * returned buffer has set .used to 1
 189  */
 190
 191 /* convert string using coder, result of conversion is appended at end of buffer
 192  * return ESTR_SUCCESS if there was no problem.
 193  * otherwise return  ESTR_PROBLEM or ESTR_FAILURE
 194  */
 195 estr_t str_convert (GIConv, const char *, GString *);
 196 estr_t str_nconvert (GIConv, const char *, int, GString *);
 197
 198 /* convert GError message (which in UTF-8) to terminal charset
 199  * def_char is used if result of error->str conversion if ESTR_FAILURE
 200  * return new allocated null-terminated string, which is need to be freed
 201  * I
 202  */
 203 gchar *str_conv_gerror_message (GError * error, const char *def_msg);
 204
 205 /* return only ESTR_SUCCESS or ESTR_FAILURE, because vfs must be able to convert
 206  * result to original string. (so no replace with questionmark)
 207  * if coder is str_cnv_from_term or str_cnv_not_convert, string is only copied,
 208  * so is possible to show file, that is not valid in terminal encoding
 209  */
 210 estr_t str_vfs_convert_from (GIConv, const char *, GString *);
 211
 212 /* if coder is str_cnv_to_term or str_cnv_not_convert, string is only copied,
 213  * does replace with questionmark
 214  * I
 215  */
 216 estr_t str_vfs_convert_to (GIConv, const char *, int, GString *);
 217
 218 /* printf function for str_buffer, append result of printf at the end of buffer
 219  */
 220 /* *INDENT-OFF* */
 221 void str_printf (GString * buffer, const char *format, ...) G_GNUC_PRINTF (2, 3);
 222 /* *INDENT-ON* */
 223
 224 /* add standard replacement character in terminal encoding
 225  */
 226 void str_insert_replace_char (GString *);
 227
 228 /* init strings and set terminal encoding,
 229  * if is termenc NULL, detect terminal encoding
 230  * create all str_cnv_* and set functions for terminal encoding
 231  */
 232 void str_init_strings (const char *termenc);
 233
 234 /* free all str_buffer and all str_cnv_*
 235  */
 236 void str_uninit_strings (void);
 237
 238 /* try convert characters in ch to output using conv
 239  * ch_size is size of ch, can by (size_t)(-1) (-1 only for ASCII
 240  *     compatible encoding, for other must be set)
 241  * return ESTR_SUCCESS if conversion was successfully,
 242  * ESTR_PROBLEM if ch contains only part of characters,
 243  * ESTR_FAILURE if conversion is not possible
 244  */
 245 estr_t str_translate_char (GIConv conv, const char *ch, size_t ch_size,
 246                            char *output, size_t out_size);
 247
 248 /* test, if text is valid in terminal encoding
 249  * I
 250  */
 251 int str_is_valid_string (const char *text);
 252
 253 /* test, if first char of ch is valid
 254  * size, how many bytes characters occupied, could be (size_t)(-1)
 255  * return 1 if it is valid, -1 if it is invalid or -2 if it is only part of
 256  * multibyte character
 257  * I
 258  */
 259 int str_is_valid_char (const char *ch, size_t size);
 260
 261 /* return next characters after text, do not call on the end of string
 262  */
 263 char *str_get_next_char (char *text);
 264 const char *str_cget_next_char (const char *text);
 265
 266 /* return previous characters before text, do not call on the start of strings
 267  */
 268 char *str_get_prev_char (char *text);
 269 const char *str_cget_prev_char (const char *text);
 270
 271 /* set text to next characters, do not call on the end of string
 272  */
 273 void str_next_char (char **text);
 274 void str_cnext_char (const char **text);
 275
 276 /* set text to previous characters, do not call on the start of strings
 277  */
 278 void str_prev_char (char **text);
 279 void str_cprev_char (const char **text);
 280
 281 /* return next characters after text, do not call on the end of string
 282  * works with invalid string
 283  * I
 284  */
 285 char *str_get_next_char_safe (char *text);
 286 const char *str_cget_next_char_safe (const char *text);
 287
 288 /* return previous characters before text, do not call on the start of strings
 289  * works with invalid string
 290  * I
 291  */
 292 char *str_get_prev_char_safe (char *text);
 293 const char *str_cget_prev_char_safe (const char *text);
 294
 295 /* set text to next characters, do not call on the end of string
 296  * works with invalid string
 297  * I
 298  */
 299 void str_next_char_safe (char **text);
 300 void str_cnext_char_safe (const char **text);
 301
 302 /* set text to previous characters, do not call on the start of strings
 303  * works with invalid string
 304  * I
 305  */
 306 void str_prev_char_safe (char **text);
 307 void str_cprev_char_safe (const char **text);
 308
 309 /* set text to next noncombining characters, check the end of text
 310  * return how many characters was skipped
 311  * works with invalid string
 312  * I
 313  */
 314 int str_next_noncomb_char (char **text);
 315 int str_cnext_noncomb_char (const char **text);
 316
 317 /* set text to previous noncombining characters, search stop at begin
 318  * return how many characters was skipped
 319  * works with invalid string
 320  * I
 321  */
 322 int str_prev_noncomb_char (char **text, const char *begin);
 323 int str_cprev_noncomb_char (const char **text, const char *begin);
 324
 325 /* if first characters in ch is space, tabulator  or new lines
 326  * I
 327  */
 328 int str_isspace (const char *ch);
 329
 330 /* if first characters in ch is punctuation or symbol
 331  * I
 332  */
 333 int str_ispunct (const char *ch);
 334
 335 /* if first characters in ch is alphanum
 336  * I
 337  */
 338 int str_isalnum (const char *ch);
 339
 340 /* if first characters in ch is digit
 341  * I
 342  */
 343 int str_isdigit (const char *ch);
 344
 345 /* if first characters in ch is printable
 346  * I
 347  */
 348 int str_isprint (const char *ch);
 349
 350 /* if first characters in ch is a combining mark (only in utf-8)
 351  * combining makrs are assumed to be zero width
 352  * I
 353  */
 354 gboolean str_iscombiningmark (const char *ch);
 355
 356 /* write lower from of fisrt characters in ch into out
 357  * decrase remain by size of returned characters
 358  * if out is not big enough, do nothing
 359  */
 360 int str_toupper (const char *ch, char **out, size_t * remain);
 361
 362 /* write upper from of fisrt characters in ch into out
 363  * decrase remain by size of returned characters
 364  * if out is not big enough, do nothing
 365  */
 366 int str_tolower (const char *ch, char **out, size_t * remain);
 367
 368 /* return length of text in characters
 369  * I
 370  */
 371 int str_length (const char *text);
 372
 373 /* return length of text in characters, limit to size
 374  * I
 375  */
 376 int str_length2 (const char *text, int size);
 377
 378 /* return length of one char
 379  * I
 380  */
 381 int str_length_char (const char *);
 382
 383 /* return length of text in characters, count only noncombining characters
 384  * I
 385  */
 386 int str_length_noncomb (const char *text);
 387
 388 /* replace all invalid characters in text with questionmark
 389  * after return, text is valid string in terminal encoding
 390  * I
 391  */
 392 void str_fix_string (char *text);
 393
 394 /* replace all invalid characters in text with questionmark
 395  * replace all unprintable characters with '.'
 396  * return static allocated string, "text" is not changed
 397  * returned string do not need to be freed
 398  * I
 399  */
 400 const char *str_term_form (const char *text);
 401
 402 /* like str_term_form, but text can be alignment to width
 403  * alignment is specified in just_mode (J_LEFT, J_LEFT_FIT, ...)
 404  * result is completed with spaces to width
 405  * I
 406  */
 407 const char *str_fit_to_term (const char *text, int width, align_crt_t just_mode);
 408
 409 /* like str_term_form, but when text is wider than width, three dots are
 410  * inserted at begin and result is completed with suffix of text
 411  * no additional spaces are inserted
 412  * I
 413  */
 414 const char *str_term_trim (const char *text, int width);
 415
 416
 417 /* like str_term_form, but return only specified substring
 418  * start - column (position) on terminal, where substring begin
 419  * result is completed with spaces to width
 420  * I
 421  */
 422 const char *str_term_substring (const char *text, int start, int width);
 423
 424 /* return width, that will be text occupied on terminal
 425  * I
 426  */
 427 int str_term_width1 (const char *text);
 428
 429 /* return width, that will be text occupied on terminal
 430  * text is limited by length in characters
 431  * I
 432  */
 433 int str_term_width2 (const char *text, size_t length);
 434
 435 /* return width, that will be character occupied on terminal
 436  * combining characters are always zero width
 437  * I
 438  */
 439 int str_term_char_width (const char *text);
 440
 441 /* convert position in characters to position in bytes
 442  * I
 443  */
 444 int str_offset_to_pos (const char *text, size_t length);
 445
 446 /* convert position on terminal to position in characters
 447  * I
 448  */
 449 int str_column_to_pos (const char *text, size_t pos);
 450
 451 /* like str_fit_to_term width just_mode = J_LEFT_FIT,
 452  * but do not insert additional spaces
 453  * I
 454  */
 455 const char *str_trunc (const char *text, int width);
 456
 457 /* create needle, that will be searched in str_search_fist/last,
 458  * so needle can be reused
 459  * in UTF-8 return normalized form of needle
 460  */
 461 char *str_create_search_needle (const char *needle, int case_sen);
 462
 463 /* free needle returned by str_create_search_needle
 464  */
 465 void str_release_search_needle (char *needle, int case_sen);
 466
 467 /* search for first occurrence of search in text
 468  */
 469 const char *str_search_first (const char *text, const char *needle, int case_sen);
 470
 471 /* search for last occurrence of search in text
 472  */
 473 const char *str_search_last (const char *text, const char *needle, int case_sen);
 474
 475 /* case sensitive compare two strings
 476  * I
 477  */
 478 int str_compare (const char *t1, const char *t2);
 479
 480 /* case sensitive compare two strings
 481  * if one string is prefix of the other string, return 0
 482  * I
 483  */
 484 int str_ncompare (const char *t1, const char *t2);
 485
 486 /* case insensitive compare two strings
 487  * I
 488  */
 489 int str_casecmp (const char *t1, const char *t2);
 490
 491 /* case insensitive compare two strings
 492  * if one string is prefix of the other string, return 0
 493  * I
 494  */
 495 int str_ncasecmp (const char *t1, const char *t2);
 496
 497 /* return, how many bytes are are same from start in text and prefix
 498  * both strings are decomposed before comparing and return value is counted
 499  * in decomposed form, too. calling with prefix, prefix, you get size in bytes
 500  * of prefix in decomposed form,
 501  * I
 502  */
 503 int str_prefix (const char *text, const char *prefix);
 504
 505 /* case insensitive version of str_prefix
 506  * I
 507  */
 508 int str_caseprefix (const char *text, const char *prefix);
 509
 510 /* create a key that is used by str_key_collate
 511  * I
 512  */
 513 char *str_create_key (const char *text, int case_sen);
 514
 515 /* create a key that is used by str_key_collate
 516  * should aware dot '.' in text
 517  * I
 518  */
 519 char *str_create_key_for_filename (const char *text, int case_sen);
 520
 521 /* compare two string using LC_COLLATE, if is possible
 522  * if case_sen is set, comparing is case sensitive,
 523  * case_sen must be same for str_create_key, str_key_collate and str_release_key
 524  * I
 525  */
 526 int str_key_collate (const char *t1, const char *t2, int case_sen);
 527
 528 /* release_key created by str_create_key, only rigth way to release key
 529  * I
 530  */
 531 void str_release_key (char *key, int case_sen);
 532
 533 /* return TRUE if codeset_name is utf8 or utf-8
 534  * I
 535  */
 536 gboolean str_isutf8 (const char *codeset_name);
 537
 538 const char *str_detect_termencoding (void);
 539
 540 int str_verscmp (const char *s1, const char *s2);
 541
 542 /* return how many lines and columns will text occupy on terminal
 543  */
 544 void str_msg_term_size (const char *text, int *lines, int *columns);
 545
 546 /**
 547  * skip first needle's in haystack
 548  *
 549  * @param haystack pointer to string
 550  * @param needle pointer to string
 551  * @param skip_count skip first bytes
 552  *
 553  * @return pointer to skip_count+1 needle (or NULL if not found).
 554  */
 555
 556 char *strrstr_skip_count (const char *haystack, const char *needle, size_t skip_count);
 557
 558 char *str_replace_all (const char *haystack, const char *needle, const char *replacement);
 559
 560 strtol_error_t xstrtoumax (const char *s, char **ptr, int base, uintmax_t * val,
 561                            const char *valid_suffixes);
 562 uintmax_t parse_integer (const char *str, gboolean * invalid);
 563
 564 /* --------------------------------------------------------------------------------------------- */
 565 /*** inline functions ****************************************************************************/
 566 /* --------------------------------------------------------------------------------------------- */
 567
 568 static inline void
 569 str_replace (char *s, char from, char to)
 570 {
 571     for (; *s != '\0'; s++)
 572     {
 573         if (*s == from)
 574             *s = to;
 575     }
 576 }
 577
 578 /* --------------------------------------------------------------------------------------------- */
 579 /*
 580  * strcpy is unsafe on overlapping memory areas, so define memmove-alike
 581  * string function.
 582  * Have sense only when:
 583  *  * dest <= src
 584  *   AND
 585  *  * dest and str are pointers to one object (as Roland Illig pointed).
 586  *
 587  * We can't use str*cpy funs here:
 588  * http://kerneltrap.org/mailarchive/openbsd-misc/2008/5/27/1951294
 589  *
 590  * @param dest pointer to string
 591  * @param src pointer to string
 592  *
 593  * @return newly allocated string
 594  *
 595  */
 596
 597 static inline char *
 598 str_move (char *dest, const char *src)
 599 {
 600     size_t n;
 601
 602 #ifdef HAVE_ASSERT_H
 603     assert (dest <= src);
 604 #endif
 605
 606     n = strlen (src) + 1;       /* + '\0' */
 607
 608     return (char *) memmove (dest, src, n);
 609 }
 610
 611 /* --------------------------------------------------------------------------------------------- */
 612
 613 #endif /* MC_STRUTIL_H */