ucx: comparison docs/Writerside/topics/list.h.md

-:189756516eaa
+:4407229bd944
 The `list.h` header defines a common interface for all list implementations.
 UCX already comes with two common list implementations ([linked list](linked_list.h.md) and [array list](array_list.h.md))
 that should cover most use cases.
-But if you feel the need to implement an own list, you will find instructions [below](#implement-own-list-structures).
+But if you feel the need to implement your own list, you will find the instructions [below](#implement-own-list-structures).
 ```C
 #include <cx/linked_list.h>
 CxList *cxLinkedListCreate(const CxAllocator *allocator,
 Array lists can be created with `cxArrayListCreate()` where the additional argument `initial_capacity` specifies for how many elements the underlying array shall be initially allocated.
 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.
 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.
-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.
+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.
 > When you create a list which is storing pointers and do not specify a compare function, `cx_cmp_ptr` will be used by default.
 > If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer.
 > While you *must not* insert elements into that list, you can safely access this list or create iterators.
 return 0;
 }
 }
 ```
-Also, just registering `regfree()` as destructor is not sufficient anymore, because the `regex_t` structure also needs to be freed.
+Also, just registering `regfree()` as destructor is not enough anymore, because the `regex_t` structure also needs to be freed.
 Therefore, we would need to wrap the calls to `regfree()` and `free()` into an own destructor, which we then register with the list.
 However, it should be clear by now that using `CX_STORE_POINTERS` is a bad choice for this use case to begin with.
 As a rule of thumb: if you allocate memory for an element that you immediately put into the list, consider storing the element directly.
 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`.
 This _should_ be done with [mutating iterators](iterator.h.md#mutating-iterators) only, but is also defined for normal iterators.
 If the list is storing pointers (cf. `cxCollectionStoresPointers()`), the pointer `elem` is directly added to the list.
 Otherwise, the contents at the location pointed to by `elem` are copied to the list's memory with the element size specified during creation of the list.
-On the other hand the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, and `cxListInsertSortedArray()`
+On the other hand, the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, and `cxListInsertSortedArray()`
-must always point to an array of elements to be added (i.e. either an array of pointers, or an array of actual elements).
+must always point to an array of elements to be added (i.e., either an array of pointers or an array of actual elements).
 A special requirement for `cxListInsertSortedArray()` is, that the `array` must already be sorted.
 > Implementations are required to optimize the insertion of a sorted array into a sorted list in linear time,
 > while inserting each element separately via `cxListInsertSorted()` may take quadratic time.
 size_t cxListSize(const CxList *list);
 ```
 The function `cxListAt()` accesses the element at the specified `index`.
 If the list is storing pointers (i.e. `cxCollectionStoresPointers()` returns `true`), the pointer at the specified index is directly returned.
-Otherwise, a pointer to element at the specified index is returned.
+Otherwise, a pointer to the element at the specified index is returned.
 If the index is out-of-bounds, the function returns `NULL`.
 The functions `cxListFirst()` and `cxListLast()` behave like `cxListAt()`,
 accessing the first or the last valid index, respectively, and returning `NULL` when the list is empty.
 The function `cxListSet()` allows you to modify elements at a specific index in the list.
 This function replaces the element at the specified `index` with the value pointed to by `elem`.
 If the list is storing values directly (not pointers), the contents at the memory location `elem` will be copied into the list.
 If the list is storing pointers, the pointer value itself will be stored.
 The function returns `0` on success and `1` if the index is out of bounds.
-On the other hand, `cxListFind()` searches for the element pointed to by `elem` by comparing each element in the list with the list`s compare function,
+On the other hand, `cxListFind()` searches for the element pointed to by `elem` by comparing each element in the list with the list's compare function,
 and returns the first index when the element was found.
 Otherwise, the function returns the list size.
 The function `cxListFindRemove()` behaves like `cxListFind()`, except that it also removes the first occurrence of the element from the list.
 This will _also_ call destructor functions, if specified, so take special care when you continue to use `elem`, or when the list is storing pointers and the element appears more than once in the list.
 Default UCX implementations of the list interface make use of [small buffer optimizations](install.md#small-buffer-optimizations) when swapping elements.
 > An invocation of `cxListSort` sets the `sorted` flag of the [collection](collection.h.md).
 > Implementations usually make use of this flag to optimize search operations, if possible.
-> For example the [array list](array_list.h.md) implementation will use binary search
+> For example, the [array list](array_list.h.md) implementation will use binary search
 > for `cxListFind()` and similar operations, when the list is sorted.
 ## Compare
 ```C
 int cxListCompare(const CxList *list, const CxList *other);
 ```
 Arbitrary lists can be compared element-wise with `cxListCompare()`, as long as the compare functions of both lists are equivalent.
-That means, you can compare an UCX [array list](array_list.h.md) with a [linked list](linked_list.h.md),
+That means you can compare an UCX [array list](array_list.h.md) with a [linked list](linked_list.h.md),
 and you could even compare lists that are storing pointers with lists that are not storing pointers.
-However, the optimized list-internal compare implementation is only used, when both the compare functions and the list classes are identical.
+However, the optimized list-internal compare implementation is only used when both the compare functions and the list classes are identical.
 Otherwise, `cxListCompare()` will behave as if you were iterating through both lists and manually comparing the elements.
 The return value of `cxListCompare()` is zero, if the lists are element-wise equivalent.
 If they are not, the non-zero return value equals the return value of the used compare function for the first pair of elements that are not equal.
 No matter with which function a `CxList` has been created, you can _always_ deallocate the entire memory with a call to `cxListFree()`.
 The effect is equivalent to invoking `cxListClear()` plus deallocating the memory for the list structure.
 That means, for each element in the list, the [destructor functions](collection.h.md#destructor-functions) are called before deallocating the list.
-When the list has been storing pointers, make sure that either another reference to the same memory exist in your program,
+When the list has been storing pointers, make sure that either another reference to the same memory exists in your program,
 or any of the destructor functions deallocates the memory.
 Otherwise, there is a risk of a memory leak.
 ## Implement own List Structures
 If you want to create your own list implementation, this is extremely easy.
-You just need to define a function for creating your list and assign a `cx_list_class` structure with the pointers to your implementation.
+You need to define a function for creating your list and assign a `cx_list_class` structure with the pointers to your implementation.
 Then you call the `cx_list_init()` helper function to initialize the collection sture.
 This also automatically adds support for `CX_STORE_POINTERS` to your list.
 ```C
 // define the class with pointers to your functions
 | `iterator`       | Creates an iterator starting at the specified index. The Boolean argument indicates whether iteration is supposed to traverse backwards.                                                                                                                                                                                   |
 > If you initialize your list with `cx_list_init()` you do not have to worry about making a
 > difference between storing pointers and storing elements, because your implementation will
 > be automatically wrapped.
-> This means, you only have to handle the one single case described above.
+> This means you only have to handle the one single case described above.
 ### Default Class Function Implementations
 If you are satisfied with some of the default implementations, you can use some pre-defined functions.
 Note, however, that those are not optimized for any specific list structure

Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/list.h.md

docs/Writerside/topics/list.h.md