lib/psiconv/list.h

/*
    list.h - Part of psiconv, a PSION 5 file formats converter
    Copyright (c) 1999-2014  Frodo Looijaard <frodo@frodo.looijaard.name> 

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/

/* A generic list type. In C++, this would be much neater. All elements must
   be of the same size (solve it with pointers, if needed) */

#ifndef PSICONV_LIST_H
#define PSICONV_LIST_H

#include <stddef.h>
#include <stdio.h>

#include <psiconv/general.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/* Always use psiconv_list, never struct psiconv_list */
/* No need to export the actual internal format */
typedef struct psiconv_list_s *psiconv_list; 

/* Before using a list, call list_new. It takes the size of a single element
   as its argument. Always compute it with a sizeof() expression, just to be
   safe. The returned list is empty. 
   If there is not enough memory available, NULL is returned. You should 
   always test for this explicitely, because the other functions do not
   like a psiconv_list argument that is equal to NULL */
extern psiconv_list psiconv_list_new(size_t element_size);

/* This frees the list. If elements contain pointers that need to be freed
   separately, call list_free_el below. */
extern void psiconv_list_free(psiconv_list l);

/* This calls free_el first for each element, before doing a list_free.
   Note that you should *not* do 'free(el)' at any time; that is taken care of
   automatically. */
extern void psiconv_list_free_el(psiconv_list l, void free_el(void *el));

/* Return the number of allocated elements */
extern psiconv_u32 psiconv_list_length(const psiconv_list l);

/* Return 1 if the list is empty, 0 if not */
extern int psiconv_list_is_empty(const psiconv_list l);

/* Empty a list. Note this does not reclaim any memory space! */
extern void psiconv_list_empty(psiconv_list l);

/* Get an element from the list, and return a pointer to it. Note: you can
   directly modify this element, but be careful not to write beyond the
   element memory space. 
   If indx is out of range, NULL is returned. */
extern void * psiconv_list_get(const psiconv_list l, psiconv_u32 indx);

/* Add an element at the end of the list. The element is copied from the
   supplied element. Of course, this does not help if the element contains
   pointers. 
   As the lists extends itself, it may be necessary to allocate new
   memory. If this fails, a negative error-code is returned. If everything,
   succeeds, 0 is returned. */
extern int psiconv_list_add(psiconv_list l, const void *el);

/* Remove the last element from the list, and copy it to el. Note that
   this will not reduce the amount of space reserved for the list.
   An error code is returned, which will be 0 zero if everything
   succeeded. It is your own responsibility to make sure enough
   space is allocated to el. */
extern int psiconv_list_pop(psiconv_list l, void *el);

/* Replace an element within the list. The element is copied from the
   supplied element. Fails if you try to write at or after the end of
   the list. */
extern int psiconv_list_replace(psiconv_list l, psiconv_u32 indx, 
                                const void *el);

/* Do some action for each element. Note: you can directly modify the
   elements supplied to action, and they will be changed in the list,
   but never try a free(el)! */
extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el));

/* Clone the list, that is, copy it. If elements contain pointers, you
   should call the next routine. If not enough memory is available,
   NULL is returned. */
extern psiconv_list psiconv_list_clone(const psiconv_list l);

/* Read upto size_t elements from file f, and put them at the end of list l.
   Returned is the actual number of elements added. This assumes the file
   layout and the memory layout of elements is the same. Note that if
   not enough memory could be allocated, 0 is simply returned. */
extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f);

/* Read the whole file f to list l. Returns 0 on succes, and an errorcode
   on failure. */
extern int psiconv_list_fread_all(psiconv_list l, FILE *f);

/* Write the whole list l to the opened file f. Returns 0 on succes, and 
   an errorcode on failure. */
extern int psiconv_list_fwrite_all(const psiconv_list l, FILE *f);

/* Concatenate two lists. The element sized does not have to be the same,
   but the result may be quite unexpected if it is not. */
int psiconv_list_concat(psiconv_list l, const psiconv_list extra);


