/[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 2 Revision 79
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 Frodo Looijaard <frodol@dds.nl> 3 Copyright (c) 1999, 2000 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.
… …
21 be of the same size (solve it with pointers, if needed) */ 21 be of the same size (solve it with pointers, if needed) */
22 22
23#ifndef PSICONV_LIST_H 23#ifndef PSICONV_LIST_H
24#define PSICONV_LIST_H 24#define PSICONV_LIST_H
25 25
26#include <psiconv/general.h>
26#include <stddef.h> 27#include <stddef.h>
27#include <stdio.h> 28#include <stdio.h>
28 29
30#ifdef __cplusplus
31extern "C" {
32#endif /* __cplusplus */
33
29/* Always use psiconv_list, never struct psiconv_list */ 34/* Always use psiconv_list, never struct psiconv_list */
30/* No need to export the actual internal format */ 35/* No need to export the actual internal format */
31typedef struct psiconv_list *psiconv_list; 36typedef struct psiconv_list_s *psiconv_list;
32 37
33/* Before using a list, call list_new. It takes the size of a single element 38/* Before using a list, call list_new. It takes the size of a single element
34 as its argument. Always compute it with a sizeof() expression, just to be 39 as its argument. Always compute it with a sizeof() expression, just to be
35 safe. The returned list is empty. */ 40 safe. The returned list is empty.
41 If there is not enough memory available, NULL is returned. You should
42 always test for this explicitely, because the other functions do not
43 like a psiconv_list argument that is equal to NULL */
36extern psiconv_list psiconv_list_new(int element_size); 44extern psiconv_list psiconv_list_new(size_t element_size);
37 45
38/* This frees the list. If elements contain pointers that need to be freed 46/* This frees the list. If elements contain pointers that need to be freed
39 separately, call list_free_el below. */ 47 separately, call list_free_el below. */
40extern void psiconv_list_free(psiconv_list l); 48extern void psiconv_list_free(psiconv_list l);
41 49
… …
43 Note that you should *not* do 'free(el)' at any time; that is taken care of 51 Note that you should *not* do 'free(el)' at any time; that is taken care of
44 automatically. */ 52 automatically. */
45extern void psiconv_list_free_el(psiconv_list l, void free_el(void *el)); 53extern void psiconv_list_free_el(psiconv_list l, void free_el(void *el));
46 54
47/* Return the number of allocated elements */ 55/* Return the number of allocated elements */
48extern int psiconv_list_length(const psiconv_list l); 56extern psiconv_u32 psiconv_list_length(const psiconv_list l);
49 57
50/* Return 1 if the list is empty, 0 if not */ 58/* Return 1 if the list is empty, 0 if not */
51extern int psiconv_list_is_empty(const psiconv_list l); 59extern int psiconv_list_is_empty(const psiconv_list l);
52 60
53/* Get an element from the list, and return a pointer to it. Note: you can 61/* Get an element from the list, and return a pointer to it. Note: you can
54 directly modify this element, but be careful not to write beyond the 62 directly modify this element, but be careful not to write beyond the
55 element memory space. */ 63 element memory space.
64 If indx is out of range, NULL is returned. */
56extern void * psiconv_list_get(const psiconv_list l, unsigned int indx); 65extern void * psiconv_list_get(const psiconv_list l, psiconv_u32 indx);
57 66
58/* Add an element at the end of the list. The element is copied from the 67/* Add an element at the end of the list. The element is copied from the
59 supplied element. Of course, this does not help if the element contains 68 supplied element. Of course, this does not help if the element contains
60 pointers. */ 69 pointers.
70 As the lists extends itself, it may be necessary to allocate new
71 memory. If this fails, a negative error-code is returned. If everything,
72 succeeds, 0 is returned. */
61extern void psiconv_list_add(psiconv_list l, void *el); 73extern int psiconv_list_add(psiconv_list l, const void *el);
62 74
63/* Do some action for each element. Note: you can directly modify the 75/* Do some action for each element. Note: you can directly modify the
64 elements supplied to action, and they will be changed in the list, 76 elements supplied to action, and they will be changed in the list,
65 but never try a free(el)! */ 77 but never try a free(el)! */
66extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el)); 78extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el));
67 79
68/* Clone the list, that is, copy it. If elements contain pointers, you 80/* Clone the list, that is, copy it. If elements contain pointers, you
69 should call the next routine. */ 81 should call the next routine. If not enough memory is available,
82 NULL is returned. */
70extern psiconv_list psiconv_list_clone(const psiconv_list l); 83extern psiconv_list psiconv_list_clone(const psiconv_list l);
71
72/* Clone the list. For each element, clone_el is called. The elements which
73 are given to clone_el must be modified in place, as needed. */
74extern psiconv_list psiconv_list_clone_el(const psiconv_list l,
75 void clone_el(void *el));
76 84
77/* Read upto size_t elements from file f, and put them at the end of list l. 85/* Read upto size_t elements from file f, and put them at the end of list l.
78 Returned is the actual number of elements added. This assumes the file 86 Returned is the actual number of elements added. This assumes the file
79 layout and the memory layout of elements is the same. */ 87 layout and the memory layout of elements is the same. Note that if
88 not enough memory could be allocated, 0 is simply returned. */
80extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f); 89extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f);
81 90
91/* Read the whole file f to list l. Returns 0 on succes, and an errorcode
92 on failure. */
93extern int psiconv_list_fread_all(psiconv_list l, FILE *f);
94
95/* Write the whole list l to the opened file f. Returns 0 on succes, and
96 an errorcode on failure. */
97extern int psiconv_list_fwrite_all(const psiconv_list l, FILE *f);
98
99/* Concatenate two lists. The element sized does not have to be the same,
100 but the result may be quite unexpected if it is not. */
101int psiconv_list_concat(psiconv_list l, const psiconv_list extra);
102
103
104#ifdef __cplusplus
105}
106#endif /* __cplusplus */
107
82#endif 108#endif
Legend:
Removed from v.2  
changed lines
  Added in v.79
frodo@frodo.looijaard.name
 ViewVC Help
Powered by ViewVC 1.1.26