xine-lib: xine-lib-1.2.13/include/xine/sorted_array.h Source File

xine-lib 1.2.13-20230125hg15249

sorted_array.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2000-2022 the xine project
3 *
4 * This file is part of xine, a free video player.
5 *
6 * xine is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * xine 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 General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA
19 *
20 * Sorted array which grows automatically when you add elements.
21 * A binary search is used to find the position of a new element.
22 *
23 * Example:
24 * Let's create de comparison method for integers:
25 *
26 * int int_comparator(void *a, void *b) {
27 * if ((int)a < (int)b) {
28 * return -1;
29 * } else if ((int)a == (int)b) {
30 * return 0;
31 * } else {
32 * return 1;
33 * }
34 * }
35 *
36 * Create a sorted array for integers:
37 * xine_sarray_t *sarray = xine_sarray_new(10, int_comparator);
38 *
39 * Add elements:
40 * xine_sarray_add(sarray, (void*)4);
41 * xine_sarray_add(sarray, (void*)28);
42 * xine_sarray_add(sarray, (void*)7);
43 *
44 * Find an element:
45 * int pos = xine_sarray_binary_search(sarray, (void*)7);
46 * if (pos >= 0)
47 * FOUND
48 * else
49 * NOT FOUND
50 *
51 * Delete the array:
52 * xine_sarray_delete(sarray);
53 */
54#ifndef XINE_SORTED_ARRAY_H
55#define XINE_SORTED_ARRAY_H
56
57#include <stddef.h> /* size_t */
58#include <xine/attributes.h>
59
60/* version */
61#define XINE_SARRAY 3
62
63/* Array type */
64 typedef struct xine_sarray_s xine_sarray_t;
65
66/* Array element comparator */
67 typedef int (*xine_sarray_comparator_t) (void *item1, void *item2);
68/* Array element hash value */
69 typedef unsigned int (*xine_sarray_hash_func_t) (void *item);
70
71/* Constructor */
72 xine_sarray_t *xine_sarray_new(size_t initial_size, xine_sarray_comparator_t comparator) XINE_MALLOC XINE_PROTECTED;
73
74/* Destructor */
75void xine_sarray_delete(xine_sarray_t *sarray) XINE_PROTECTED;
76
77/* XINE_SARRAY >= 3: add optional hash function that returns 0 ... (hash_size - 1).
78 * Items will be sorted by ascending hash value first, then by comparator within the same hash value.
79 * NOTE: hash_size is currently limited to 4096. */
80void xine_sarray_set_hash (xine_sarray_t *sarray, xine_sarray_hash_func_t hash_func, unsigned int hash_size) XINE_PROTECTED;
81
82/* Set mode */
83/* For both add() and binary_search(): if there are multiple matching indices,
84 * select 1 of them randomly. That is, the order of matches does not matter, just be fast. */
85#define XINE_SARRAY_MODE_DEFAULT 0x00000000
86/* if present, select the first match, or add brfore that. */
87#define XINE_SARRAY_MODE_FIRST 0x80000000
88/* if present, select the last match, or add after that. */
89#define XINE_SARRAY_MODE_LAST 0x40000000
90/* For add(): if there is a match already, dont add another copy,
91 * and return ~(found_index) instead. */
92#define XINE_SARRAY_MODE_UNIQUE 0x20000000
93void xine_sarray_set_mode (xine_sarray_t *sarray, unsigned int mode) XINE_PROTECTED;
94
95/* Returns the number of element stored in the array */
96size_t xine_sarray_size(const xine_sarray_t *sarray) XINE_PROTECTED;
97
98/* Removes all elements from an array */
99void xine_sarray_clear(xine_sarray_t *sarray) XINE_PROTECTED;
100
101/* Adds the element into the array
102 Returns the insertion position */
103int xine_sarray_add(xine_sarray_t *sarray, void *value) XINE_PROTECTED;
104
105/* Removes one element from an array at the position specified.
106 * XINE_SARRAY >= 4: return the removed data ptr. */
107void *xine_sarray_remove (xine_sarray_t *sarray, unsigned int position) XINE_PROTECTED;
108
109/* Removes one element from an array by user pointer.
110 * Return the index it was found at, or ~0. */
111int xine_sarray_remove_ptr (xine_sarray_t *sarray, void *ptr) XINE_PROTECTED;
112
113/* Get the element at the position specified */
114void *xine_sarray_get(xine_sarray_t *sarray, unsigned int position) XINE_PROTECTED;
115
116/* Returns the index of the search key, if it is contained in the list.
117 Otherwise, (-(insertion point) - 1) or ~(insertion point).
118 The insertion point is defined as the point at which the key would be
119 inserted into the array. */
120int xine_sarray_binary_search(xine_sarray_t *sarray, void *key) XINE_PROTECTED;
121
122/* XINE_SARRAY >= 2: update the location of an existing entry,
123 * eg from a stack dummy to a neqly allocted real object.
124 * new_ptr == NULL does the same as xine_sarray_remove ().
125 * WARNING: this does _not_ recheck the sort order. */
126void xine_sarray_move_location (xine_sarray_t *sarray, void *new_ptr, unsigned int position) XINE_PROTECTED;
127
128#endif
129
attributes.h
XINE_MALLOC
#define XINE_MALLOC
Definition attributes.h:141
XINE_PROTECTED
#define XINE_PROTECTED
Definition attributes.h:75
xine_sarray_set_mode
void xine_sarray_set_mode(xine_sarray_t *sarray, unsigned int mode)
Definition sorted_array.c:261
xine_sarray_binary_search
int xine_sarray_binary_search(xine_sarray_t *sarray, void *key)
Definition sorted_array.c:176
xine_sarray_remove_ptr
int xine_sarray_remove_ptr(xine_sarray_t *sarray, void *ptr)
Definition sorted_array.c:335
xine_sarray_get
void * xine_sarray_get(xine_sarray_t *sarray, unsigned int position)
Definition sorted_array.c:271
xine_sarray_set_hash
void xine_sarray_set_hash(xine_sarray_t *sarray, xine_sarray_hash_func_t hash_func, unsigned int hash_size)
Definition sorted_array.c:237
xine_sarray_clear
void xine_sarray_clear(xine_sarray_t *sarray)
Definition sorted_array.c:279
xine_sarray_move_location
void xine_sarray_move_location(xine_sarray_t *sarray, void *new_ptr, unsigned int position)
Definition sorted_array.c:294
xine_sarray_comparator_t
int(* xine_sarray_comparator_t)(void *item1, void *item2)
Definition sorted_array.h:67
xine_sarray_size
size_t xine_sarray_size(const xine_sarray_t *sarray)
Definition sorted_array.c:257
xine_sarray_delete
void xine_sarray_delete(xine_sarray_t *sarray)
Definition sorted_array.c:228
xine_sarray_hash_func_t
unsigned int(* xine_sarray_hash_func_t)(void *item)
Definition sorted_array.h:69
xine_sarray_remove
void * xine_sarray_remove(xine_sarray_t *sarray, unsigned int position)
Definition sorted_array.c:313
xine_sarray_add
int xine_sarray_add(xine_sarray_t *sarray, void *value)
Definition sorted_array.c:410
xine_sarray_new
xine_sarray_t * xine_sarray_new(size_t initial_size, xine_sarray_comparator_t comparator)
Definition sorted_array.c:191
xine_sarray_s
Definition sorted_array.c:35
xine_sarray_s::comparator
xine_sarray_comparator_t comparator
Definition sorted_array.c:39
xine_sarray_s::value
unsigned int value
Definition sorted_array.c:55
mode
enable disable number of frames of telecine pattern sync required before mode change make frames evenly spaced for film mode(24 fps)" ) PARAM_ITEM( POST_PARAM_TYPE_BOOL
key
char key[16]
Definition xine_speex_decoder.c:94