comparison: ucx/cx/list.h
ucx/cx/list.h
- changeset 943
- 9b5948aa5b90
- parent 870
- e167cf006213
equal
deleted
inserted
replaced
| 942:488178e3e328 | 943:9b5948aa5b90 |
|---|---|
| 168 * Member function for reversing the order of the items. | 168 * Member function for reversing the order of the items. |
| 169 */ | 169 */ |
| 170 void (*reverse)(struct cx_list_s *list); | 170 void (*reverse)(struct cx_list_s *list); |
| 171 | 171 |
| 172 /** | 172 /** |
| 173 * Optional member function for changing the capacity. | |
| 174 * If the list does not support overallocation, this can be set to @c NULL. | |
| 175 */ | |
| 176 int (*change_capacity)(struct cx_list_s *list, size_t new_capacity); | |
| 177 | |
| 178 /** | |
| 173 * Member function for returning an iterator pointing to the specified index. | 179 * Member function for returning an iterator pointing to the specified index. |
| 174 */ | 180 */ |
| 175 struct cx_iterator_s (*iterator)(const struct cx_list_s *list, size_t index, bool backward); | 181 struct cx_iterator_s (*iterator)(const struct cx_list_s *list, size_t index, bool backward); |
| 176 }; | 182 }; |
| 177 | 183 |
| 959 * @param list the list that shall be freed | 965 * @param list the list that shall be freed |
| 960 */ | 966 */ |
| 961 CX_EXPORT void cxListFree(CxList *list); | 967 CX_EXPORT void cxListFree(CxList *list); |
| 962 | 968 |
| 963 | 969 |
| 970 /** | |
| 971 * Performs a deep clone of one list into another. | |
| 972 * | |
| 973 * If the destination list already contains elements, the cloned elements | |
| 974 * are appended to that list. | |
| 975 * | |
| 976 * @attention If the cloned elements need to be destroyed by a destructor | |
| 977 * function, you must make sure that the destination list also uses this | |
| 978 * destructor function. | |
| 979 * | |
| 980 * @param dst the destination list | |
| 981 * @param src the source list | |
| 982 * @param clone_func the clone function for the elements | |
| 983 * @param clone_allocator the allocator that is passed to the clone function | |
| 984 * @param data optional additional data that is passed to the clone function | |
| 985 * @retval zero when all elements were successfully cloned | |
| 986 * @retval non-zero when an allocation error occurred | |
| 987 * @see cxListCloneSimple() | |
| 988 */ | |
| 989 cx_attr_nonnull_arg(1, 2, 3) | |
| 990 CX_EXPORT int cxListClone(CxList *dst, const CxList *src, | |
| 991 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 992 | |
| 993 /** | |
| 994 * Clones elements from a list only if they are not present in another list. | |
| 995 * | |
| 996 * If the @p minuend does not contain duplicates, this is equivalent to adding | |
| 997 * the set difference to the destination list. | |
| 998 * | |
| 999 * This function is optimized for the case when both the @p minuend and the | |
| 1000 * @p subtrahend are sorted. | |
| 1001 * | |
| 1002 * @param dst the destination list | |
| 1003 * @param minuend the list to subtract elements from | |
| 1004 * @param subtrahend the elements that shall be subtracted | |
| 1005 * @param clone_func the clone function for the elements | |
| 1006 * @param clone_allocator the allocator that is passed to the clone function | |
| 1007 * @param data optional additional data that is passed to the clone function | |
| 1008 * @retval zero when the elements were successfully cloned | |
| 1009 * @retval non-zero when an allocation error occurred | |
| 1010 * @see cxListDifferenceSimple() | |
| 1011 */ | |
| 1012 cx_attr_nonnull_arg(1, 2, 3, 4) | |
| 1013 CX_EXPORT int cxListDifference(CxList *dst, | |
| 1014 const CxList *minuend, const CxList *subtrahend, | |
| 1015 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 1016 | |
| 1017 /** | |
| 1018 * Clones elements from a list only if they are also present in another list. | |
| 1019 * | |
| 1020 * This function is optimized for the case when both the @p src and the | |
| 1021 * @p other list are sorted. | |
| 1022 * | |
| 1023 * If the destination list already contains elements, the intersection is appended | |
| 1024 * to that list. | |
| 1025 * | |
| 1026 * @param dst the destination list | |
| 1027 * @param src the list to clone the elements from | |
| 1028 * @param other the list to check the elements for existence | |
| 1029 * @param clone_func the clone function for the elements | |
| 1030 * @param clone_allocator the allocator that is passed to the clone function | |
| 1031 * @param data optional additional data that is passed to the clone function | |
| 1032 * @retval zero when the elements were successfully cloned | |
| 1033 * @retval non-zero when an allocation error occurred | |
| 1034 * @see cxListIntersectionSimple() | |
| 1035 */ | |
| 1036 cx_attr_nonnull_arg(1, 2, 3, 4) | |
| 1037 CX_EXPORT int cxListIntersection(CxList *dst, const CxList *src, const CxList *other, | |
| 1038 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 1039 | |
| 1040 /** | |
| 1041 * Performs a deep clone of one list into another, skipping duplicates. | |
| 1042 * | |
| 1043 * This function is optimized for the case when both the @p src and the | |
| 1044 * @p other list are sorted. | |
| 1045 * In that case, the union will also be sorted. | |
| 1046 * | |
| 1047 * If the destination list already contains elements, the union is appended | |
| 1048 * to that list. In that case the destination is not necessarily sorted. | |
| 1049 * | |
| 1050 * @param dst the destination list | |
| 1051 * @param src the primary source list | |
| 1052 * @param other the other list, where elements are only cloned from | |
| 1053 * when they are not in @p src | |
| 1054 * @param clone_func the clone function for the elements | |
| 1055 * @param clone_allocator the allocator that is passed to the clone function | |
| 1056 * @param data optional additional data that is passed to the clone function | |
| 1057 * @retval zero when the elements were successfully cloned | |
| 1058 * @retval non-zero when an allocation error occurred | |
| 1059 * @see cxListUnionSimple() | |
| 1060 */ | |
| 1061 cx_attr_nonnull_arg(1, 2, 3, 4) | |
| 1062 CX_EXPORT int cxListUnion(CxList *dst, const CxList *src, const CxList *other, | |
| 1063 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 1064 | |
| 1065 /** | |
| 1066 * Performs a shallow clone of one list into another. | |
| 1067 * | |
| 1068 * This function uses the default allocator, if needed, and performs | |
| 1069 * shallow clones with @c memcpy(). | |
| 1070 * | |
| 1071 * If the destination list already contains elements, the cloned elements | |
| 1072 * are appended to that list. | |
| 1073 * | |
| 1074 * @attention If the cloned elements need to be destroyed by a destructor | |
| 1075 * function, you must make sure that the destination list also uses this | |
| 1076 * destructor function. | |
| 1077 * | |
| 1078 * @param dst the destination list | |
| 1079 * @param src the source list | |
| 1080 * @retval zero when all elements were successfully cloned | |
| 1081 * @retval non-zero when an allocation error occurred | |
| 1082 * @see cxListClone() | |
| 1083 */ | |
| 1084 cx_attr_nonnull | |
| 1085 CX_EXPORT int cxListCloneSimple(CxList *dst, const CxList *src); | |
| 1086 | |
| 1087 /** | |
| 1088 * Clones elements from a list only if they are not present in another list. | |
| 1089 * | |
| 1090 * This function uses the default allocator, if needed, and performs | |
| 1091 * shallow clones with @c memcpy(). | |
| 1092 * | |
| 1093 * If the @p minuend does not contain duplicates, this is equivalent to adding | |
| 1094 * the set difference to the destination list. | |
| 1095 * | |
| 1096 * This function is optimized for the case when both the @p minuend and the | |
| 1097 * @p subtrahend are sorted. | |
| 1098 * | |
| 1099 * @param dst the destination list | |
| 1100 * @param minuend the list to subtract elements from | |
| 1101 * @param subtrahend the elements that shall be subtracted | |
| 1102 * @retval zero when the elements were successfully cloned | |
| 1103 * @retval non-zero when an allocation error occurred | |
| 1104 * @see cxListDifference() | |
| 1105 */ | |
| 1106 cx_attr_nonnull | |
| 1107 CX_EXPORT int cxListDifferenceSimple(CxList *dst, | |
| 1108 const CxList *minuend, const CxList *subtrahend); | |
| 1109 | |
| 1110 /** | |
| 1111 * Clones elements from a list only if they are also present in another list. | |
| 1112 * | |
| 1113 * This function uses the default allocator, if needed, and performs | |
| 1114 * shallow clones with @c memcpy(). | |
| 1115 * | |
| 1116 * This function is optimized for the case when both the @p src and the | |
| 1117 * @p other list are sorted. | |
| 1118 * | |
| 1119 * If the destination list already contains elements, the intersection is appended | |
| 1120 * to that list. | |
| 1121 * | |
| 1122 * @param dst the destination list | |
| 1123 * @param src the list to clone the elements from | |
| 1124 * @param other the list to check the elements for existence | |
| 1125 * @retval zero when the elements were successfully cloned | |
| 1126 * @retval non-zero when an allocation error occurred | |
| 1127 * @see cxListIntersection() | |
| 1128 */ | |
| 1129 cx_attr_nonnull | |
| 1130 CX_EXPORT int cxListIntersectionSimple(CxList *dst, const CxList *src, const CxList *other); | |
| 1131 | |
| 1132 /** | |
| 1133 * Performs a deep clone of one list into another, skipping duplicates. | |
| 1134 * | |
| 1135 * This function uses the default allocator, if needed, and performs | |
| 1136 * shallow clones with @c memcpy(). | |
| 1137 * | |
| 1138 * This function is optimized for the case when both the @p src and the | |
| 1139 * @p other list are sorted. | |
| 1140 * In that case, the union will also be sorted. | |
| 1141 * | |
| 1142 * If the destination list already contains elements, the union is appended | |
| 1143 * to that list. In that case the destination is not necessarily sorted. | |
| 1144 * | |
| 1145 * @param dst the destination list | |
| 1146 * @param src the primary source list | |
| 1147 * @param other the other list, where elements are only cloned from | |
| 1148 * when they are not in @p src | |
| 1149 * @retval zero when the elements were successfully cloned | |
| 1150 * @retval non-zero when an allocation error occurred | |
| 1151 * @see cxListUnion() | |
| 1152 */ | |
| 1153 cx_attr_nonnull | |
| 1154 CX_EXPORT int cxListUnionSimple(CxList *dst, const CxList *src, const CxList *other); | |
| 1155 | |
| 1156 /** | |
| 1157 * Asks the list to reserve enough memory for a given total number of elements. | |
| 1158 * | |
| 1159 * List implementations are free to choose if reserving memory upfront makes | |
| 1160 * sense. | |
| 1161 * For example, array-based implementations usually do support reserving memory | |
| 1162 * for additional elements while linked lists usually don't. | |
| 1163 * | |
| 1164 * @note When the requested capacity is smaller than the current size, | |
| 1165 * this function returns zero without performing any action. | |
| 1166 * | |
| 1167 * @param list the list | |
| 1168 * @param capacity the expected total number of elements | |
| 1169 * @retval zero on success or when overallocation is not supported | |
| 1170 * @retval non-zero when an allocation error occurred | |
| 1171 * @see cxListShrink() | |
| 1172 */ | |
| 1173 cx_attr_nonnull | |
| 1174 CX_EXPORT int cxListReserve(CxList *list, size_t capacity); | |
| 1175 | |
| 1176 /** | |
| 1177 * Advises the list to free any overallocated memory. | |
| 1178 * | |
| 1179 * Lists that do not support overallocation simply return zero. | |
| 1180 * | |
| 1181 * This function usually returns zero, except for very special and custom | |
| 1182 * list and/or allocator implementations where freeing memory can fail. | |
| 1183 * | |
| 1184 * @param list the list | |
| 1185 * @return usually zero | |
| 1186 */ | |
| 1187 cx_attr_nonnull | |
| 1188 CX_EXPORT int cxListShrink(CxList *list); | |
| 1189 | |
| 964 #ifdef __cplusplus | 1190 #ifdef __cplusplus |
| 965 } // extern "C" | 1191 } // extern "C" |
| 966 #endif | 1192 #endif |
| 967 | 1193 |
| 968 #endif // UCX_LIST_H | 1194 #endif // UCX_LIST_H |
