comparison: docs/Writerside/topics/properties.h.md
docs/Writerside/topics/properties.h.md
- changeset 1694
- a2757c6427cc
- parent 1603
- ffea41207599
equal
deleted
inserted
replaced
| 1693:c2d05cf1a062 | 1694:a2757c6427cc |
|---|---|
| 80 and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config). | 80 and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config). |
| 81 The line continuation symbol is set to `'\'`. | 81 The line continuation symbol is set to `'\'`. |
| 82 Note that leading spaces of a continuing line are ignored. | 82 Note that leading spaces of a continuing line are ignored. |
| 83 | 83 |
| 84 The actual parsing is an interleaving invocation of the `cxPropertiesFill()` (or `cxPropertiesFilln()`) and `cxPropertiesNext()` functions. | 84 The actual parsing is an interleaving invocation of the `cxPropertiesFill()` (or `cxPropertiesFilln()`) and `cxPropertiesNext()` functions. |
| 85 The `cxPropertiesFill()` function is a convenience function, that accepts UCX strings and normal zero-terminated C strings and behaves otherwise like `cxPropertiesFilln()`. | 85 The `cxPropertiesFill()` function is a convenience function that accepts UCX strings and normal zero-terminated C strings and behaves otherwise like `cxPropertiesFilln()`. |
| 86 | 86 |
| 87 Filling the input buffer is cost-free if there is no data already in the input buffer. | 87 Filling the input buffer is cost-free if there is no data already in the input buffer. |
| 88 In that case, the input buffer only stores the pointer to the original data without creating a copy. | 88 In that case, the input buffer only stores the pointer to the original data without creating a copy. |
| 89 Calling `cxPropertiesNext()` will return with `CX_PROPERTIES_NO_ERROR` (= zero) for each key/value-pair that is successfully parsed, | 89 Calling `cxPropertiesNext()` will return with `CX_PROPERTIES_NO_ERROR` (= zero) for each key/value-pair that is successfully parsed |
| 90 and stores the pointers and lengths for both the key and the value into the structures pointed to by the `key` and `value` arguments. | 90 and stores the pointers and lengths for both the key and the value into the structures pointed to by the `key` and `value` arguments. |
| 91 | 91 |
| 92 When all the data from the input buffer was successfully consumed, `cxPropertiesNext()` returns `CX_PROPERTIES_NO_DATA`. | 92 When all the data from the input buffer was successfully consumed, `cxPropertiesNext()` returns `CX_PROPERTIES_NO_DATA`. |
| 93 | 93 |
| 94 > This is all still free of any copies and allocations. | 94 > This is all still free of any copies and allocations. |
| 95 > That means, the pointers in `key` and `value` after `cxPropertiesNext()` returns will point into the input buffer. | 95 > That means, the pointers in `key` and `value` after `cxPropertiesNext()` returns will point into the input buffer. |
| 96 > If you intend to store the key and/or the value somewhere else, it is strongly recommended to create a copy with `cx_strdup()`, | 96 > If you intend to store the key and/or the value somewhere else, it is strongly recommended to create a copy with `cx_strdup()`, |
| 97 > because you will otherwise soon end up with a dangling pointer. | 97 > because you will otherwise soon end up with a dangling pointer. |
| 98 > {style="note"} | 98 > {style="note"} |
| 99 | 99 |
| 100 If `cxPropertiesNext()` returns `CX_PROPERTIES_INCOMPLETE_DATA` it means that the input buffer is exhausted, | 100 If `cxPropertiesNext()` returns `CX_PROPERTIES_INCOMPLETE_DATA`, the input buffer is exhausted, |
| 101 but the last line did not contain a full key/value pair. | 101 but the last line did not contain a full key/value pair. |
| 102 In that case, you can call `cxPropertiesFill()` again to add more data and continue with `cxPropertiesNext()`. | 102 In that case, you can call `cxPropertiesFill()` again to add more data and continue with `cxPropertiesNext()`. |
| 103 | 103 |
| 104 Note that adding more data to a non-empty input buffer will lead to an allocation, | 104 Note that adding more data to a non-empty input buffer will lead to an allocation, |
| 105 unless you specified some stack memory with `cxPropertiesUseStack()`. | 105 unless you specified some stack memory with `cxPropertiesUseStack()`. |
