xref: /freebsd/contrib/libcbor/src/cbor/strings.h (revision 5956d97f4b3204318ceb6aa9c77bd0bc6ea87a41)
1 /*
2  * Copyright (c) 2014-2020 Pavel Kalvoda <me@pavelkalvoda.com>
3  *
4  * libcbor is free software; you can redistribute it and/or modify
5  * it under the terms of the MIT license. See LICENSE for details.
6  */
7 
8 #ifndef LIBCBOR_STRINGS_H
9 #define LIBCBOR_STRINGS_H
10 
11 #include "cbor/cbor_export.h"
12 #include "cbor/common.h"
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 /*
19  * ============================================================================
20  * String manipulation
21  * ============================================================================
22  */
23 
24 /** Returns the length of the underlying string
25  *
26  * For definite strings only
27  *
28  * @param item[borrow] a definite string
29  * @return length of the string. Zero if no chunk has been attached yet
30  */
31 CBOR_EXPORT size_t cbor_string_length(const cbor_item_t *item);
32 
33 /** The number of codepoints in this string
34  *
35  * Might differ from length if there are multibyte ones
36  *
37  * @param item[borrow] A string
38  * @return The number of codepoints in this string
39  */
40 CBOR_EXPORT size_t cbor_string_codepoint_count(const cbor_item_t *item);
41 
42 /** Is the string definite?
43  *
44  * @param item[borrow] a string
45  * @return Is the string definite?
46  */
47 CBOR_EXPORT bool cbor_string_is_definite(const cbor_item_t *item);
48 
49 /** Is the string indefinite?
50  *
51  * @param item[borrow] a string
52  * @return Is the string indefinite?
53  */
54 CBOR_EXPORT bool cbor_string_is_indefinite(const cbor_item_t *item);
55 
56 /** Get the handle to the underlying string
57  *
58  * Definite items only. Modifying the data is allowed. In that case, the caller
59  * takes responsibility for the effect on items this item might be a part of
60  *
61  * @param item[borrow] A definite string
62  * @return The address of the underlying string. `NULL` if no data have been
63  * assigned yet.
64  */
65 CBOR_EXPORT cbor_mutable_data cbor_string_handle(const cbor_item_t *item);
66 
67 /** Set the handle to the underlying string
68  *
69  *
70  * \rst
71  * .. warning:: Using a pointer to a stack allocated constant is a common
72  *  mistake. Lifetime of the string will expire when it goes out of scope and
73  *  the CBOR item will be left inconsistent.
74  * \endrst
75  *
76  * @param item[borrow] A definite string
77  * @param data The memory block. The caller gives up the ownership of the block.
78  * libcbor will deallocate it when appropriate using its free function
79  * @param length Length of the data block
80  */
81 CBOR_EXPORT void cbor_string_set_handle(
82     cbor_item_t *item, cbor_mutable_data CBOR_RESTRICT_POINTER data,
83     size_t length);
84 
85 /** Get the handle to the array of chunks
86  *
87  * Manipulations with the memory block (e.g. sorting it) are allowed, but the
88  * validity and the number of chunks must be retained.
89  *
90  * @param item[borrow] A indefinite string
91  * @return array of #cbor_string_chunk_count definite strings
92  */
93 CBOR_EXPORT cbor_item_t **cbor_string_chunks_handle(const cbor_item_t *item);
94 
95 /** Get the number of chunks this string consist of
96  *
97  * @param item[borrow] A indefinite string
98  * @return The chunk count. 0 for freshly created items.
99  */
100 CBOR_EXPORT size_t cbor_string_chunk_count(const cbor_item_t *item);
101 
102 /** Appends a chunk to the string
103  *
104  * Indefinite strings only.
105  *
106  * May realloc the chunk storage.
107  *
108  * @param item[borrow] An indefinite string
109  * @param item[incref] A definite string
110  * @return true on success. false on realloc failure. In that case, the refcount
111  * of `chunk` is not increased and the `item` is left intact.
112  */
113 CBOR_EXPORT bool cbor_string_add_chunk(cbor_item_t *item, cbor_item_t *chunk);
114 
115 /** Creates a new definite string
116  *
117  * The handle is initialized to `NULL` and length to 0
118  *
119  * @return **new** definite string. `NULL` on malloc failure.
120  */
121 CBOR_EXPORT cbor_item_t *cbor_new_definite_string();
122 
123 /** Creates a new indefinite string
124  *
125  * The chunks array is initialized to `NULL` and chunkcount to 0
126  *
127  * @return **new** indefinite string. `NULL` on malloc failure.
128  */
129 CBOR_EXPORT cbor_item_t *cbor_new_indefinite_string();
130 
131 /** Creates a new string and initializes it
132  *
133  * The `val` will be copied to a newly allocated block
134  *
135  * @param val A null-terminated UTF-8 string
136  * @return A **new** string with content `handle`. `NULL` on malloc failure.
137  */
138 CBOR_EXPORT cbor_item_t *cbor_build_string(const char *val);
139 
140 /** Creates a new string and initializes it
141  *
142  * The `handle` will be copied to a newly allocated block
143  *
144  * @param val A UTF-8 string, at least \p length long (excluding the null byte)
145  * @return A **new** string with content `handle`. `NULL` on malloc failure.
146  */
147 CBOR_EXPORT cbor_item_t *cbor_build_stringn(const char *val, size_t length);
148 
149 #ifdef __cplusplus
150 }
151 #endif
152 
153 #endif  // LIBCBOR_STRINGS_H
154