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 in bytes 25 * 26 * There can be fewer unicode character than bytes (see 27 * `cbor_string_codepoint_count`). For definite strings only. 28 * 29 * @param item a definite string 30 * @return length of the string. Zero if no chunk has been attached yet 31 */ 32 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_string_length(const cbor_item_t *item); 33 34 /** The number of codepoints in this string 35 * 36 * Might differ from length if there are multibyte ones 37 * 38 * @param item A string 39 * @return The number of codepoints in this string 40 */ 41 _CBOR_NODISCARD CBOR_EXPORT size_t 42 cbor_string_codepoint_count(const cbor_item_t *item); 43 44 /** Is the string definite? 45 * 46 * @param item a string 47 * @return Is the string definite? 48 */ 49 _CBOR_NODISCARD CBOR_EXPORT bool cbor_string_is_definite( 50 const cbor_item_t *item); 51 52 /** Is the string indefinite? 53 * 54 * @param item a string 55 * @return Is the string indefinite? 56 */ 57 _CBOR_NODISCARD CBOR_EXPORT bool cbor_string_is_indefinite( 58 const cbor_item_t *item); 59 60 /** Get the handle to the underlying string 61 * 62 * Definite items only. Modifying the data is allowed. In that case, the caller 63 * takes responsibility for the effect on items this item might be a part of 64 * 65 * @param item A definite string 66 * @return The address of the underlying string. 67 * @return `NULL` if no data have been assigned yet. 68 */ 69 _CBOR_NODISCARD CBOR_EXPORT cbor_mutable_data 70 cbor_string_handle(const cbor_item_t *item); 71 72 /** Set the handle to the underlying string 73 * 74 * 75 * \rst 76 * .. warning:: Using a pointer to a stack allocated constant is a common 77 * mistake. Lifetime of the string will expire when it goes out of scope and 78 * the CBOR item will be left inconsistent. 79 * \endrst 80 * 81 * @param item A definite string 82 * @param data The memory block. The caller gives up the ownership of the block. 83 * libcbor will deallocate it when appropriate using its free function 84 * @param length Length of the data block 85 */ 86 CBOR_EXPORT void cbor_string_set_handle( 87 cbor_item_t *item, cbor_mutable_data CBOR_RESTRICT_POINTER data, 88 size_t length); 89 90 /** Get the handle to the array of chunks 91 * 92 * Manipulations with the memory block (e.g. sorting it) are allowed, but the 93 * validity and the number of chunks must be retained. 94 * 95 * @param item A indefinite string 96 * @return array of #cbor_string_chunk_count definite strings 97 */ 98 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t **cbor_string_chunks_handle( 99 const cbor_item_t *item); 100 101 /** Get the number of chunks this string consist of 102 * 103 * @param item A indefinite string 104 * @return The chunk count. 0 for freshly created items. 105 */ 106 _CBOR_NODISCARD CBOR_EXPORT size_t 107 cbor_string_chunk_count(const cbor_item_t *item); 108 109 /** Appends a chunk to the string 110 * 111 * Indefinite strings only. 112 * 113 * May realloc the chunk storage. 114 * 115 * @param item An indefinite string 116 * @param chunk A definite string item. Its reference count will be increased 117 * by one. 118 * @return `true` on success. `false` on memory allocation failure. In that 119 * case, the refcount of @p `chunk` is not increased and the @p `item` is left 120 * intact. 121 */ 122 _CBOR_NODISCARD CBOR_EXPORT bool cbor_string_add_chunk(cbor_item_t *item, 123 cbor_item_t *chunk); 124 125 /** Creates a new definite string 126 * 127 * The handle is initialized to `NULL` and length to 0 128 * 129 * @return Reference to the new string item. The item's reference count is 130 * initialized to one. 131 * @return `NULL` if memory allocation fails 132 */ 133 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_definite_string(void); 134 135 /** Creates a new indefinite string 136 * 137 * The chunks array is initialized to `NULL` and chunkcount to 0 138 * 139 * @return Reference to the new string item. The item's reference count is 140 * initialized to one. 141 * @return `NULL` if memory allocation fails 142 */ 143 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_indefinite_string(void); 144 145 /** Creates a new string and initializes it 146 * 147 * The `val` will be copied to a newly allocated block 148 * 149 * @param val A null-terminated UTF-8 string 150 * @return Reference to the new string item. The item's reference count is 151 * initialized to one. 152 * @return `NULL` if memory allocation fails 153 */ 154 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_string(const char *val); 155 156 /** Creates a new string and initializes it 157 * 158 * The `handle` will be copied to a newly allocated block 159 * 160 * @param val A UTF-8 string, at least @p `length` long (excluding the null 161 * byte) 162 * @param length Length (in bytes) of the string passed in @p `val`. 163 * @return Reference to the new string item. The item's reference count is 164 * initialized to one. 165 * @return `NULL` if memory allocation fails 166 */ 167 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_stringn(const char *val, 168 size_t length); 169 170 #ifdef __cplusplus 171 } 172 #endif 173 174 #endif // LIBCBOR_STRINGS_H 175