deimos.cbor.strings source code

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