fort.h (34283B)
1 /* 2 libfort 3 4 MIT License 5 6 Copyright (c) 2017 - 2020 Seleznev Anton 7 8 Permission is hereby granted, free of charge, to any person obtaining a copy 9 of this software and associated documentation files (the "Software"), to deal 10 in the Software without restriction, including without limitation the rights 11 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 12 copies of the Software, and to permit persons to whom the Software is 13 furnished to do so, subject to the following conditions: 14 15 The above copyright notice and this permission notice shall be included in all 16 copies or substantial portions of the Software. 17 18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 21 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 23 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 24 SOFTWARE. 25 */ 26 27 /** 28 * @file fort.h 29 * @brief Main header file describing libfort API. 30 * 31 * This file contains declarations of all libfort functions and macro 32 * definitions. 33 */ 34 35 #ifndef LIBFORT_H 36 #define LIBFORT_H 37 38 #include <stddef.h> 39 #include <stdlib.h> 40 #include <stdint.h> 41 #include <limits.h> 42 43 /***************************************************************************** 44 * VERSION 45 *****************************************************************************/ 46 47 #define LIBFORT_MAJOR_VERSION 0 48 #define LIBFORT_MINOR_VERSION 5 49 #define LIBFORT_REVISION 0 50 #define LIBFORT_VERSION_STR "0.5.0" 51 52 53 /***************************************************************************** 54 * Configuration 55 *****************************************************************************/ 56 57 /** 58 * libfort configuration macros 59 * (to disable wchar_t/UTF-8 support this macros should be defined) 60 */ 61 /** #define FT_CONGIG_DISABLE_WCHAR */ 62 /** #define FT_CONGIG_DISABLE_UTF8 */ 63 64 #if !defined(FT_CONGIG_DISABLE_WCHAR) 65 #define FT_HAVE_WCHAR 66 #endif 67 68 #if !defined(FT_CONGIG_DISABLE_UTF8) 69 #define FT_HAVE_UTF8 70 #endif 71 72 73 /***************************************************************************** 74 * RETURN CODES 75 *****************************************************************************/ 76 77 /** 78 * Operation successfully ended. 79 */ 80 #define FT_SUCCESS 0 81 82 /** 83 * Memory allocation failed. 84 */ 85 #define FT_MEMORY_ERROR -1 86 87 /** 88 * Invalid argument. 89 */ 90 #define FT_EINVAL -2 91 92 /** 93 * Libfort internal logic error. 94 * 95 * Usually such errors mean that something is wrong in 96 * libfort internal logic and in most of cases cause of 97 * these errors is a library bug. 98 */ 99 #define FT_INTERN_ERROR -3 100 101 /** 102 * General error. 103 * 104 * Different errors that do not belong to the group of errors 105 * mentioned above. 106 */ 107 #define FT_GEN_ERROR -4 108 109 110 #define FT_IS_SUCCESS(arg) ((arg) >= 0) 111 #define FT_IS_ERROR(arg) ((arg) < 0) 112 113 114 115 116 /** 117 * @cond HELPER_MACROS 118 */ 119 120 /***************************************************************************** 121 * Determine compiler 122 *****************************************************************************/ 123 124 #if defined(__clang__) 125 #define FT_CLANG_COMPILER 126 #elif defined(__GNUC__) 127 #define FT_GCC_COMPILER 128 #elif defined(_MSC_VER) 129 #define FT_MICROSOFT_COMPILER 130 #else 131 #define FT_UNDEFINED_COMPILER 132 #endif 133 134 135 /***************************************************************************** 136 * Declare inline 137 *****************************************************************************/ 138 139 #if defined(__cplusplus) 140 #define FT_INLINE inline 141 #else 142 #define FT_INLINE __inline 143 #endif /* if defined(__cplusplus) */ 144 145 146 /***************************************************************************** 147 * C++ needs to know that types and declarations are C, not C++. 148 *****************************************************************************/ 149 150 #ifdef __cplusplus 151 # define FT_BEGIN_DECLS extern "C" { 152 # define FT_END_DECLS } 153 #else 154 # define FT_BEGIN_DECLS 155 # define FT_END_DECLS 156 #endif 157 158 159 /***************************************************************************** 160 * Helper macros 161 *****************************************************************************/ 162 163 #define FT_STR_2_CAT_(arg1, arg2) \ 164 arg1##arg2 165 #define FT_STR_2_CAT(arg1, arg2) \ 166 FT_STR_2_CAT_(arg1, arg2) 167 168 /** 169 * @interanl 170 */ 171 static FT_INLINE int ft_check_if_string_helper(const char *str) 172 { 173 (void)str; 174 return 0; 175 } 176 177 /** 178 * @interanl 179 */ 180 static FT_INLINE int ft_check_if_wstring_helper(const wchar_t *str) 181 { 182 (void)str; 183 return 0; 184 } 185 186 #define FT_NARGS_IMPL_(x1,x2,x3,x4,x5,x6,x7,x8,x9,x10,x11,x12,x13,x14,x15,N,...) N 187 #define FT_EXPAND_(x) x 188 #define FT_PP_NARG_(...) \ 189 FT_EXPAND_(FT_NARGS_IMPL_(__VA_ARGS__,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1,0)) 190 191 #define FT_CHECK_IF_STR_32(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_31(checker,__VA_ARGS__))) 192 #define FT_CHECK_IF_STR_31(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_30(checker,__VA_ARGS__))) 193 #define FT_CHECK_IF_STR_30(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_29(checker,__VA_ARGS__))) 194 #define FT_CHECK_IF_STR_29(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_28(checker,__VA_ARGS__))) 195 #define FT_CHECK_IF_STR_28(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_27(checker,__VA_ARGS__))) 196 #define FT_CHECK_IF_STR_27(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_26(checker,__VA_ARGS__))) 197 #define FT_CHECK_IF_STR_26(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_25(checker,__VA_ARGS__))) 198 #define FT_CHECK_IF_STR_25(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_24(checker,__VA_ARGS__))) 199 #define FT_CHECK_IF_STR_24(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_23(checker,__VA_ARGS__))) 200 #define FT_CHECK_IF_STR_23(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_22(checker,__VA_ARGS__))) 201 #define FT_CHECK_IF_STR_22(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_21(checker,__VA_ARGS__))) 202 #define FT_CHECK_IF_STR_21(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_20(checker,__VA_ARGS__))) 203 #define FT_CHECK_IF_STR_20(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_19(checker,__VA_ARGS__))) 204 #define FT_CHECK_IF_STR_19(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_18(checker,__VA_ARGS__))) 205 #define FT_CHECK_IF_STR_18(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_17(checker,__VA_ARGS__))) 206 #define FT_CHECK_IF_STR_17(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_16(checker,__VA_ARGS__))) 207 #define FT_CHECK_IF_STR_16(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_15(checker,__VA_ARGS__))) 208 #define FT_CHECK_IF_STR_15(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_14(checker,__VA_ARGS__))) 209 #define FT_CHECK_IF_STR_14(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_13(checker,__VA_ARGS__))) 210 #define FT_CHECK_IF_STR_13(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_12(checker,__VA_ARGS__))) 211 #define FT_CHECK_IF_STR_12(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_11(checker,__VA_ARGS__))) 212 #define FT_CHECK_IF_STR_11(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_10(checker,__VA_ARGS__))) 213 #define FT_CHECK_IF_STR_10(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_9(checker,__VA_ARGS__))) 214 #define FT_CHECK_IF_STR_9(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_8(checker,__VA_ARGS__))) 215 #define FT_CHECK_IF_STR_8(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_7(checker,__VA_ARGS__))) 216 #define FT_CHECK_IF_STR_7(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_6(checker,__VA_ARGS__))) 217 #define FT_CHECK_IF_STR_6(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_5(checker,__VA_ARGS__))) 218 #define FT_CHECK_IF_STR_5(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_4(checker,__VA_ARGS__))) 219 #define FT_CHECK_IF_STR_4(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_3(checker,__VA_ARGS__))) 220 #define FT_CHECK_IF_STR_3(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_2(checker,__VA_ARGS__))) 221 #define FT_CHECK_IF_STR_2(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_1(checker,__VA_ARGS__))) 222 #define FT_CHECK_IF_STR_1(checker,arg) (checker(arg)) 223 224 #define FT_CHECK_IF_ARGS_ARE_STRINGS__(checker,func, ...) \ 225 FT_EXPAND_(func(checker,__VA_ARGS__)) 226 #define FT_CHECK_IF_ARGS_ARE_STRINGS_(checker,basis, n, ...) \ 227 FT_CHECK_IF_ARGS_ARE_STRINGS__(checker,FT_STR_2_CAT_(basis, n), __VA_ARGS__) 228 #define FT_CHECK_IF_ARGS_ARE_STRINGS(...) \ 229 FT_CHECK_IF_ARGS_ARE_STRINGS_(ft_check_if_string_helper,FT_CHECK_IF_STR_,FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__) 230 231 #ifdef FT_HAVE_WCHAR 232 #define CHECK_IF_ARGS_ARE_WSTRINGS(...) \ 233 FT_CHECK_IF_ARGS_ARE_STRINGS_(ft_check_if_wstring_helper,FT_CHECK_IF_STR_,FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__) 234 #endif 235 236 /** 237 * @endcond 238 */ 239 240 241 /***************************************************************************** 242 * Attribute format for argument checking 243 *****************************************************************************/ 244 245 #if defined(FT_CLANG_COMPILER) || defined(FT_GCC_COMPILER) 246 #define FT_PRINTF_ATTRIBUTE_FORMAT(string_index, first_to_check) \ 247 __attribute__ ((format (printf, string_index, first_to_check))) 248 #else 249 #define FT_PRINTF_ATTRIBUTE_FORMAT(string_index, first_to_check) 250 #endif /* defined(FT_CLANG_COMPILER) || defined(FT_GCC_COMPILER) */ 251 252 253 /***************************************************************************** 254 * libfort API 255 *****************************************************************************/ 256 257 FT_BEGIN_DECLS 258 259 /** 260 * The main structure of libfort containing information about formatted table. 261 */ 262 struct ft_table; 263 264 /** 265 * The main structure of libfort containing information about formatted table. 266 * 267 * ft_table_t objects should be created by a call to ft_create_table and 268 * destroyed with ft_destroy_table. 269 */ 270 typedef struct ft_table ft_table_t; 271 272 /** 273 * Create formatted table. 274 * 275 * @return 276 * The pointer to the new allocated ft_table_t, on success. NULL on error. 277 */ 278 ft_table_t *ft_create_table(void); 279 280 /** 281 * Destroy formatted table. 282 * 283 * Destroy formatted table and free all resources allocated during table creation 284 * and work with it. 285 * 286 * @param table 287 * Pointer to formatted table previousley created with ft_create_table. If 288 * table is a null pointer, the function does nothing. 289 */ 290 void ft_destroy_table(ft_table_t *table); 291 292 /** 293 * Copy formatted table. 294 * 295 * @param table 296 * Pointer to formatted table previousley created with ft_create_table. If 297 * table is a null pointer, the function returns null. 298 * @return 299 * The pointer to the new allocated ft_table_t, on success. NULL on error. 300 */ 301 ft_table_t *ft_copy_table(ft_table_t *table); 302 303 /** 304 * Move current position to the first cell of the next line(row). 305 * 306 * @param table 307 * Pointer to formatted table. 308 * @return 309 * - 0: Success; data were written 310 * - (<0): In case of error. 311 * @note 312 * This function can fail only in case FT_STRATEGY_INSERT adding strategy 313 * was set for the table. 314 */ 315 int ft_ln(ft_table_t *table); 316 317 /** 318 * Get row number of the current cell. 319 * 320 * @param table 321 * Pointer to formatted table. 322 * @return 323 * Row number of the current cell. 324 */ 325 size_t ft_cur_row(const ft_table_t *table); 326 327 /** 328 * Get column number of the current cell. 329 * 330 * @param table 331 * Pointer to formatted table. 332 * @return 333 * Column number of the current cell. 334 */ 335 size_t ft_cur_col(const ft_table_t *table); 336 337 /** 338 * Set current cell position. 339 * 340 * Current cell - cell that will be edited with all modifiing functions 341 * (ft_printf, ft_write ...). 342 * 343 * @param table 344 * Pointer to formatted table. 345 * @param row 346 * New row number for the current cell. 347 * @param col 348 * New row number for the current cell. 349 */ 350 void ft_set_cur_cell(ft_table_t *table, size_t row, size_t col); 351 352 /** 353 * Check if table is empty. 354 * 355 * @param table 356 * Pointer to the table. 357 * @return 358 * 1 - table is empty 359 * 0 - some data has been inserted 360 */ 361 int ft_is_empty(const ft_table_t *table); 362 363 /** 364 * Get number of rows in the table. 365 * 366 * @param table 367 * Pointer to formatted table. 368 * @return 369 * Number of rows in the table. 370 */ 371 size_t ft_row_count(const ft_table_t *table); 372 373 /** 374 * Get number of columns in the table. 375 * 376 * @param table 377 * Pointer to formatted table. 378 * @return 379 * Number of columns in the table. 380 */ 381 size_t ft_col_count(const ft_table_t *table); 382 383 /** 384 * Erase range of cells. 385 * 386 * Range of cells is determined by 2 points (top-left and bottom-right) (both 387 * ends are included). 388 * 389 * @param table 390 * Pointer to formatted table. 391 * @param top_left_row 392 * Row number of the top left cell in the range. 393 * @param top_left_col 394 * Column number of the top left cell in the range. 395 * @param bottom_right_row 396 * Row number of the bottom right cell in the range. 397 * @param bottom_right_col 398 * Column number of the bottom right cell in the range. 399 * @return 400 * - 0 - Operation was successfully implemented 401 * - (<0): In case of error 402 */ 403 int ft_erase_range(ft_table_t *table, 404 size_t top_left_row, size_t top_left_col, 405 size_t bottom_right_row, size_t bottom_right_col); 406 407 #if defined(FT_CLANG_COMPILER) || defined(FT_GCC_COMPILER) 408 409 /** 410 * Write data formatted according to the format string to a variety of table 411 * cells. 412 * 413 * @param table 414 * Pointer to formatted table. 415 * @param fmt 416 * Pointer to a null-terminated multibyte string specifying how to interpret 417 * the data. The format string consists of ordinary characters (except % and |), 418 * which are copied unchanged into the output stream, and conversion 419 * specifications. Conversion specifications are the same as for standard 420 * printf function. Character '|' (which can be changed with 421 * {@link ft_set_default_printf_field_separator}) in the format string is treated as 422 * a cell separator. 423 * @param ... 424 * Arguments specifying data to print. Similarly to standard printf-like 425 * functions if any argument after default conversions is not the type 426 * expected by the corresponding conversion specifier, or if there are fewer 427 * arguments than required by format, the behavior is undefined. If there are 428 * more arguments than required by format, the extraneous arguments are 429 * evaluated and ignored. 430 * @return 431 * - Number of printed cells 432 * - (<0): In case of error 433 */ 434 int ft_printf(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3); 435 436 /** 437 * Write data formatted according to the format string to a variety of table 438 * cells and move current position to the first cell of the next line(row). 439 * 440 * @param table 441 * Pointer to formatted table. 442 * @param fmt 443 * Pointer to a null-terminated multibyte string specifying how to interpret 444 * the data. The format string consists of ordinary characters (except % and |), 445 * which are copied unchanged into the output stream, and conversion 446 * specifications. Conversion specifications are the same as for standard 447 * printf function. Character '|' (which can be changed with 448 * {@link ft_set_default_printf_field_separator}) in the format string is treated as 449 * a cell separator. 450 * @param ... 451 * Arguments specifying data to print. Similarly to standard printf-like 452 * functions if any argument after default conversions is not the type 453 * expected by the corresponding conversion specifier, or if there are fewer 454 * arguments than required by format, the behavior is undefined. If there are 455 * more arguments than required by format, the extraneous arguments are 456 * evaluated and ignored. 457 * @return 458 * - Number of printed cells. 459 * - (<0): In case of error. 460 */ 461 int ft_printf_ln(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3); 462 463 #else 464 465 /** 466 * @cond IGNORE_DOC 467 */ 468 469 int ft_printf_impl(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3); 470 int ft_printf_ln_impl(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3); 471 472 #define ft_printf(table, ...) \ 473 (( 0 ? fprintf(stderr, __VA_ARGS__) : 1), ft_printf_impl(table, __VA_ARGS__)) 474 #define ft_printf_ln(table, ...) \ 475 (( 0 ? fprintf(stderr, __VA_ARGS__) : 1), ft_printf_ln_impl(table, __VA_ARGS__)) 476 477 /** 478 * @endcond 479 */ 480 #endif 481 482 /** 483 * Set field separator for {@link ft_printf}, {@link ft_printf_ln} 484 * (default separator is '|'). 485 * 486 * @param separator 487 * New separator. 488 */ 489 void ft_set_default_printf_field_separator(char separator); 490 491 492 /** 493 * Write strings to the table. 494 * 495 * Write specified strings to the same number of consecutive cells in the 496 * current row. 497 * 498 * @param table 499 * Pointer to formatted table. 500 * @param ... 501 * Strings to write. 502 * @return 503 * - 0: Success; data were written 504 * - (<0): In case of error 505 */ 506 #define ft_write(table, ...)\ 507 (0 ? FT_CHECK_IF_ARGS_ARE_STRINGS(__VA_ARGS__) : ft_nwrite(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)) 508 509 /** 510 * Write strings to the table and go to the next line. 511 * 512 * Write specified strings to the same number of consecutive cells in the 513 * current row and move current position to the first cell of the next 514 * line(row). 515 * 516 * @param table 517 * Pointer to formatted table. 518 * @param ... 519 * Strings to write. 520 * @return 521 * - 0: Success; data were written 522 * - (<0): In case of error 523 */ 524 #define ft_write_ln(table, ...)\ 525 (0 ? FT_CHECK_IF_ARGS_ARE_STRINGS(__VA_ARGS__) : ft_nwrite_ln(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)) 526 527 /** 528 * Write specified number of strings to the table. 529 * 530 * Write specified number of strings to the same number of consecutive cells in 531 * the current row. 532 * 533 * @note In most cases it is more preferable to use MACRO @ref ft_write instead 534 * of @ref ft_nwrite, which is more safe (@ref ft_write automatically counts the 535 * number of string arguments and at compile check that all passed arguments are 536 * strings). 537 * 538 * @param table 539 * Pointer to formatted table. 540 * @param count 541 * Number of strings to write. 542 * @param cell_content 543 * First string to write. 544 * @param ... 545 * Other strings to write. 546 * @return 547 * - 0: Success; data were written 548 * - (<0): In case of error 549 */ 550 int ft_nwrite(ft_table_t *table, size_t count, const char *cell_content, ...); 551 552 /** 553 * Write specified number of strings to the table and go to the next line. 554 * 555 * Write specified number of strings to the same number of consecutive cells 556 * in the current row and move current position to the first cell of the next 557 * line(row). 558 * 559 * @note In most cases it is more preferable to use MACRO @ref ft_write instead 560 * of @ref ft_nwrite, which is more safe (@ref ft_write automatically counts the 561 * number of string arguments and at compile check that all passed arguments are 562 * strings). 563 * 564 * @param table 565 * Pointer to formatted table. 566 * @param count 567 * Number of strings to write. 568 * @param cell_content 569 * First string to write. 570 * @param ... 571 * Other strings to write. 572 * @return 573 * - 0: Success; data were written 574 * - (<0): In case of error 575 */ 576 int ft_nwrite_ln(ft_table_t *table, size_t count, const char *cell_content, ...); 577 578 579 580 /** 581 * Write strings from the array to the table. 582 * 583 * Write specified number of strings from the array to the same number of 584 * consecutive cells in the current row. 585 * 586 * @param table 587 * Pointer to formatted table. 588 * @param cols 589 * Number of elements in row_cells. 590 * @param row_cells 591 * Array of strings to write. 592 * @return 593 * - 0: Success; data were written 594 * - (<0): In case of error 595 */ 596 int ft_row_write(ft_table_t *table, size_t cols, const char *row_cells[]); 597 598 /** 599 * Write strings from the array to the table and go to the next line. 600 * 601 * Write specified number of strings from the array to the same number of 602 * consecutive cells in the current row and move current position to the first 603 * cell of the next line(row). 604 * 605 * @param table 606 * Pointer to formatted table. 607 * @param cols 608 * Number of elements in row_cells. 609 * @param row_cells 610 * Array of strings to write. 611 * @return 612 * - 0: Success; data were written 613 * - (<0): In case of error 614 */ 615 int ft_row_write_ln(ft_table_t *table, size_t cols, const char *row_cells[]); 616 617 618 /** 619 * Write strings from the 2D array to the table. 620 * 621 * Write specified number of strings from the 2D array to the formatted table. 622 * 623 * @param table 624 * Pointer to formatted table. 625 * @param rows 626 * Number of rows in the 2D array. 627 * @param cols 628 * Number of columns in the 2D array. 629 * @param table_cells 630 * 2D array of strings to write. 631 * @return 632 * - 0: Success; data were written 633 * - (<0): In case of error 634 */ 635 int ft_table_write(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]); 636 637 /** 638 * Write strings from the 2D array to the table and go to the next line. 639 * 640 * Write specified number of strings from the 2D array to the formatted table 641 * and move current position to the first cell of the next line(row). 642 * 643 * @param table 644 * Pointer to formatted table. 645 * @param rows 646 * Number of rows in the 2D array. 647 * @param cols 648 * Number of columns in the 2D array. 649 * @param table_cells 650 * 2D array of strings to write. 651 * @return 652 * - 0: Success; data were written 653 * - (<0): In case of error 654 */ 655 int ft_table_write_ln(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]); 656 657 658 /** 659 * Add separator after the current row. 660 * 661 * @param table 662 * Formatted table. 663 * @return 664 * - 0: Success; separator was added. 665 * - (<0): In case of error 666 */ 667 int ft_add_separator(ft_table_t *table); 668 669 670 /** 671 * Convert table to string representation. 672 * 673 * ft_table_t has ownership of the returned pointer. So there is no need to 674 * free it. To take ownership user should explicitly copy the returned 675 * string with strdup or similar functions. 676 * 677 * Returned pointer may be later invalidated by: 678 * - Calling ft_destroy_table; 679 * - Other invocations of ft_to_string. 680 * 681 * @param table 682 * Formatted table. 683 * @return 684 * - The pointer to the string representation of formatted table, on success. 685 * - NULL on error. 686 */ 687 const char *ft_to_string(const ft_table_t *table); 688 689 690 691 692 693 694 695 /** 696 * Structure describing border appearance. 697 */ 698 struct ft_border_chars { 699 const char *top_border_ch; 700 const char *separator_ch; 701 const char *bottom_border_ch; 702 const char *side_border_ch; 703 const char *out_intersect_ch; 704 const char *in_intersect_ch; 705 }; 706 707 /** 708 * Structure describing border style. 709 */ 710 struct ft_border_style { 711 struct ft_border_chars border_chs; 712 struct ft_border_chars header_border_chs; 713 const char *hor_separator_char; 714 }; 715 716 /** 717 * @defgroup BasicStyles 718 * @name Built-in table border styles. 719 * @note Built-in border styles (FT_BASIC_STYLE, FT_BASIC2_STYLE ...) can be 720 * used as arguments for @ref ft_set_border_style and 721 * @ref ft_set_default_border_style, but their fields shouldn't be accessed 722 * directly because implementation doesn't guarantee that these objects are 723 * properly initialized. 724 * @{ 725 */ 726 extern const struct ft_border_style *const FT_BASIC_STYLE; 727 extern const struct ft_border_style *const FT_BASIC2_STYLE; 728 extern const struct ft_border_style *const FT_SIMPLE_STYLE; 729 extern const struct ft_border_style *const FT_PLAIN_STYLE; 730 extern const struct ft_border_style *const FT_DOT_STYLE; 731 extern const struct ft_border_style *const FT_EMPTY_STYLE; 732 extern const struct ft_border_style *const FT_EMPTY2_STYLE; 733 extern const struct ft_border_style *const FT_SOLID_STYLE; 734 extern const struct ft_border_style *const FT_SOLID_ROUND_STYLE; 735 extern const struct ft_border_style *const FT_NICE_STYLE; 736 extern const struct ft_border_style *const FT_DOUBLE_STYLE; 737 extern const struct ft_border_style *const FT_DOUBLE2_STYLE; 738 extern const struct ft_border_style *const FT_BOLD_STYLE; 739 extern const struct ft_border_style *const FT_BOLD2_STYLE; 740 extern const struct ft_border_style *const FT_FRAME_STYLE; 741 /** @} */ 742 743 744 745 /** 746 * Set default border style for all new formatted tables. 747 * 748 * @param style 749 * Pointer to border style. 750 * @return 751 * - 0: Success; default border style was changed. 752 * - (<0): In case of error 753 */ 754 int ft_set_default_border_style(const struct ft_border_style *style); 755 756 /** 757 * Set border style for the table. 758 * 759 * @param table 760 * A pointer to the ft_table_t structure. 761 * @param style 762 * Pointer to border style. 763 * @return 764 * - 0: Success; table border style was changed. 765 * - (<0): In case of error 766 */ 767 int ft_set_border_style(ft_table_t *table, const struct ft_border_style *style); 768 769 770 771 /** 772 * @name Special macros to define cell position (row and column). 773 * @{ 774 */ 775 #define FT_ANY_COLUMN (UINT_MAX) /**< Any column (can be used to refer to all cells in a row)*/ 776 #define FT_CUR_COLUMN (UINT_MAX - 1) /**< Current column */ 777 #define FT_ANY_ROW (UINT_MAX) /**< Any row (can be used to refer to all cells in a column)*/ 778 #define FT_CUR_ROW (UINT_MAX - 1) /**< Current row */ 779 /** @} */ 780 781 #define FT_MAX_ROW_INDEX (UINT_MAX - 2) 782 #define FT_MAX_COL_INDEX (UINT_MAX - 2) 783 784 785 /** 786 * @name Cell properties identifiers. 787 * @{ 788 */ 789 #define FT_CPROP_MIN_WIDTH (0x01U << 0) /**< Minimum width */ 790 #define FT_CPROP_TEXT_ALIGN (0x01U << 1) /**< Text alignment */ 791 #define FT_CPROP_TOP_PADDING (0x01U << 2) /**< Top padding for cell content */ 792 #define FT_CPROP_BOTTOM_PADDING (0x01U << 3) /**< Bottom padding for cell content */ 793 #define FT_CPROP_LEFT_PADDING (0x01U << 4) /**< Left padding for cell content */ 794 #define FT_CPROP_RIGHT_PADDING (0x01U << 5) /**< Right padding for cell content */ 795 #define FT_CPROP_EMPTY_STR_HEIGHT (0x01U << 6) /**< Height of empty cell */ 796 #define FT_CPROP_ROW_TYPE (0x01U << 7) /**< Row type */ 797 #define FT_CPROP_CONT_FG_COLOR (0x01U << 8) /**< Cell content foreground text color */ 798 #define FT_CPROP_CELL_BG_COLOR (0x01U << 9) /**< Cell background color */ 799 #define FT_CPROP_CONT_BG_COLOR (0x01U << 10) /**< Cell content background color */ 800 #define FT_CPROP_CELL_TEXT_STYLE (0x01U << 11) /**< Cell text style */ 801 #define FT_CPROP_CONT_TEXT_STYLE (0x01U << 12) /**< Cell content text style */ 802 #define FT_CPROP_CELL_BG_RGBCOLOR (0x01U << 13) /**< Cell background color */ 803 /** @} */ 804 805 806 /** 807 * Colors. 808 */ 809 enum ft_color { 810 FT_COLOR_DEFAULT = 0, /**< Default color */ 811 FT_COLOR_BLACK = 1, /**< Black color*/ 812 FT_COLOR_RED = 2, /**< Red color */ 813 FT_COLOR_GREEN = 3, /**< Green color */ 814 FT_COLOR_YELLOW = 4, /**< Yellow color */ 815 FT_COLOR_BLUE = 5, /**< Blue color */ 816 FT_COLOR_MAGENTA = 6, /**< Magenta color */ 817 FT_COLOR_CYAN = 7, /**< Cyan color */ 818 FT_COLOR_LIGHT_GRAY = 8, /**< Light gray color */ 819 FT_COLOR_DARK_GRAY = 9, /**< Dark gray color */ 820 FT_COLOR_LIGHT_RED = 10, /**< Light red color */ 821 FT_COLOR_LIGHT_GREEN = 11, /**< Light green color */ 822 FT_COLOR_LIGHT_YELLOW = 12, /**< Light yellow color */ 823 FT_COLOR_LIGHT_BLUE = 13, /**< Light blue color */ 824 FT_COLOR_LIGHT_MAGENTA = 14, /**< Light magenta color */ 825 FT_COLOR_LIGHT_CYAN = 15, /**< Light cyan color */ 826 FT_COLOR_LIGHT_WHYTE = 16 /**< Light whyte color */ 827 }; 828 829 /** 830 * Text styles. 831 */ 832 enum ft_text_style { 833 FT_TSTYLE_DEFAULT = (1U << 0), /**< Default style */ 834 FT_TSTYLE_BOLD = (1U << 1), /**< Bold */ 835 FT_TSTYLE_DIM = (1U << 2), /**< Dim */ 836 FT_TSTYLE_ITALIC = (1U << 3), /**< Italic */ 837 FT_TSTYLE_UNDERLINED = (1U << 4), /**< Underlined */ 838 FT_TSTYLE_BLINK = (1U << 5), /**< Blink */ 839 FT_TSTYLE_INVERTED = (1U << 6), /**< Reverse (invert the foreground and background colors) */ 840 FT_TSTYLE_HIDDEN = (1U << 7) /**< Hidden (useful for passwords) */ 841 }; 842 843 844 /** 845 * Alignment of cell content. 846 */ 847 enum ft_text_alignment { 848 FT_ALIGNED_LEFT = 0, /**< Align left */ 849 FT_ALIGNED_CENTER, /**< Align center */ 850 FT_ALIGNED_RIGHT /**< Align right */ 851 }; 852 853 /** 854 * Type of table row. Determines appearance of row. 855 */ 856 enum ft_row_type { 857 FT_ROW_COMMON = 0, /**< Common row */ 858 FT_ROW_HEADER /**< Header row */ 859 }; 860 861 /** 862 * Set default cell property for all new formatted tables. 863 * 864 * @param property 865 * Cell property identifier. 866 * @param value 867 * Cell property value. 868 * @return 869 * - 0: Success; default cell property was changed. 870 * - (<0): In case of error 871 */ 872 int ft_set_default_cell_prop(uint32_t property, int value); 873 874 /** 875 * Set property for the specified cell of the table. 876 * 877 * @param table 878 * A pointer to the ft_table_t structure. 879 * @param row 880 * Cell row. 881 * @param col 882 * Cell column. 883 * @param property 884 * Cell property identifier. 885 * @param value 886 * Cell property value. 887 * @return 888 * - 0: Success; cell property was changed. 889 * - (<0): In case of error 890 */ 891 int ft_set_cell_prop(ft_table_t *table, size_t row, size_t col, uint32_t property, int value); 892 893 894 /** 895 * @name Table properties identifiers. 896 * @{ 897 */ 898 #define FT_TPROP_LEFT_MARGIN (0x01U << 0) 899 #define FT_TPROP_TOP_MARGIN (0x01U << 1) 900 #define FT_TPROP_RIGHT_MARGIN (0x01U << 2) 901 #define FT_TPROP_BOTTOM_MARGIN (0x01U << 3) 902 #define FT_TPROP_ADDING_STRATEGY (0x01U << 4) 903 /** @} */ 904 905 /** 906 * Adding strategy. 907 * 908 * Determines what happens with old content if current cell is not empty after 909 * adding data to it. Default strategy is FT_STRATEGY_REPLACE. 910 */ 911 enum ft_adding_strategy { 912 FT_STRATEGY_REPLACE = 0, /**< Replace old content. */ 913 FT_STRATEGY_INSERT /**< Insert new conten. Old content is shifted. */ 914 }; 915 916 917 /** 918 * Set default table property. 919 * 920 * @param property 921 * Table property identifier. 922 * @param value 923 * Table property value. 924 * @return 925 * - 0: Success; default table property was changed. 926 * - (<0): In case of error 927 */ 928 int ft_set_default_tbl_prop(uint32_t property, int value); 929 930 /** 931 * Set table property. 932 * 933 * @param table 934 * A pointer to the ft_table_t structure. 935 * @param property 936 * Table property identifier. 937 * @param value 938 * Table property value. 939 * @return 940 * - 0: Success; default table property was changed. 941 * - (<0): In case of error 942 */ 943 int ft_set_tbl_prop(ft_table_t *table, uint32_t property, int value); 944 945 946 /** 947 * Set column span for the specified cell of the table. 948 * 949 * @param table 950 * A pointer to the ft_table_t structure. 951 * @param row 952 * Cell row. 953 * @param col 954 * Cell column. 955 * @param hor_span 956 * Column span. 957 * @return 958 * - 0: Success; cell span was changed. 959 * - (<0): In case of error 960 */ 961 int ft_set_cell_span(ft_table_t *table, size_t row, size_t col, size_t hor_span); 962 963 964 /** 965 * Set functions for memory allocation and deallocation to be used instead of 966 * standard ones. 967 * 968 * @param f_malloc 969 * Pointer to a function for memory allocation that should be used instead of 970 * malloc. 971 * @param f_free 972 * Pointer to a function for memory deallocation that should be used instead 973 * of free. 974 * @note 975 * To return memory allocation/deallocation functions to their standard values 976 * set f_malloc and f_free to NULL. 977 */ 978 void ft_set_memory_funcs(void *(*f_malloc)(size_t size), void (*f_free)(void *ptr)); 979 980 981 /** 982 * Return string describing the `error_code`. 983 * 984 * @param error_code 985 * Error code returned by the library. 986 * @return 987 * String describing the error. 988 */ 989 const char *ft_strerror(int error_code); 990 991 992 993 #ifdef FT_HAVE_WCHAR 994 995 996 int ft_wprintf(ft_table_t *table, const wchar_t *fmt, ...); 997 int ft_wprintf_ln(ft_table_t *table, const wchar_t *fmt, ...); 998 999 1000 #define ft_wwrite(table, ...)\ 1001 (0 ? CHECK_IF_ARGS_ARE_WSTRINGS(__VA_ARGS__) : ft_nwwrite(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)) 1002 #define ft_wwrite_ln(table, ...)\ 1003 (0 ? CHECK_IF_ARGS_ARE_WSTRINGS(__VA_ARGS__) : ft_nwwrite_ln(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)) 1004 int ft_nwwrite(ft_table_t *table, size_t n, const wchar_t *cell_content, ...); 1005 int ft_nwwrite_ln(ft_table_t *table, size_t n, const wchar_t *cell_content, ...); 1006 1007 int ft_row_wwrite(ft_table_t *table, size_t cols, const wchar_t *row_cells[]); 1008 int ft_row_wwrite_ln(ft_table_t *table, size_t cols, const wchar_t *row_cells[]); 1009 1010 int ft_table_wwrite(ft_table_t *table, size_t rows, size_t cols, const wchar_t *table_cells[]); 1011 int ft_table_wwrite_ln(ft_table_t *table, size_t rows, size_t cols, const wchar_t *table_cells[]); 1012 1013 const wchar_t *ft_to_wstring(const ft_table_t *table); 1014 #endif 1015 1016 1017 1018 #ifdef FT_HAVE_UTF8 1019 #define ft_u8write(table, ...)\ 1020 (ft_u8nwrite(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)) 1021 #define ft_u8write_ln(table, ...)\ 1022 (ft_u8nwrite_ln(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)) 1023 int ft_u8nwrite(ft_table_t *table, size_t n, const void *cell_content, ...); 1024 int ft_u8nwrite_ln(ft_table_t *table, size_t n, const void *cell_content, ...); 1025 1026 int ft_u8printf(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3); 1027 int ft_u8printf_ln(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3); 1028 1029 const void *ft_to_u8string(const ft_table_t *table); 1030 1031 /** 1032 * Set custom function to compute visible width of UTF-8 string. 1033 * 1034 * libfort internally has a very simple logic to compute visible width of UTF-8 1035 * strings. It considers that each codepoint will occupy one position on the 1036 * terminal in case of monowidth font (some east asians wide and fullwidth 1037 * characters (see http://www.unicode.org/reports/tr11/tr11-33.html) will occupy 1038 * 2 positions). This logic is very simple and covers wide range of cases. But 1039 * obviously there a lot of cases when it is not sufficient. In such cases user 1040 * should use some external libraries and provide an appropriate function to 1041 * libfort. 1042 * 1043 * @param u8strwid 1044 * User provided function to evaluate width of UTF-8 string ( beg - start of 1045 * UTF-8 string, end - end of UTF-8 string (not included), width - pointer to 1046 * the result). If function succeed it should return 0, otherwise some non- 1047 * zero value. If function returns nonzero value libfort fallbacks to default 1048 * internal algorithm. 1049 */ 1050 void ft_set_u8strwid_func(int (*u8strwid)(const void *beg, const void *end, size_t *width)); 1051 1052 #endif /* FT_HAVE_UTF8 */ 1053 1054 1055 FT_END_DECLS 1056 1057 #endif /* LIBFORT_H */