comparison: src/cx/buffer.h
src/cx/buffer.h
- changeset 1180
- 4c3a69b9723a
- parent 1135
- f79415d974d3
- child 1181
- 183bf43aa9b9
equal
deleted
inserted
replaced
| 1179:ca4c6f590a08 | 1180:4c3a69b9723a |
|---|---|
| 225 * (if @c NULL, a default stdlib allocator will be used) | 225 * (if @c NULL, a default stdlib allocator will be used) |
| 226 * @param flags buffer features (see cx_buffer_s.flags) | 226 * @param flags buffer features (see cx_buffer_s.flags) |
| 227 * @return zero on success, non-zero if a required allocation failed | 227 * @return zero on success, non-zero if a required allocation failed |
| 228 */ | 228 */ |
| 229 cx_attr_nonnull_arg(1) | 229 cx_attr_nonnull_arg(1) |
| 230 cx_attr_export | |
| 230 int cxBufferInit( | 231 int cxBufferInit( |
| 231 CxBuffer *buffer, | 232 CxBuffer *buffer, |
| 232 void *space, | 233 void *space, |
| 233 size_t capacity, | 234 size_t capacity, |
| 234 const CxAllocator *allocator, | 235 const CxAllocator *allocator, |
| 248 * @retval non-zero failure | 249 * @retval non-zero failure |
| 249 * @see cxBufferFlush() | 250 * @see cxBufferFlush() |
| 250 * @see cxBufferWrite() | 251 * @see cxBufferWrite() |
| 251 */ | 252 */ |
| 252 cx_attr_nonnull | 253 cx_attr_nonnull |
| 254 cx_attr_export | |
| 253 int cxBufferEnableFlushing( | 255 int cxBufferEnableFlushing( |
| 254 CxBuffer *buffer, | 256 CxBuffer *buffer, |
| 255 CxBufferFlushConfig config | 257 CxBufferFlushConfig config |
| 256 ); | 258 ); |
| 257 | 259 |
| 263 * | 265 * |
| 264 * @param buffer the buffer which contents shall be destroyed | 266 * @param buffer the buffer which contents shall be destroyed |
| 265 * @see cxBufferInit() | 267 * @see cxBufferInit() |
| 266 */ | 268 */ |
| 267 cx_attr_nonnull | 269 cx_attr_nonnull |
| 270 cx_attr_export | |
| 268 void cxBufferDestroy(CxBuffer *buffer); | 271 void cxBufferDestroy(CxBuffer *buffer); |
| 269 | 272 |
| 270 /** | 273 /** |
| 271 * Deallocates the buffer. | 274 * Deallocates the buffer. |
| 272 * | 275 * |
| 277 * case it does nothing. | 280 * case it does nothing. |
| 278 * | 281 * |
| 279 * @param buffer the buffer to deallocate | 282 * @param buffer the buffer to deallocate |
| 280 * @see cxBufferCreate() | 283 * @see cxBufferCreate() |
| 281 */ | 284 */ |
| 285 cx_attr_export | |
| 282 void cxBufferFree(CxBuffer *buffer); | 286 void cxBufferFree(CxBuffer *buffer); |
| 283 | 287 |
| 284 /** | 288 /** |
| 285 * Allocates and initializes a fresh buffer. | 289 * Allocates and initializes a fresh buffer. |
| 286 * | 290 * |
| 306 * @return a pointer to the buffer on success, @c NULL if a required allocation failed | 310 * @return a pointer to the buffer on success, @c NULL if a required allocation failed |
| 307 */ | 311 */ |
| 308 cx_attr_malloc | 312 cx_attr_malloc |
| 309 cx_attr_dealloc(cxBufferFree, 1) | 313 cx_attr_dealloc(cxBufferFree, 1) |
| 310 cx_attr_nodiscard | 314 cx_attr_nodiscard |
| 315 cx_attr_export | |
| 311 CxBuffer *cxBufferCreate( | 316 CxBuffer *cxBufferCreate( |
| 312 void *space, | 317 void *space, |
| 313 size_t capacity, | 318 size_t capacity, |
| 314 const CxAllocator *allocator, | 319 const CxAllocator *allocator, |
| 315 int flags | 320 int flags |
| 350 * @retval non-zero if a required auto-extension or copy-on-write fails | 355 * @retval non-zero if a required auto-extension or copy-on-write fails |
| 351 * @see cxBufferShiftLeft() | 356 * @see cxBufferShiftLeft() |
| 352 * @see cxBufferShiftRight() | 357 * @see cxBufferShiftRight() |
| 353 */ | 358 */ |
| 354 cx_attr_nonnull | 359 cx_attr_nonnull |
| 360 cx_attr_export | |
| 355 int cxBufferShift( | 361 int cxBufferShift( |
| 356 CxBuffer *buffer, | 362 CxBuffer *buffer, |
| 357 off_t shift | 363 off_t shift |
| 358 ); | 364 ); |
| 359 | 365 |
| 366 * @retval zero success | 372 * @retval zero success |
| 367 * @retval non-zero if a required auto-extension or copy-on-write fails | 373 * @retval non-zero if a required auto-extension or copy-on-write fails |
| 368 * @see cxBufferShift() | 374 * @see cxBufferShift() |
| 369 */ | 375 */ |
| 370 cx_attr_nonnull | 376 cx_attr_nonnull |
| 377 cx_attr_export | |
| 371 int cxBufferShiftRight( | 378 int cxBufferShiftRight( |
| 372 CxBuffer *buffer, | 379 CxBuffer *buffer, |
| 373 size_t shift | 380 size_t shift |
| 374 ); | 381 ); |
| 375 | 382 |
| 382 * @retval zero success | 389 * @retval zero success |
| 383 * @retval non-zero if the buffer uses copy-on-write and the allocation fails | 390 * @retval non-zero if the buffer uses copy-on-write and the allocation fails |
| 384 * @see cxBufferShift() | 391 * @see cxBufferShift() |
| 385 */ | 392 */ |
| 386 cx_attr_nonnull | 393 cx_attr_nonnull |
| 394 cx_attr_export | |
| 387 int cxBufferShiftLeft( | 395 int cxBufferShiftLeft( |
| 388 CxBuffer *buffer, | 396 CxBuffer *buffer, |
| 389 size_t shift | 397 size_t shift |
| 390 ); | 398 ); |
| 391 | 399 |
| 409 * @retval zero success | 417 * @retval zero success |
| 410 * @retval non-zero if the position is invalid | 418 * @retval non-zero if the position is invalid |
| 411 * | 419 * |
| 412 */ | 420 */ |
| 413 cx_attr_nonnull | 421 cx_attr_nonnull |
| 422 cx_attr_export | |
| 414 int cxBufferSeek( | 423 int cxBufferSeek( |
| 415 CxBuffer *buffer, | 424 CxBuffer *buffer, |
| 416 off_t offset, | 425 off_t offset, |
| 417 int whence | 426 int whence |
| 418 ); | 427 ); |
| 428 * | 437 * |
| 429 * @param buffer the buffer to be cleared | 438 * @param buffer the buffer to be cleared |
| 430 * @see cxBufferReset() | 439 * @see cxBufferReset() |
| 431 */ | 440 */ |
| 432 cx_attr_nonnull | 441 cx_attr_nonnull |
| 442 cx_attr_export | |
| 433 void cxBufferClear(CxBuffer *buffer); | 443 void cxBufferClear(CxBuffer *buffer); |
| 434 | 444 |
| 435 /** | 445 /** |
| 436 * Resets the buffer by resetting the position and size to zero. | 446 * Resets the buffer by resetting the position and size to zero. |
| 437 * | 447 * |
| 440 * | 450 * |
| 441 * @param buffer the buffer to be cleared | 451 * @param buffer the buffer to be cleared |
| 442 * @see cxBufferClear() | 452 * @see cxBufferClear() |
| 443 */ | 453 */ |
| 444 cx_attr_nonnull | 454 cx_attr_nonnull |
| 455 cx_attr_export | |
| 445 void cxBufferReset(CxBuffer *buffer); | 456 void cxBufferReset(CxBuffer *buffer); |
| 446 | 457 |
| 447 /** | 458 /** |
| 448 * Tests, if the buffer position has exceeded the buffer size. | 459 * Tests, if the buffer position has exceeded the buffer size. |
| 449 * | 460 * |
| 452 * byte of the buffer's contents | 463 * byte of the buffer's contents |
| 453 * @retval false otherwise | 464 * @retval false otherwise |
| 454 */ | 465 */ |
| 455 cx_attr_nonnull | 466 cx_attr_nonnull |
| 456 cx_attr_nodiscard | 467 cx_attr_nodiscard |
| 468 cx_attr_export | |
| 457 bool cxBufferEof(const CxBuffer *buffer); | 469 bool cxBufferEof(const CxBuffer *buffer); |
| 458 | 470 |
| 459 | 471 |
| 460 /** | 472 /** |
| 461 * Ensures that the buffer has a minimum capacity. | 473 * Ensures that the buffer has a minimum capacity. |
| 466 * @param capacity the minimum required capacity for this buffer | 478 * @param capacity the minimum required capacity for this buffer |
| 467 * @retval zero the capacity was already sufficient or successfully increased | 479 * @retval zero the capacity was already sufficient or successfully increased |
| 468 * @retval non-zero on allocation failure | 480 * @retval non-zero on allocation failure |
| 469 */ | 481 */ |
| 470 cx_attr_nonnull | 482 cx_attr_nonnull |
| 483 cx_attr_export | |
| 471 int cxBufferMinimumCapacity( | 484 int cxBufferMinimumCapacity( |
| 472 CxBuffer *buffer, | 485 CxBuffer *buffer, |
| 473 size_t capacity | 486 size_t capacity |
| 474 ); | 487 ); |
| 475 | 488 |
| 513 * @return the total count of elements written | 526 * @return the total count of elements written |
| 514 * @see cxBufferAppend() | 527 * @see cxBufferAppend() |
| 515 * @see cxBufferRead() | 528 * @see cxBufferRead() |
| 516 */ | 529 */ |
| 517 cx_attr_nonnull | 530 cx_attr_nonnull |
| 531 cx_attr_export | |
| 518 size_t cxBufferWrite( | 532 size_t cxBufferWrite( |
| 519 const void *ptr, | 533 const void *ptr, |
| 520 size_t size, | 534 size_t size, |
| 521 size_t nitems, | 535 size_t nitems, |
| 522 CxBuffer *buffer | 536 CxBuffer *buffer |
| 540 * @return the total count of elements written | 554 * @return the total count of elements written |
| 541 * @see cxBufferWrite() | 555 * @see cxBufferWrite() |
| 542 * @see cxBufferRead() | 556 * @see cxBufferRead() |
| 543 */ | 557 */ |
| 544 cx_attr_nonnull | 558 cx_attr_nonnull |
| 559 cx_attr_export | |
| 545 size_t cxBufferAppend( | 560 size_t cxBufferAppend( |
| 546 const void *ptr, | 561 const void *ptr, |
| 547 size_t size, | 562 size_t size, |
| 548 size_t nitems, | 563 size_t nitems, |
| 549 CxBuffer *buffer | 564 CxBuffer *buffer |
| 601 * @param buffer the buffer | 616 * @param buffer the buffer |
| 602 * @return the number of successfully flushed bytes | 617 * @return the number of successfully flushed bytes |
| 603 * @see cxBufferEnableFlushing() | 618 * @see cxBufferEnableFlushing() |
| 604 */ | 619 */ |
| 605 cx_attr_nonnull | 620 cx_attr_nonnull |
| 621 cx_attr_export | |
| 606 size_t cxBufferFlush(CxBuffer *buffer); | 622 size_t cxBufferFlush(CxBuffer *buffer); |
| 607 | 623 |
| 608 /** | 624 /** |
| 609 * Reads data from a CxBuffer. | 625 * Reads data from a CxBuffer. |
| 610 * | 626 * |
| 619 * @return the total number of elements read | 635 * @return the total number of elements read |
| 620 * @see cxBufferWrite() | 636 * @see cxBufferWrite() |
| 621 * @see cxBufferAppend() | 637 * @see cxBufferAppend() |
| 622 */ | 638 */ |
| 623 cx_attr_nonnull | 639 cx_attr_nonnull |
| 640 cx_attr_export | |
| 624 size_t cxBufferRead( | 641 size_t cxBufferRead( |
| 625 void *ptr, | 642 void *ptr, |
| 626 size_t size, | 643 size_t size, |
| 627 size_t nitems, | 644 size_t nitems, |
| 628 CxBuffer *buffer | 645 CxBuffer *buffer |
| 646 * @return the byte that has been written or @c EOF when the end of the stream is | 663 * @return the byte that has been written or @c EOF when the end of the stream is |
| 647 * reached and automatic extension is not enabled or not possible | 664 * reached and automatic extension is not enabled or not possible |
| 648 * @see cxBufferTerminate() | 665 * @see cxBufferTerminate() |
| 649 */ | 666 */ |
| 650 cx_attr_nonnull | 667 cx_attr_nonnull |
| 668 cx_attr_export | |
| 651 int cxBufferPut( | 669 int cxBufferPut( |
| 652 CxBuffer *buffer, | 670 CxBuffer *buffer, |
| 653 int c | 671 int c |
| 654 ); | 672 ); |
| 655 | 673 |
| 664 * | 682 * |
| 665 * @param buffer the buffer to write to | 683 * @param buffer the buffer to write to |
| 666 * @return zero, if the terminator could be written, non-zero otherwise | 684 * @return zero, if the terminator could be written, non-zero otherwise |
| 667 */ | 685 */ |
| 668 cx_attr_nonnull | 686 cx_attr_nonnull |
| 687 cx_attr_export | |
| 669 int cxBufferTerminate(CxBuffer *buffer); | 688 int cxBufferTerminate(CxBuffer *buffer); |
| 670 | 689 |
| 671 /** | 690 /** |
| 672 * Writes a string to a buffer. | 691 * Writes a string to a buffer. |
| 673 * | 692 * |
| 677 * @param str the zero-terminated string | 696 * @param str the zero-terminated string |
| 678 * @return the number of bytes written | 697 * @return the number of bytes written |
| 679 */ | 698 */ |
| 680 cx_attr_nonnull | 699 cx_attr_nonnull |
| 681 cx_attr_cstr_arg(2) | 700 cx_attr_cstr_arg(2) |
| 701 cx_attr_export | |
| 682 size_t cxBufferPutString( | 702 size_t cxBufferPutString( |
| 683 CxBuffer *buffer, | 703 CxBuffer *buffer, |
| 684 const char *str | 704 const char *str |
| 685 ); | 705 ); |
| 686 | 706 |
| 691 * | 711 * |
| 692 * @param buffer the buffer to read from | 712 * @param buffer the buffer to read from |
| 693 * @return the character or @c EOF, if the end of the buffer is reached | 713 * @return the character or @c EOF, if the end of the buffer is reached |
| 694 */ | 714 */ |
| 695 cx_attr_nonnull | 715 cx_attr_nonnull |
| 716 cx_attr_export | |
| 696 int cxBufferGet(CxBuffer *buffer); | 717 int cxBufferGet(CxBuffer *buffer); |
| 697 | 718 |
| 698 #ifdef __cplusplus | 719 #ifdef __cplusplus |
| 699 } | 720 } |
| 700 #endif | 721 #endif |