#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif
1	frodo	2	/*
2			list.h - Part of psiconv, a PSION 5 file formats converter
3	frodo	351	Copyright (c) 1999-2014 Frodo Looijaard <frodo@frodo.looijaard.name>
4	frodo	2
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
7			the Free Software Foundation; either version 2 of the License, or
8			(at your option) any later version.
9
10			This program is distributed in the hope that it will be useful,
11			but WITHOUT ANY WARRANTY; without even the implied warranty of
12			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13			GNU General Public License for more details.
14
15			You should have received a copy of the GNU General Public License
16			along with this program; if not, write to the Free Software
17			Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18			*/
19
20			/* A generic list type. In C++, this would be much neater. All elements must
21			be of the same size (solve it with pointers, if needed) */
22
23			#ifndef PSICONV_LIST_H
24			#define PSICONV_LIST_H
25
26			#include <stddef.h>
27			#include <stdio.h>
28
29	frodo	173	#include <psiconv/general.h>
30
31	frodo	55	#ifdef __cplusplus
32			extern "C" {
33			#endif /* __cplusplus */
34
35	frodo	2	/* Always use psiconv_list, never struct psiconv_list */
36			/* No need to export the actual internal format */
37	frodo	56	typedef struct psiconv_list_s *psiconv_list;
38	frodo	2
39			/* Before using a list, call list_new. It takes the size of a single element
40			as its argument. Always compute it with a sizeof() expression, just to be
41	frodo	62	safe. The returned list is empty.
42			If there is not enough memory available, NULL is returned. You should
43			always test for this explicitely, because the other functions do not
44			like a psiconv_list argument that is equal to NULL */
45	frodo	79	extern psiconv_list psiconv_list_new(size_t element_size);
46	frodo	2
47			/* This frees the list. If elements contain pointers that need to be freed
48			separately, call list_free_el below. */
49			extern void psiconv_list_free(psiconv_list l);
50
51			/* This calls free_el first for each element, before doing a list_free.
52			Note that you should not do 'free(el)' at any time; that is taken care of
53			automatically. */
54			extern void psiconv_list_free_el(psiconv_list l, void free_el(void *el));
55
56			/* Return the number of allocated elements */
57	frodo	79	extern psiconv_u32 psiconv_list_length(const psiconv_list l);
58	frodo	2
59			/* Return 1 if the list is empty, 0 if not */
60			extern int psiconv_list_is_empty(const psiconv_list l);
61
62	frodo	80	/* Empty a list. Note this does not reclaim any memory space! */
63			extern void psiconv_list_empty(psiconv_list l);
64
65	frodo	2	/* Get an element from the list, and return a pointer to it. Note: you can
66			directly modify this element, but be careful not to write beyond the
67	frodo	62	element memory space.
68			If indx is out of range, NULL is returned. */
69	frodo	79	extern void * psiconv_list_get(const psiconv_list l, psiconv_u32 indx);
70	frodo	2
71			/* Add an element at the end of the list. The element is copied from the
72			supplied element. Of course, this does not help if the element contains
73	frodo	62	pointers.
74			As the lists extends itself, it may be necessary to allocate new
75			memory. If this fails, a negative error-code is returned. If everything,
76			succeeds, 0 is returned. */
77	frodo	70	extern int psiconv_list_add(psiconv_list l, const void *el);
78	frodo	2
79	frodo	98	/* 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. */
84			extern int psiconv_list_pop(psiconv_list l, void *el);
85
86	frodo	80	/* 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. */
89			extern int psiconv_list_replace(psiconv_list l, psiconv_u32 indx,
90			const void *el);
91
92	frodo	2	/* Do some action for each element. Note: you can directly modify the
93			elements supplied to action, and they will be changed in the list,
94			but never try a free(el)! */
95			extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el));
96
97			/* Clone the list, that is, copy it. If elements contain pointers, you
98	frodo	62	should call the next routine. If not enough memory is available,
99			NULL is returned. */
100	frodo	2	extern psiconv_list psiconv_list_clone(const psiconv_list l);
101
102			/* Read upto size_t elements from file f, and put them at the end of list l.
103			Returned is the actual number of elements added. This assumes the file
104	frodo	62	layout and the memory layout of elements is the same. Note that if
105			not enough memory could be allocated, 0 is simply returned. */
106	frodo	2	extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f);
107
108	frodo	74	/* Read the whole file f to list l. Returns 0 on succes, and an errorcode
109			on failure. */
110			extern 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. */
114			extern int psiconv_list_fwrite_all(const psiconv_list l, FILE *f);
115
116	frodo	72	/* 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. */
118			int psiconv_list_concat(psiconv_list l, const psiconv_list extra);
119	frodo	62
120	frodo	72
121	frodo	55	#ifdef __cplusplus
122			}
123			#endif /* __cplusplus */
124
125	frodo	2	#endif
frodo@frodo.looijaard.name	ViewVC Help
Powered by ViewVC 1.1.26