/[public]/psiconv/trunk/lib/psiconv/list.h
ViewVC logotype

Diff of /psiconv/trunk/lib/psiconv/list.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 70 Revision 196
1/* 1/*
2 list.h - Part of psiconv, a PSION 5 file formats converter 2 list.h - Part of psiconv, a PSION 5 file formats converter
3 Copyright (c) 1999, 2000 Frodo Looijaard <frodol@dds.nl> 3 Copyright (c) 1999-2004 Frodo Looijaard <frodol@dds.nl>
4 4
5 This program is free software; you can redistribute it and/or modify 5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by 6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2 of the License, or 7 the Free Software Foundation; either version 2 of the License, or
8 (at your option) any later version. 8 (at your option) any later version.
… …
24#define PSICONV_LIST_H 24#define PSICONV_LIST_H
25 25
26#include <stddef.h> 26#include <stddef.h>
27#include <stdio.h> 27#include <stdio.h>
28 28
29#include <psiconv/general.h>
30
29#ifdef __cplusplus 31#ifdef __cplusplus
30extern "C" { 32extern "C" {
31#endif /* __cplusplus */ 33#endif /* __cplusplus */
32 34
33/* Always use psiconv_list, never struct psiconv_list */ 35/* Always use psiconv_list, never struct psiconv_list */
… …
38 as its argument. Always compute it with a sizeof() expression, just to be 40 as its argument. Always compute it with a sizeof() expression, just to be
39 safe. The returned list is empty. 41 safe. The returned list is empty.
40 If there is not enough memory available, NULL is returned. You should 42 If there is not enough memory available, NULL is returned. You should
41 always test for this explicitely, because the other functions do not 43 always test for this explicitely, because the other functions do not
42 like a psiconv_list argument that is equal to NULL */ 44 like a psiconv_list argument that is equal to NULL */
43extern psiconv_list psiconv_list_new(int element_size); 45extern psiconv_list psiconv_list_new(size_t element_size);
44 46
45/* This frees the list. If elements contain pointers that need to be freed 47/* This frees the list. If elements contain pointers that need to be freed
46 separately, call list_free_el below. */ 48 separately, call list_free_el below. */
47extern void psiconv_list_free(psiconv_list l); 49extern void psiconv_list_free(psiconv_list l);
48 50
… …
50 Note that you should *not* do 'free(el)' at any time; that is taken care of 52 Note that you should *not* do 'free(el)' at any time; that is taken care of
51 automatically. */ 53 automatically. */
52extern void psiconv_list_free_el(psiconv_list l, void free_el(void *el)); 54extern void psiconv_list_free_el(psiconv_list l, void free_el(void *el));
53 55
54/* Return the number of allocated elements */ 56/* Return the number of allocated elements */
55extern int psiconv_list_length(const psiconv_list l); 57extern psiconv_u32 psiconv_list_length(const psiconv_list l);
56 58
57/* Return 1 if the list is empty, 0 if not */ 59/* Return 1 if the list is empty, 0 if not */
58extern int psiconv_list_is_empty(const psiconv_list l); 60extern int psiconv_list_is_empty(const psiconv_list l);
61
62/* Empty a list. Note this does not reclaim any memory space! */
63extern void psiconv_list_empty(psiconv_list l);
59 64
60/* Get an element from the list, and return a pointer to it. Note: you can 65/* Get an element from the list, and return a pointer to it. Note: you can
61 directly modify this element, but be careful not to write beyond the 66 directly modify this element, but be careful not to write beyond the
62 element memory space. 67 element memory space.
63 If indx is out of range, NULL is returned. */ 68 If indx is out of range, NULL is returned. */
64extern void * psiconv_list_get(const psiconv_list l, unsigned int indx); 69extern void * psiconv_list_get(const psiconv_list l, psiconv_u32 indx);
65 70
66/* Add an element at the end of the list. The element is copied from the 71/* Add an element at the end of the list. The element is copied from the
67 supplied element. Of course, this does not help if the element contains 72 supplied element. Of course, this does not help if the element contains
68 pointers. 73 pointers.
69 As the lists extends itself, it may be necessary to allocate new 74 As the lists extends itself, it may be necessary to allocate new
70 memory. If this fails, a negative error-code is returned. If everything, 75 memory. If this fails, a negative error-code is returned. If everything,
71 succeeds, 0 is returned. */ 76 succeeds, 0 is returned. */
72extern int psiconv_list_add(psiconv_list l, const void *el); 77extern int psiconv_list_add(psiconv_list l, const void *el);
78
79/* Remove the last element from the list, and copy it to el. Note that
80 this will not reduce the amount of space reserved for the list.
81 An error code is returned, which will be 0 zero if everything
82 succeeded. It is your own responsibility to make sure enough
83 space is allocated to el. */
84extern int psiconv_list_pop(psiconv_list l, void *el);
85
86/* Replace an element within the list. The element is copied from the
87 supplied element. Fails if you try to write at or after the end of
88 the list. */
89extern int psiconv_list_replace(psiconv_list l, psiconv_u32 indx,
90 const void *el);
73 91
74/* Do some action for each element. Note: you can directly modify the 92/* Do some action for each element. Note: you can directly modify the
75 elements supplied to action, and they will be changed in the list, 93 elements supplied to action, and they will be changed in the list,
76 but never try a free(el)! */ 94 but never try a free(el)! */
77extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el)); 95extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el));
… …
85 Returned is the actual number of elements added. This assumes the file 103 Returned is the actual number of elements added. This assumes the file
86 layout and the memory layout of elements is the same. Note that if 104 layout and the memory layout of elements is the same. Note that if
87 not enough memory could be allocated, 0 is simply returned. */ 105 not enough memory could be allocated, 0 is simply returned. */
88extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f); 106extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f);
89 107
108/* Read the whole file f to list l. Returns 0 on succes, and an errorcode
109 on failure. */
110extern int psiconv_list_fread_all(psiconv_list l, FILE *f);
111
112/* Write the whole list l to the opened file f. Returns 0 on succes, and
113 an errorcode on failure. */
114extern int psiconv_list_fwrite_all(const psiconv_list l, FILE *f);
115
116/* Concatenate two lists. The element sized does not have to be the same,
117 but the result may be quite unexpected if it is not. */
118int psiconv_list_concat(psiconv_list l, const psiconv_list extra);
119
90 120
91#ifdef __cplusplus 121#ifdef __cplusplus
92} 122}
93#endif /* __cplusplus */ 123#endif /* __cplusplus */
94 124
Legend:
Removed from v.70  
changed lines
  Added in v.196
frodo@frodo.looijaard.name
 ViewVC Help
Powered by ViewVC 1.1.26