VLC 4.0.0-dev
Loading...
Searching...
No Matches
vlc_diffutil.h
Go to the documentation of this file.
1/******************************************************************************
2 * vlc_diffutil.h
3 ******************************************************************************
4 * Copyright (C) 2022 VLC authors and VideoLAN
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU Lesser General Public License as published by
8 * the Free Software Foundation; either version 2.1 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with this program; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19 *****************************************************************************/
20#ifndef VLC_DIFFUTIL_H
21#define VLC_DIFFUTIL_H
22
23#include <vlc_common.h>
24#include <vlc_vector.h>
25
26/**
27 * this structure defines callback to access and compare elements from
28 * the old and the new list
29 */
30typedef struct {
31 /// return the size of the old list @a list
32 uint32_t (*getOldSize)(const void* list);
33 /// return the size of the new list @a list
34 uint32_t (*getNewSize)(const void* list);
35 /// compare 2 elements
36 bool (*isSame)(const void* listOld, uint32_t oldIndex, const void* listNew, uint32_t newIndex);
38
39typedef struct {
40 /**
41 * notify that the item from @a listNew at position @a posNew is inserted in list @a listOld at position @a posOld
42 *
43 * @param opaque user data from function vlc_diffutil_walk_snake
44 * @param listOld pointer to the old model
45 * @param posOld position of the element inserted in the old model (before removal)
46 * @param listNew pointer to the new model
47 * @param posNew position of the element inserted in the new model
48 */
49 void (*insert)(void* opaque, const void* listOld, uint32_t posOld, const void* listNew, uint32_t posNew);
50 /**
51 * notify that the item from @a listOld at position @a posOld is removed
52 * @param opaque user data from function vlc_diffutil_walk_snake
53 * @param listOld pointer to the old model
54 * @param posOld position of the element removed in the old model
55 * @param listNew pointer to the new model
56 * @param posNew position of the element removed in the new model (before removal)
57 */
58 void (*remove)(void* opaque, const void* listOld, uint32_t posOld, const void* listNew, uint32_t posNew);
59 /**
60 * notify that the item as @a posOld from the old list @a listOld is unchanged, the respective item
61 * position in the new list is at the position @a posNew in @a listNew
62 */
63 void (*equal)(void* opaque, const void* listOld, uint32_t posOld, const void* listNew, uint32_t posNew);
65
69 ///items have been added to the list
71 ///items have been removed from the list
73 ///items have been moved within the list
75 ///current change should be ignored
77};
78
79
80/**
81 * The data positioned at newModel[ y ] is inserted at position index
82 * in the current model.
83 *
84 * @code
85 * model = "abcdefg"
86 * newModel[3] = 'X'
87 * after operation insert(y=3, index = 3), model will be
88 * model = "abcXdefg"
89 * @endcode
90 */
92 /// data position in the old model
93 uint32_t x;
94 /// data position in the new model
95 uint32_t y;
96 /// insertion position in the updated model
97 uint32_t index;
98};
99
100
101/**
102 * The data positioned at oldModel[ y ] is removed at position index
103 * in the current model.
104 *
105 * @code
106 * model = "abCdefg"
107 * oldModel[4] = 'C'
108 * after operation remove(x=4, index = 2), model will be
109 * model = "abdefg"
110 * @endcode
111 */
112struct vlc_diffutil_remove {
113 /// data position in the old model
114 uint32_t x;
115 /// data position in the new model
116 uint32_t y;
117 /// removal position in the updated model
118 uint32_t index;
120
121
122/**
123 * Moves the data from position model[ from ] to model[ to ]
124 * the data is available either at newModel[ y ] or oldModel[ x ]
125 *
126 * the positions @a from and @a to are given in the referenrial before the operation
127 *
128 * @code
129 * model = "aBCdefg"
130 * after operation move(from=1, to=5, count=2), model will be
131 * model = "adeCBfg"
132 * @endcode
133 */
134struct vlc_diffutil_move {
135 /// move origin
136 uint32_t from;
137 /// move destination
138 uint32_t to;
139 /// data position in the old model
140 uint32_t x;
141 /// data position in the new model
142 uint32_t y;
144
145
146
147/**
148 * represent a change to the model, each change assumes that previous changes
149 * have already been applied
150 *
151 * for instance with a model "aBcDef", the operations [remove(index=1, count=1), remove(index=2, count=1)]
152 * will result in "acef" (with "acDef" as intermediary step)
153 */
154typedef struct {
155 union {
156 struct vlc_diffutil_insert insert;
157 struct vlc_diffutil_remove remove;
158 struct vlc_diffutil_move move;
159 } op;
161 /// type of change operation
162 enum vlc_diffutil_op_type type;
164 /// number of elements to be inserted/removed/moved
165 uint32_t count;
167
168typedef struct VLC_VECTOR(vlc_diffutil_change_t) vlc_diffutil_changelist_t;
171 /// try to transform an insertion with a matching suppression into a move operation
173 /**
174 * aggregate similar consecutive operations into a single operation
175 * for instance this:
176 * [{INSERT, i=5}{INSERT, x=6}{REMOVE, i=10}{REMOVE, i=10}{REMOVE, i=10}]
177 * would be transformed into:
178 * [{INSERT, i=5, count=2}{REMOVE, i=10, count=3}]
179 */
182
183/**
184 * vlc_diffutil_build_snake compute a diff model
185 * between the @a dataOld model and the @a dataNew model. This model can be
186 * processed manually using vlc_diffutil_walk_snake or translated into a change list using
187 * vlc_diffutil_build_change_list
188 *
189 * @param diffOp callback to compare the elements from the old and new model
190 * @param dataOld old model
191 * @param dataNew new model
192 * @return the diff model, NULL on error
193 */
194VLC_API struct diffutil_snake_t* vlc_diffutil_build_snake(const vlc_diffutil_callback_t* diffOp, const void* dataOld, const void* dataNew);
195
196/// free the snake created by vlc_diffutil_build_snake
198
199/**
200 * iterate over the changelist and callback user on each operation (keep/insert/remove)
201 *
202 * @param snake the snake created with vlc_diffutil_build_snake
203 * @param snakeOp snake callback
204 * @param cbData user data for snake callbacks
205 * @param diffOp callbacks used in vlc_diffutil_build_snake
206 * @param dataOld old model
207 * @param dataNew new model
208 * @return false on error
209 *
210 * @warning @a dataOld and @a dataNew should not be altered during the operation
211 */
213 const diffutil_snake_t* snake,
214 const vlc_diffutil_snake_callback_t* snakeOp, void* cbData,
215 const vlc_diffutil_callback_t* diffOp, const void* dataOld, const void* dataNew);
216
217/**
218 * vlc_diffutil_build_change_list creates a list of changes to apply to transform @a dataOld into @a dataNew
219 *
220 * @param snake the snake created with vlc_diffutil_build_snake
221 * @param diffOp callbacks used in vlc_diffutil_build_snake
222 * @param dataOld old model
223 * @param dataNew new model
224 * @param flags vlc_diffutil_result_flag flags
225 * @return the list of changes, NULL on error
226 */
228 const struct diffutil_snake_t* snake,
229 const vlc_diffutil_callback_t* diffOp, const void* dataOld, const void* dataNew,
230 int flags);
231
232/// free the changelist created by vlc_diffutil_build_change_list
234
235
236#endif // VLC_DIFFUTIL_H
struct vlc_param ** list
Definition core.c:402
size_t count
Definition core.c:403
void vlc_diffutil_free_snake(diffutil_snake_t *snake)
free the snake created by vlc_diffutil_build_snake
Definition diffutil.c:300
void vlc_diffutil_free_change_list(vlc_diffutil_changelist_t *changelist)
free the changelist created by vlc_diffutil_build_change_list
Definition diffutil.c:612
diffutil_snake_t * vlc_diffutil_build_snake(const vlc_diffutil_callback_t *diffOp, const void *dataOld, const void *dataNew)
vlc_diffutil_build_snake compute a diff model between the dataOld model and the dataNew model.
Definition diffutil.c:248
vlc_diffutil_changelist_t * vlc_diffutil_build_change_list(const diffutil_snake_t *snake, const vlc_diffutil_callback_t *diffOp, const void *dataOld, const void *dataNew, int flags)
Definition diffutil.c:577
bool vlc_diffutil_walk_snake(const diffutil_snake_t *snake, const vlc_diffutil_snake_callback_t *snakeOp, void *cbData, const vlc_diffutil_callback_t *diffOp, const void *dataOld, const void *dataNew)
iterate over the changelist and callback user on each operation (keep/insert/remove)
Definition diffutil.c:309
#define VLC_API
Definition fourcc_gen.c:31
Definition diffutil.c:34
this structure defines callback to access and compare elements from the old and the new list
Definition vlc_diffutil.h:31
represent a change to the model, each change assumes that previous changes have already been applied
Definition vlc_diffutil.h:155
uint32_t count
number of elements to be inserted/removed/moved
Definition vlc_diffutil.h:166
enum vlc_diffutil_op_type type
type of change operation
Definition vlc_diffutil.h:163
Definition vlc_diffutil.h:169
The data positioned at newModel[ y ] is inserted at position index in the current model.
Definition vlc_diffutil.h:92
uint32_t y
data position in the new model
Definition vlc_diffutil.h:96
uint32_t index
insertion position in the updated model
Definition vlc_diffutil.h:98
uint32_t x
data position in the old model
Definition vlc_diffutil.h:94
Moves the data from position model[ from ] to model[ to ] the data is available either at newModel[ y...
Definition vlc_diffutil.h:135
uint32_t x
data position in the old model
Definition vlc_diffutil.h:141
uint32_t from
move origin
Definition vlc_diffutil.h:137
uint32_t y
data position in the new model
Definition vlc_diffutil.h:143
uint32_t to
move destination
Definition vlc_diffutil.h:139
The data positioned at oldModel[ y ] is removed at position index in the current model.
Definition vlc_diffutil.h:113
uint32_t index
removal position in the updated model
Definition vlc_diffutil.h:119
uint32_t y
data position in the new model
Definition vlc_diffutil.h:117
uint32_t x
data position in the old model
Definition vlc_diffutil.h:115
Definition vlc_diffutil.h:40
This file is a collection of common definitions and types.
vlc_diffutil_op_type
Definition vlc_diffutil.h:69
@ VLC_DIFFUTIL_OP_MOVE
items have been moved within the list
Definition vlc_diffutil.h:75
@ VLC_DIFFUTIL_OP_INSERT
items have been added to the list
Definition vlc_diffutil.h:71
@ VLC_DIFFUTIL_OP_REMOVE
items have been removed from the list
Definition vlc_diffutil.h:73
@ VLC_DIFFUTIL_OP_IGNORE
current change should be ignored
Definition vlc_diffutil.h:77
vlc_diffutil_result_flag
Definition vlc_diffutil.h:171
@ VLC_DIFFUTIL_RESULT_AGGREGATE
aggregate similar consecutive operations into a single operation for instance this: [{INSERT,...
Definition vlc_diffutil.h:181
@ VLC_DIFFUTIL_RESULT_MOVE
try to transform an insertion with a matching suppression into a move operation
Definition vlc_diffutil.h:173
This provides convenience helpers for vectors.