rlib
Convenience library for useful things
Loading...
Searching...
No Matches
rstring.h
Go to the documentation of this file.
1/* RLIB - Convenience library for useful things
2 * Copyright (C) 2015 Haakon Sporsheim <haakon.sporsheim@gmail.com>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 3.0 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library.
16 * See the COPYING file at the root of the source repository.
17 */
18#ifndef __R_STRING_H__
19#define __R_STRING_H__
20
21#if !defined(__RLIB_H_INCLUDE_GUARD__) && !defined(RLIB_COMPILATION)
22#error "#include <rlib.h> only please."
23#endif
24
25#include <rlib/rtypes.h>
26#include <stdarg.h>
27
53R_BEGIN_DECLS
54
56typedef struct RString RString;
57
69R_ATTR_WARN_UNUSED_RESULT
70R_API RString * r_string_new (const rchar * cstr) R_ATTR_MALLOC;
81R_ATTR_WARN_UNUSED_RESULT
82R_API RString * r_string_new_sized (rsize size) R_ATTR_MALLOC;
83
85R_API void r_string_free (RString * str);
94R_ATTR_WARN_UNUSED_RESULT
95R_API rchar * r_string_free_keep (RString * str);
96
105R_API rsize r_string_length (RString * str);
107R_API rsize r_string_alloc_size (RString * str);
108
110R_API int r_string_cmp (RString * str1, RString * str2);
112R_API int r_string_cmp_cstr (RString * str, const rchar * cstr);
113
138R_API rsize r_string_reset (RString * str, const rchar * cstr);
139
141R_API rsize r_string_append_c (RString * str, rchar c);
143R_API rsize r_string_append (RString * str, const rchar * cstr);
145R_API rsize r_string_append_len (RString * str, const rchar * cstr, rsize len);
150R_API rsize r_string_append_printf (RString * str, const rchar * fmt, ...) R_ATTR_PRINTF (2, 3);
152R_API rsize r_string_append_vprintf (RString * str, const rchar * fmt, va_list ap) R_ATTR_PRINTF (2, 0);
153
155R_API rsize r_string_prepend (RString * str, const rchar * cstr);
157R_API rsize r_string_prepend_len (RString * str, const rchar * cstr, rsize len);
159R_API rsize r_string_prepend_printf (RString * str, const rchar * fmt, ...) R_ATTR_PRINTF (2, 3);
161R_API rsize r_string_prepend_vprintf (RString * str, const rchar * fmt, va_list ap) R_ATTR_PRINTF (2, 0);
162
168R_API rsize r_string_insert (RString * str, rsize pos, const rchar * cstr);
170R_API rsize r_string_insert_len (RString * str, rsize pos, const rchar * cstr, rsize len);
177R_API rsize r_string_overwrite (RString * str, rsize pos, const rchar * cstr);
179R_API rsize r_string_overwrite_len (RString * str, rsize pos, const rchar * cstr, rsize len);
180
183R_API rsize r_string_truncate (RString * str, rsize len);
189R_API rsize r_string_erase (RString * str, rsize pos, rsize len);
190
193R_END_DECLS
194
/* r_string group */
196
197#endif /* __R_STRING_H__ */
198
R_ATTR_WARN_UNUSED_RESULT
#define R_ATTR_WARN_UNUSED_RESULT
Warn if a function's return value is ignored.
Definition rmacros.h:278
R_API
#define R_API
Public-API decoration: resolves to R_API_EXPORT while building rlib and R_API_IMPORT for consumers.
Definition rmacros.h:115
R_BEGIN_DECLS
#define R_BEGIN_DECLS
Open an extern "C" block under C++ (no-op in C).
Definition rmacros.h:196
r_string_new_sized
R_ATTR_WARN_UNUSED_RESULT RString * r_string_new_sized(rsize size)
Allocate an empty RString with size bytes of buffer reserved up front.
r_string_prepend_len
rsize r_string_prepend_len(RString *str, const rchar *cstr, rsize len)
Prepend len bytes from cstr to the front of str.
r_string_free
void r_string_free(RString *str)
Free the RString and its backing buffer.
r_string_overwrite
rsize r_string_overwrite(RString *str, rsize pos, const rchar *cstr)
Overwrite bytes starting at pos with cstr.
r_string_prepend_printf
rsize r_string_prepend_printf(RString *str, const rchar *fmt,...)
printf-format and prepend the result to the front of str.
r_string_append_vprintf
rsize r_string_append_vprintf(RString *str, const rchar *fmt, va_list ap)
va_list flavour of r_string_append_printf.
r_string_truncate
rsize r_string_truncate(RString *str, rsize len)
Trim str to len bytes (no-op, returning 0, if already shorter).
r_string_cmp_cstr
int r_string_cmp_cstr(RString *str, const rchar *cstr)
Byte-compare an RString against a NUL-terminated C string.
r_string_alloc_size
rsize r_string_alloc_size(RString *str)
Capacity of the underlying buffer in bytes.
RString
struct RString RString
Opaque heap-allocated mutable string.
Definition rstring.h:56
r_string_insert
rsize r_string_insert(RString *str, rsize pos, const rchar *cstr)
Insert cstr at byte offset pos, sliding the existing tail to the right.
r_string_length
rsize r_string_length(RString *str)
Current length in bytes (excluding the terminating NUL).
r_string_append
rsize r_string_append(RString *str, const rchar *cstr)
Append a NUL-terminated C string to str.
r_string_new
R_ATTR_WARN_UNUSED_RESULT RString * r_string_new(const rchar *cstr)
Allocate an RString seeded from the NUL-terminated cstr.
r_string_append_len
rsize r_string_append_len(RString *str, const rchar *cstr, rsize len)
Append len bytes from cstr to str.
r_string_overwrite_len
rsize r_string_overwrite_len(RString *str, rsize pos, const rchar *cstr, rsize len)
Length-bounded variant of r_string_overwrite.
r_string_cmp
int r_string_cmp(RString *str1, RString *str2)
Byte-compare two RString contents. Behaves like r_strcmp.
r_string_prepend
rsize r_string_prepend(RString *str, const rchar *cstr)
Prepend a NUL-terminated C string to the front of str.
r_string_erase
rsize r_string_erase(RString *str, rsize pos, rsize len)
Remove len bytes starting at byte offset pos (clamped to the end of the string).
r_string_prepend_vprintf
rsize r_string_prepend_vprintf(RString *str, const rchar *fmt, va_list ap)
va_list flavour of r_string_prepend_printf.
r_string_free_keep
R_ATTR_WARN_UNUSED_RESULT rchar * r_string_free_keep(RString *str)
Free the RString struct but return its inner rchar *.
r_string_insert_len
rsize r_string_insert_len(RString *str, rsize pos, const rchar *cstr, rsize len)
Length-bounded variant of r_string_insert.
r_string_reset
rsize r_string_reset(RString *str, const rchar *cstr)
Discard the current contents and seed str from a fresh NUL-terminated C string.
r_string_append_printf
rsize r_string_append_printf(RString *str, const rchar *fmt,...)
printf-format and append the result to str.
r_string_append_c
rsize r_string_append_c(RString *str, rchar c)
Append a single byte to str.
rchar
char rchar
Default character type (char).
Definition rtypes.h:137
rsize
unsigned long rsize
Unsigned pointer-sized size type (like size_t).
Definition rtypes.h:290
rtypes.h
Foundational type aliases used by every rlib header.