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