comparison: docs/Writerside/topics/list.h.md
docs/Writerside/topics/list.h.md
- changeset 1243
- 13e15cd529ae
- parent 1240
- c5924c781372
equal
deleted
inserted
replaced
| 1242:bbb734f73392 | 1243:13e15cd529ae |
|---|---|
| 33 If `CX_STORE_POINTERS` is used as `elem_size`, the actual element size will be `sizeof(void*)` and the list will behave slightly differently when accessing elements. | 33 If `CX_STORE_POINTERS` is used as `elem_size`, the actual element size will be `sizeof(void*)` and the list will behave slightly differently when accessing elements. |
| 34 Lists that are storing pointers will always return the stored pointer directly, instead of returning a pointer into the list's memory, thus saving you from unnecessary dereferencing. | 34 Lists that are storing pointers will always return the stored pointer directly, instead of returning a pointer into the list's memory, thus saving you from unnecessary dereferencing. |
| 35 Conversely, when adding elements to the list, the pointers you specify (e.g. in `cxListAdd()` or `cxListInsert()`) are directly added to the list, instead of copying the contents pointed to by the argument. | 35 Conversely, when adding elements to the list, the pointers you specify (e.g. in `cxListAdd()` or `cxListInsert()`) are directly added to the list, instead of copying the contents pointed to by the argument. |
| 36 | 36 |
| 37 > When you create a list which is storing pointers and do not specify a compare function, `cx_cmp_ptr` will be used by default. | 37 > When you create a list which is storing pointers and do not specify a compare function, `cx_cmp_ptr` will be used by default. |
| 38 | |
| 39 > If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer. | |
| 40 > While you *must not* insert elements into that list, you can safely access this list or create iterators. | |
| 41 > This allows you to write clean code without checking for `NULL`-pointer everywhere. | |
| 42 > You still need to make sure that the placeholder is replaced with an actual list before inserting elements. | |
| 38 | 43 |
| 39 ## Example | 44 ## Example |
| 40 | 45 |
| 41 In the following example we create a linked-list of regular expressions for filtering data. | 46 In the following example we create a linked-list of regular expressions for filtering data. |
| 42 | 47 |
| 98 Also, just registering `regfree()` as destructor is not sufficient anymore, because the `regex_t` structure also needs to be freed. | 103 Also, just registering `regfree()` as destructor is not sufficient anymore, because the `regex_t` structure also needs to be freed. |
| 99 Therefore, we would need to wrap the calls to `regfree()` and `free()` into an own destructor, which we then register with the list. | 104 Therefore, we would need to wrap the calls to `regfree()` and `free()` into an own destructor, which we then register with the list. |
| 100 However, it should be clear by now that using `CX_STORE_POINTERS` is a bad choice for this use case to begin with. | 105 However, it should be clear by now that using `CX_STORE_POINTERS` is a bad choice for this use case to begin with. |
| 101 | 106 |
| 102 As a rule of thumb: if you allocate memory for an element that you immediately put into the list, consider storing the element directly. | 107 As a rule of thumb: if you allocate memory for an element that you immediately put into the list, consider storing the element directly. |
| 103 And if you are getting pointers to already allocated memory from somewhere else, and you just want to organize those elements in a list, then consider using `CX_STORE_POINTERS`. | 108 And if you are getting pointers to already allocated memory from somewhere else, and you just want to organize those elements in a list, then consider using `CX_STORE_POINTERS`. |
| 104 | |
| 105 > If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer. | |
| 106 > While you *must not* insert elements into that list, you can safely access this list or create iterators. | |
| 107 > This allows you to write clean code without checking for `NULL`-pointer everywhere. | |
| 108 > You still need to make sure that the placeholder is replaced with an actual list before inserting elements. | |
| 109 | 109 |
| 110 ## Insert | 110 ## Insert |
| 111 | 111 |
| 112 ```C | 112 ```C |
| 113 #include <cx/list.h> | 113 #include <cx/list.h> |
