src/buffer.h

   1 /*
   2  * Copyright (C) 2009-2012 the libgit2 contributors
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_buffer_h__
   8 #define INCLUDE_buffer_h__
   9
  10 #include "common.h"
  11 #include "git2/strarray.h"
  12 #include <stdarg.h>
  13
  14 typedef struct {
  15         char *ptr;
  16         size_t asize, size;
  17 } git_buf;
  18
  19 extern char git_buf__initbuf[];
  20 extern char git_buf__oom[];
  21
  22 #define GIT_BUF_INIT { git_buf__initbuf, 0, 0 }
  23
  24 /**
  25  * Initialize a git_buf structure.
  26  *
  27  * For the cases where GIT_BUF_INIT cannot be used to do static
  28  * initialization.
  29  */
  30 extern void git_buf_init(git_buf *buf, size_t initial_size);
  31
  32 /**
  33  * Attempt to grow the buffer to hold at least `target_size` bytes.
  34  *
  35  * If the allocation fails, this will return an error.  If mark_oom is true,
  36  * this will mark the buffer as invalid for future operations; if false,
  37  * existing buffer content will be preserved, but calling code must handle
  38  * that buffer was not expanded.
  39  */
  40 extern int git_buf_try_grow(git_buf *buf, size_t target_size, bool mark_oom);
  41
  42 /**
  43  * Grow the buffer to hold at least `target_size` bytes.
  44  *
  45  * If the allocation fails, this will return an error and the buffer will be
  46  * marked as invalid for future operations, invaliding contents.
  47  *
  48  * @return 0 on success or -1 on failure
  49  */
  50 GIT_INLINE(int) git_buf_grow(git_buf *buf, size_t target_size)
  51 {
  52         return git_buf_try_grow(buf, target_size, true);
  53 }
  54
  55 extern void git_buf_free(git_buf *buf);
  56 extern void git_buf_swap(git_buf *buf_a, git_buf *buf_b);
  57 extern char *git_buf_detach(git_buf *buf);
  58 extern void git_buf_attach(git_buf *buf, char *ptr, size_t asize);
  59
  60 /**
  61  * Test if there have been any reallocation failures with this git_buf.
  62  *
  63  * Any function that writes to a git_buf can fail due to memory allocation
  64  * issues.  If one fails, the git_buf will be marked with an OOM error and
  65  * further calls to modify the buffer will fail.  Check git_buf_oom() at the
  66  * end of your sequence and it will be true if you ran out of memory at any
  67  * point with that buffer.
  68  *
  69  * @return false if no error, true if allocation error
  70  */
  71 GIT_INLINE(bool) git_buf_oom(const git_buf *buf)
  72 {
  73         return (buf->ptr == git_buf__oom);
  74 }
  75
  76 /*
  77  * Functions below that return int value error codes will return 0 on
  78  * success or -1 on failure (which generally means an allocation failed).
  79  * Using a git_buf where the allocation has failed with result in -1 from
  80  * all further calls using that buffer.  As a result, you can ignore the
  81  * return code of these functions and call them in a series then just call
  82  * git_buf_oom at the end.
  83  */
  84 int git_buf_set(git_buf *buf, const char *data, size_t len);
  85 int git_buf_sets(git_buf *buf, const char *string);
  86 int git_buf_putc(git_buf *buf, char c);
  87 int git_buf_put(git_buf *buf, const char *data, size_t len);
  88 int git_buf_puts(git_buf *buf, const char *string);
  89 int git_buf_printf(git_buf *buf, const char *format, ...) GIT_FORMAT_PRINTF(2, 3);
  90 int git_buf_vprintf(git_buf *buf, const char *format, va_list ap);
  91 void git_buf_clear(git_buf *buf);
  92 void git_buf_consume(git_buf *buf, const char *end);
  93 void git_buf_truncate(git_buf *buf, size_t len);
  94 void git_buf_rtruncate_at_char(git_buf *path, char separator);
  95
  96 int git_buf_join_n(git_buf *buf, char separator, int nbuf, ...);
  97 int git_buf_join(git_buf *buf, char separator, const char *str_a, const char *str_b);
  98
  99 /**
 100  * Join two strings as paths, inserting a slash between as needed.
 101  * @return 0 on success, -1 on failure
 102  */
 103 GIT_INLINE(int) git_buf_joinpath(git_buf *buf, const char *a, const char *b)
 104 {
 105         return git_buf_join(buf, '/', a, b);
 106 }
 107
 108 GIT_INLINE(const char *) git_buf_cstr(const git_buf *buf)
 109 {
 110         return buf->ptr;
 111 }
 112
 113 GIT_INLINE(size_t) git_buf_len(const git_buf *buf)
 114 {
 115         return buf->size;
 116 }
 117
 118 void git_buf_copy_cstr(char *data, size_t datasize, const git_buf *buf);
 119
 120 #define git_buf_PUTS(buf, str) git_buf_put(buf, str, sizeof(str) - 1)
 121
 122 GIT_INLINE(ssize_t) git_buf_rfind_next(git_buf *buf, char ch)
 123 {
 124         ssize_t idx = (ssize_t)buf->size - 1;
 125         while (idx >= 0 && buf->ptr[idx] == ch) idx--;
 126         while (idx >= 0 && buf->ptr[idx] != ch) idx--;
 127         return idx;
 128 }
 129
 130 GIT_INLINE(ssize_t) git_buf_rfind(git_buf *buf, char ch)
 131 {
 132         ssize_t idx = (ssize_t)buf->size - 1;
 133         while (idx >= 0 && buf->ptr[idx] != ch) idx--;
 134         return idx;
 135 }
 136
 137 /* Remove whitespace from the end of the buffer */
 138 void git_buf_rtrim(git_buf *buf);
 139
 140 int git_buf_cmp(const git_buf *a, const git_buf *b);
 141
 142 /* Write data as base64 encoded in buffer */
 143 int git_buf_put_base64(git_buf *buf, const char *data, size_t len);
 144
 145 /*
 146  * Insert, remove or replace a portion of the buffer.
 147  *
 148  * @param buf The buffer to work with
 149  *
 150  * @param where The location in the buffer where the transformation
 151  * should be applied.
 152  *
 153  * @param nb_to_remove The number of chars to be removed. 0 to not
 154  * remove any character in the buffer.
 155  *
 156  * @param data A pointer to the data which should be inserted.
 157  *
 158  * @param nb_to_insert The number of chars to be inserted. 0 to not
 159  * insert any character from the buffer.
 160  *
 161  * @return 0 or an error code.
 162  */
 163 int git_buf_splice(
 164         git_buf *buf,
 165         size_t where,
 166         size_t nb_to_remove,
 167         const char *data,
 168         size_t nb_to_insert);
 169
 170 #endif