Mercurial > hg > idav / file comparison

comparison: ucx/cx/buffer.h

ucx/cx/buffer.h

changeset 113
dde28a806552
parent 112
c3f2f16fa4b8
equal deleted inserted replaced
112:c3f2f16fa4b8 113:dde28a806552
225 * (if @c NULL, the cxDefaultAllocator will be used) 225 * (if @c NULL, the cxDefaultAllocator 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 CX_EXPORT int cxBufferInit(CxBuffer *buffer, void *space, size_t capacity,
231 int cxBufferInit( 231 const CxAllocator *allocator, int flags);
232 CxBuffer *buffer,
233 void *space,
234 size_t capacity,
235 const CxAllocator *allocator,
236 int flags
237 );
238 232
239 /** 233 /**
240 * Configures the buffer for flushing. 234 * Configures the buffer for flushing.
241 * 235 *
242 * Flushing can happen automatically when data is written 236 * Flushing can happen automatically when data is written
249 * @retval non-zero failure 243 * @retval non-zero failure
250 * @see cxBufferFlush() 244 * @see cxBufferFlush()
251 * @see cxBufferWrite() 245 * @see cxBufferWrite()
252 */ 246 */
253 cx_attr_nonnull 247 cx_attr_nonnull
254 cx_attr_export 248 CX_EXPORT int cxBufferEnableFlushing(CxBuffer *buffer, CxBufferFlushConfig config);
255 int cxBufferEnableFlushing(
256 CxBuffer *buffer,
257 CxBufferFlushConfig config
258 );
259 249
260 /** 250 /**
261 * Destroys the buffer contents. 251 * Destroys the buffer contents.
262 * 252 *
263 * Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled. 253 * Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled.
265 * 255 *
266 * @param buffer the buffer which contents shall be destroyed 256 * @param buffer the buffer which contents shall be destroyed
267 * @see cxBufferInit() 257 * @see cxBufferInit()
268 */ 258 */
269 cx_attr_nonnull 259 cx_attr_nonnull
270 cx_attr_export 260 CX_EXPORT void cxBufferDestroy(CxBuffer *buffer);
271 void cxBufferDestroy(CxBuffer *buffer);
272 261
273 /** 262 /**
274 * Deallocates the buffer. 263 * Deallocates the buffer.
275 * 264 *
276 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys 265 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys
277 * the contents. If you @em only want to destroy the contents, use cxBufferDestroy(). 266 * the contents. If you @em only want to destroy the contents, use cxBufferDestroy().
278 * 267 *
279 * @param buffer the buffer to deallocate 268 * @param buffer the buffer to deallocate
280 * @see cxBufferCreate() 269 * @see cxBufferCreate()
281 */ 270 */
282 cx_attr_export 271 CX_EXPORT void cxBufferFree(CxBuffer *buffer);
283 void cxBufferFree(CxBuffer *buffer);
284 272
285 /** 273 /**
286 * Allocates and initializes a fresh buffer. 274 * Allocates and initializes a fresh buffer.
287 * 275 *
288 * You may also provide a read-only @p space, in which case 276 * You may also provide a read-only @p space, in which case
304 * memory management within the buffer 292 * memory management within the buffer
305 * (if @c NULL, the cxDefaultAllocator will be used) 293 * (if @c NULL, the cxDefaultAllocator will be used)
306 * @param flags buffer features (see cx_buffer_s.flags) 294 * @param flags buffer features (see cx_buffer_s.flags)
307 * @return a pointer to the buffer on success, @c NULL if a required allocation failed 295 * @return a pointer to the buffer on success, @c NULL if a required allocation failed
308 */ 296 */
309 cx_attr_malloc 297 cx_attr_malloc cx_attr_dealloc(cxBufferFree, 1) cx_attr_nodiscard
310 cx_attr_dealloc(cxBufferFree, 1) 298 CX_EXPORT CxBuffer *cxBufferCreate(void *space, size_t capacity,
311 cx_attr_nodiscard 299 const CxAllocator *allocator, int flags);
312 cx_attr_export
313 CxBuffer *cxBufferCreate(
314 void *space,
315 size_t capacity,
316 const CxAllocator *allocator,
317 int flags
318 );
319 300
320 /** 301 /**
321 * Shifts the contents of the buffer by the given offset. 302 * Shifts the contents of the buffer by the given offset.
322 * 303 *
323 * If the offset is positive, the contents are shifted to the right. 304 * If the offset is positive, the contents are shifted to the right.
352 * @retval non-zero if a required auto-extension or copy-on-write fails 333 * @retval non-zero if a required auto-extension or copy-on-write fails
353 * @see cxBufferShiftLeft() 334 * @see cxBufferShiftLeft()
354 * @see cxBufferShiftRight() 335 * @see cxBufferShiftRight()
355 */ 336 */
356 cx_attr_nonnull 337 cx_attr_nonnull
357 cx_attr_export 338 CX_EXPORT int cxBufferShift(CxBuffer *buffer, off_t shift);
358 int cxBufferShift(
359 CxBuffer *buffer,
360 off_t shift
361 );
362 339
363 /** 340 /**
364 * Shifts the buffer to the right. 341 * Shifts the buffer to the right.
365 * See cxBufferShift() for details. 342 * See cxBufferShift() for details.
366 * 343 *
369 * @retval zero success 346 * @retval zero success
370 * @retval non-zero if a required auto-extension or copy-on-write fails 347 * @retval non-zero if a required auto-extension or copy-on-write fails
371 * @see cxBufferShift() 348 * @see cxBufferShift()
372 */ 349 */
373 cx_attr_nonnull 350 cx_attr_nonnull
374 cx_attr_export 351 CX_EXPORT int cxBufferShiftRight(CxBuffer *buffer, size_t shift);
375 int cxBufferShiftRight(
376 CxBuffer *buffer,
377 size_t shift
378 );
379 352
380 /** 353 /**
381 * Shifts the buffer to the left. 354 * Shifts the buffer to the left.
382 * See cxBufferShift() for details. 355 * See cxBufferShift() for details.
383 * 356 *
386 * @retval zero success 359 * @retval zero success
387 * @retval non-zero if the buffer uses copy-on-write and the allocation fails 360 * @retval non-zero if the buffer uses copy-on-write and the allocation fails
388 * @see cxBufferShift() 361 * @see cxBufferShift()
389 */ 362 */
390 cx_attr_nonnull 363 cx_attr_nonnull
391 cx_attr_export 364 CX_EXPORT int cxBufferShiftLeft(CxBuffer *buffer, size_t shift);
392 int cxBufferShiftLeft(
393 CxBuffer *buffer,
394 size_t shift
395 );
396 365
397 366
398 /** 367 /**
399 * Moves the position of the buffer. 368 * Moves the position of the buffer.
400 * 369 *
414 * @retval zero success 383 * @retval zero success
415 * @retval non-zero if the position is invalid 384 * @retval non-zero if the position is invalid
416 * 385 *
417 */ 386 */
418 cx_attr_nonnull 387 cx_attr_nonnull
419 cx_attr_export 388 CX_EXPORT int cxBufferSeek(CxBuffer *buffer, off_t offset, int whence);
420 int cxBufferSeek(
421 CxBuffer *buffer,
422 off_t offset,
423 int whence
424 );
425 389
426 /** 390 /**
427 * Clears the buffer by resetting the position and deleting the data. 391 * Clears the buffer by resetting the position and deleting the data.
428 * 392 *
429 * The data is deleted by zeroing it with a call to memset(). 393 * The data is deleted by zeroing it with a call to memset().
434 * 398 *
435 * @param buffer the buffer to be cleared 399 * @param buffer the buffer to be cleared
436 * @see cxBufferReset() 400 * @see cxBufferReset()
437 */ 401 */
438 cx_attr_nonnull 402 cx_attr_nonnull
439 cx_attr_export 403 CX_EXPORT void cxBufferClear(CxBuffer *buffer);
440 void cxBufferClear(CxBuffer *buffer);
441 404
442 /** 405 /**
443 * Resets the buffer by resetting the position and size to zero. 406 * Resets the buffer by resetting the position and size to zero.
444 * 407 *
445 * The data in the buffer is not deleted. If you need a safe 408 * The data in the buffer is not deleted. If you need a safe
447 * 410 *
448 * @param buffer the buffer to be cleared 411 * @param buffer the buffer to be cleared
449 * @see cxBufferClear() 412 * @see cxBufferClear()
450 */ 413 */
451 cx_attr_nonnull 414 cx_attr_nonnull
452 cx_attr_export 415 CX_EXPORT void cxBufferReset(CxBuffer *buffer);
453 void cxBufferReset(CxBuffer *buffer);
454 416
455 /** 417 /**
456 * Tests, if the buffer position has exceeded the buffer size. 418 * Tests, if the buffer position has exceeded the buffer size.
457 * 419 *
458 * @param buffer the buffer to test 420 * @param buffer the buffer to test
459 * @retval true if the current buffer position has exceeded the last 421 * @retval true if the current buffer position has exceeded the last
460 * byte of the buffer's contents 422 * byte of the buffer's contents
461 * @retval false otherwise 423 * @retval false otherwise
462 */ 424 */
463 cx_attr_nonnull 425 cx_attr_nonnull cx_attr_nodiscard
464 cx_attr_nodiscard 426 CX_EXPORT bool cxBufferEof(const CxBuffer *buffer);
465 cx_attr_export
466 bool cxBufferEof(const CxBuffer *buffer);
467 427
468 428
469 /** 429 /**
470 * Ensures that the buffer has a minimum capacity. 430 * Ensures that the buffer has a minimum capacity.
471 * 431 *
479 * @retval zero the capacity was already sufficient or successfully increased 439 * @retval zero the capacity was already sufficient or successfully increased
480 * @retval non-zero on allocation failure 440 * @retval non-zero on allocation failure
481 * @see cxBufferShrink() 441 * @see cxBufferShrink()
482 */ 442 */
483 cx_attr_nonnull 443 cx_attr_nonnull
484 cx_attr_export 444 CX_EXPORT int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity);
485 int cxBufferMinimumCapacity(
486 CxBuffer *buffer,
487 size_t capacity
488 );
489 445
490 /** 446 /**
491 * Shrinks the capacity of the buffer to fit its current size. 447 * Shrinks the capacity of the buffer to fit its current size.
492 * 448 *
493 * If @p reserve is larger than zero, the buffer is shrunk to its size plus 449 * If @p reserve is larger than zero, the buffer is shrunk to its size plus
502 * @param buffer the buffer 458 * @param buffer the buffer
503 * @param reserve the number of bytes that shall remain reserved 459 * @param reserve the number of bytes that shall remain reserved
504 * @see cxBufferMinimumCapacity() 460 * @see cxBufferMinimumCapacity()
505 */ 461 */
506 cx_attr_nonnull 462 cx_attr_nonnull
507 cx_attr_export 463 CX_EXPORT void cxBufferShrink(CxBuffer *buffer, size_t reserve);
508 void cxBufferShrink(
509 CxBuffer *buffer,
510 size_t reserve
511 );
512 464
513 /** 465 /**
514 * Writes data to a CxBuffer. 466 * Writes data to a CxBuffer.
515 * 467 *
516 * If automatic flushing is not enabled, the data is simply written into the 468 * If automatic flushing is not enabled, the data is simply written into the
550 * @return the total count of elements written 502 * @return the total count of elements written
551 * @see cxBufferAppend() 503 * @see cxBufferAppend()
552 * @see cxBufferRead() 504 * @see cxBufferRead()
553 */ 505 */
554 cx_attr_nonnull 506 cx_attr_nonnull
555 cx_attr_export 507 CX_EXPORT size_t cxBufferWrite(const void *ptr, size_t size,
556 size_t cxBufferWrite( 508 size_t nitems, CxBuffer *buffer);
557 const void *ptr,
558 size_t size,
559 size_t nitems,
560 CxBuffer *buffer
561 );
562 509
563 /** 510 /**
564 * Appends data to a CxBuffer. 511 * Appends data to a CxBuffer.
565 * 512 *
566 * The data is always appended to current data within the buffer, 513 * The data is always appended to current data within the buffer,
578 * @return the total count of elements written 525 * @return the total count of elements written
579 * @see cxBufferWrite() 526 * @see cxBufferWrite()
580 * @see cxBufferRead() 527 * @see cxBufferRead()
581 */ 528 */
582 cx_attr_nonnull 529 cx_attr_nonnull
583 cx_attr_export 530 CX_EXPORT size_t cxBufferAppend(const void *ptr, size_t size,
584 size_t cxBufferAppend( 531 size_t nitems, CxBuffer *buffer);
585 const void *ptr,
586 size_t size,
587 size_t nitems,
588 CxBuffer *buffer
589 );
590 532
591 /** 533 /**
592 * Performs a single flush-run on the specified buffer. 534 * Performs a single flush-run on the specified buffer.
593 * 535 *
594 * Does nothing when the position in the buffer is zero. 536 * Does nothing when the position in the buffer is zero.
640 * @param buffer the buffer 582 * @param buffer the buffer
641 * @return the number of successfully flushed bytes 583 * @return the number of successfully flushed bytes
642 * @see cxBufferEnableFlushing() 584 * @see cxBufferEnableFlushing()
643 */ 585 */
644 cx_attr_nonnull 586 cx_attr_nonnull
645 cx_attr_export 587 CX_EXPORT size_t cxBufferFlush(CxBuffer *buffer);
646 size_t cxBufferFlush(CxBuffer *buffer);
647 588
648 /** 589 /**
649 * Reads data from a CxBuffer. 590 * Reads data from a CxBuffer.
650 * 591 *
651 * The position of the buffer is increased by the number of bytes read. 592 * The position of the buffer is increased by the number of bytes read.
659 * @return the total number of elements read 600 * @return the total number of elements read
660 * @see cxBufferWrite() 601 * @see cxBufferWrite()
661 * @see cxBufferAppend() 602 * @see cxBufferAppend()
662 */ 603 */
663 cx_attr_nonnull 604 cx_attr_nonnull
664 cx_attr_export 605 CX_EXPORT size_t cxBufferRead(void *ptr, size_t size,
665 size_t cxBufferRead( 606 size_t nitems, CxBuffer *buffer);
666 void *ptr,
667 size_t size,
668 size_t nitems,
669 CxBuffer *buffer
670 );
671 607
672 /** 608 /**
673 * Writes a character to a buffer. 609 * Writes a character to a buffer.
674 * 610 *
675 * The least significant byte of the argument is written to the buffer. If the 611 * The least significant byte of the argument is written to the buffer. If the
687 * @return the byte that has been written or @c EOF when the end of the stream is 623 * @return the byte that has been written or @c EOF when the end of the stream is
688 * reached, and automatic extension is not enabled or not possible 624 * reached, and automatic extension is not enabled or not possible
689 * @see cxBufferTerminate() 625 * @see cxBufferTerminate()
690 */ 626 */
691 cx_attr_nonnull 627 cx_attr_nonnull
692 cx_attr_export 628 CX_EXPORT int cxBufferPut(CxBuffer *buffer, int c);
693 int cxBufferPut(
694 CxBuffer *buffer,
695 int c
696 );
697 629
698 /** 630 /**
699 * Writes a terminating zero to a buffer at the current position. 631 * Writes a terminating zero to a buffer at the current position.
700 * 632 *
701 * If successful, sets the size to the current position and advances the position by one. 633 * If successful, sets the size to the current position and advances the position by one.
705 * 637 *
706 * @param buffer the buffer to write to 638 * @param buffer the buffer to write to
707 * @return zero, if the terminator could be written, non-zero otherwise 639 * @return zero, if the terminator could be written, non-zero otherwise
708 */ 640 */
709 cx_attr_nonnull 641 cx_attr_nonnull
710 cx_attr_export 642 CX_EXPORT int cxBufferTerminate(CxBuffer *buffer);
711 int cxBufferTerminate(CxBuffer *buffer);
712 643
713 /** 644 /**
714 * Writes a string to a buffer. 645 * Writes a string to a buffer.
715 * 646 *
716 * This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>. 647 * This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>.
717 * 648 *
718 * @param buffer the buffer 649 * @param buffer the buffer
719 * @param str the zero-terminated string 650 * @param str the zero-terminated string
720 * @return the number of bytes written 651 * @return the number of bytes written
721 */ 652 */
722 cx_attr_nonnull 653 cx_attr_nonnull cx_attr_cstr_arg(2)
723 cx_attr_cstr_arg(2) 654 CX_EXPORT size_t cxBufferPutString(CxBuffer *buffer, const char *str);
724 cx_attr_export
725 size_t cxBufferPutString(
726 CxBuffer *buffer,
727 const char *str
728 );
729 655
730 /** 656 /**
731 * Gets a character from a buffer. 657 * Gets a character from a buffer.
732 * 658 *
733 * The current position of the buffer is increased after a successful read. 659 * The current position of the buffer is increased after a successful read.
734 * 660 *
735 * @param buffer the buffer to read from 661 * @param buffer the buffer to read from
736 * @return the character or @c EOF, if the end of the buffer is reached 662 * @return the character or @c EOF, if the end of the buffer is reached
737 */ 663 */
738 cx_attr_nonnull 664 cx_attr_nonnull
739 cx_attr_export 665 CX_EXPORT int cxBufferGet(CxBuffer *buffer);
740 int cxBufferGet(CxBuffer *buffer);
741 666
742 #ifdef __cplusplus 667 #ifdef __cplusplus
743 } 668 }
744 #endif 669 #endif
745 670

Mercurial Repository: idav

mercurial