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[borrow] 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[borrow] 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[borrow] 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[borrow] 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[borrow] A definite string 66 * @return The address of the underlying string. `NULL` if no data have been 67 * 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[borrow] 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[borrow] 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[borrow] 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[borrow] An indefinite string 116 * @param item[incref] A definite string 117 * @return true on success. false on realloc failure. In that case, the refcount 118 * of `chunk` is not increased and the `item` is left intact. 119 */ 120 _CBOR_NODISCARD CBOR_EXPORT bool cbor_string_add_chunk(cbor_item_t *item, 121 cbor_item_t *chunk); 122 123 /** Creates a new definite string 124 * 125 * The handle is initialized to `NULL` and length to 0 126 * 127 * @return **new** definite string. `NULL` on malloc failure. 128 */ 129 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_definite_string(void); 130 131 /** Creates a new indefinite string 132 * 133 * The chunks array is initialized to `NULL` and chunkcount to 0 134 * 135 * @return **new** indefinite string. `NULL` on malloc failure. 136 */ 137 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_indefinite_string(void); 138 139 /** Creates a new string and initializes it 140 * 141 * The `val` will be copied to a newly allocated block 142 * 143 * @param val A null-terminated UTF-8 string 144 * @return A **new** string with content `handle`. `NULL` on malloc failure. 145 */ 146 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_string(const char *val); 147 148 /** Creates a new string and initializes it 149 * 150 * The `handle` will be copied to a newly allocated block 151 * 152 * @param val A UTF-8 string, at least \p length long (excluding the null byte) 153 * @return A **new** string with content `handle`. `NULL` on malloc failure. 154 */ 155 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_stringn(const char *val, 156 size_t length); 157 158 #ifdef __cplusplus 159 } 160 #endif 161 162 #endif // LIBCBOR_STRINGS_H 163