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