str_list.h 7.17 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
/* str_list.h */

/* Functions to deal with NULL-terminated string lists */

/* $Id$ */

/****************************************************************************
 * @format.tab-size 4		(Plain Text/Source Code File Header)			*
 * @format.use-tabs true	(see http://www.synchro.net/ptsc_hdr.html)		*
 *																			*
11
 * Copyright Rob Swindell - http://www.synchro.net/copyright.html			*
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 *																			*
 * This library is free software; you can redistribute it and/or			*
 * modify it under the terms of the GNU Lesser General Public License		*
 * as published by the Free Software Foundation; either version 2			*
 * of the License, or (at your option) any later version.					*
 * See the GNU Lesser General Public License for more details: lgpl.txt or	*
 * http://www.fsf.org/copyleft/lesser.html									*
 *																			*
 * Anonymous FTP access to the most recent released source is available at	*
 * ftp://vert.synchro.net, ftp://cvs.synchro.net and ftp://ftp.synchro.net	*
 *																			*
 * Anonymous CVS access to the development source and modification history	*
 * is available at cvs.synchro.net:/cvsroot/sbbs, example:					*
 * cvs -d :pserver:anonymous@cvs.synchro.net:/cvsroot/sbbs login			*
 *     (just hit return, no password is necessary)							*
 * cvs -d :pserver:anonymous@cvs.synchro.net:/cvsroot/sbbs checkout src		*
 *																			*
 * For Synchronet coding style and modification guidelines, see				*
 * http://www.synchro.net/source.html										*
 *																			*
 * You are encouraged to submit any modifications (preferably in Unix diff	*
 * format) via e-mail to mods@synchro.net									*
 *																			*
 * Note: If this box doesn't appear square, then you need to fix your tabs.	*
 ****************************************************************************/

#ifndef _STR_LIST_H
#define _STR_LIST_H

41
#include <stdio.h>			/* FILE */
42
#include <stddef.h>         /* size_t */
43
#include "gen_defs.h"
deuce's avatar
deuce committed
44
#include "wrapdll.h"
45
46
47
48
49

#if defined(__cplusplus)
extern "C" {
#endif

50
#define STR_LIST_LAST_INDEX	(~0)
51

52
53
typedef char** str_list_t;

54
/* Returns an allocated and terminated string list */
deuce's avatar
deuce committed
55
DLLEXPORT str_list_t DLLCALL	strListInit(void);
56
57

/* Frees the strings in the list (and the list itself) */
deuce's avatar
deuce committed
58
DLLEXPORT void DLLCALL		strListFree(str_list_t*);
59

rswindell's avatar
rswindell committed
60
/* Frees the strings in the list */
deuce's avatar
deuce committed
61
DLLEXPORT void DLLCALL		strListFreeStrings(str_list_t);
rswindell's avatar
rswindell committed
62

63
/* Adds a string to the end of a string list (see strListPush) */
64
/* Pass a pointer to a string list, the string to add (append) */
65
66
/* The string to add is duplicated (using strdup) and the duplicate is added to the list */
/* If you already know the index of the last string, pass it, otherwise pass STR_LIST_LAST_INDEX */
67
/* Returns the updated list or NULL on error */
deuce's avatar
deuce committed
68
DLLEXPORT char* DLLCALL		strListAppend(str_list_t*, const char* str, size_t index);
69

70
/* Append a string list onto another string list */
71
DLLEXPORT size_t DLLCALL	strListAppendList(str_list_t*, const str_list_t append_list);
72
73

/* Inserts a string into the list at a specific index */
74
75
/* Pass a pointer to a string list, the string to add (insert) */
/* The string to add is duplicated (using strdup) and the duplicate is added to the list */
deuce's avatar
deuce committed
76
DLLEXPORT char* DLLCALL		strListInsert(str_list_t*, const char* str, size_t index);
77

78
/* Insert a string list into another string list */
79
DLLEXPORT size_t DLLCALL	strListInsertList(str_list_t*, const str_list_t append_list, size_t index);
80

81
/* Remove a string at a specific index */
deuce's avatar
deuce committed
82
DLLEXPORT char* DLLCALL		strListRemove(str_list_t*, size_t index);
83
84

/* Remove and free a string at a specific index */
deuce's avatar
deuce committed
85
DLLEXPORT BOOL DLLCALL		strListDelete(str_list_t*, size_t index);
86
87

/* Replace a string at a specific index */
deuce's avatar
deuce committed
88
DLLEXPORT char* DLLCALL		strListReplace(const str_list_t, size_t index, const char* str);
rswindell's avatar
rswindell committed
89
90

/* Swap the strings at index1 and index2 */
deuce's avatar
deuce committed
91
DLLEXPORT BOOL DLLCALL		strListSwap(const str_list_t, size_t index1, size_t index2);
92

93
94
95
96
/* Convenience macros for pushing, popping strings (LIFO stack) */
#define		strListPush(list, str)	strListAppend(list, str, STR_LIST_LAST_INDEX)
#define		strListPop(list)		strListRemove(list, STR_LIST_LAST_INDEX)

97
98
/* Add to an exiting or new string list by splitting specified string (str) */
/* into multiple strings, separated by one of the delimit characters */
deuce's avatar
deuce committed
99
DLLEXPORT str_list_t DLLCALL	strListSplit(str_list_t*, char* str, const char* delimit);
100
101

/* Same as above, but copies str to temporary heap buffer first */
deuce's avatar
deuce committed
102
DLLEXPORT str_list_t DLLCALL	strListSplitCopy(str_list_t*, const char* str, const char* delimit);
103

104
/* Merge 2 string lists (no copying of string data) */
deuce's avatar
deuce committed
105
DLLEXPORT size_t DLLCALL		strListMerge(str_list_t*, str_list_t append_list);
106

107
108
109
/* Create a single delimited string from the specified list */
/* If buf is NULL, the buf is malloc'd and should be freed using strListFreeBlock() */
/* Note: maxlen includes '\0' terminator */
deuce's avatar
deuce committed
110
DLLEXPORT char* DLLCALL		strListCombine(str_list_t, char* buf, size_t maxlen, const char* delimit);
111

112
/* Count the number of strings in the list and returns the count */
113
DLLEXPORT size_t DLLCALL	strListCount(const str_list_t);
114

115
/* Returns the index of the specified str (by ptr compare) or -1 if not found */
116
117
118
DLLEXPORT int DLLCALL		strListIndexOf(const str_list_t, const char* str);
/* Returns the index of the specified str (by string compare) or -1 if not found */
DLLEXPORT int DLLCALL		strListFind(const str_list_t, const char* str, BOOL case_sensitive);
119

120
/* Sort the strings in the string list */
deuce's avatar
deuce committed
121
122
DLLEXPORT void DLLCALL		strListSortAlpha(str_list_t);
DLLEXPORT void DLLCALL		strListSortAlphaReverse(str_list_t);
123
124

/* Case-sensitive sorting */
deuce's avatar
deuce committed
125
126
DLLEXPORT void DLLCALL		strListSortAlphaCase(str_list_t);
DLLEXPORT void DLLCALL		strListSortAlphaCaseReverse(str_list_t);
rswindell's avatar
rswindell committed
127

128
129
/* Create/Copy/Append/Free NULL-terminated string block */
/* (e.g. for environment variable blocks) */
deuce's avatar
deuce committed
130
131
132
DLLEXPORT char* DLLCALL		strListCreateBlock(str_list_t);
DLLEXPORT char* DLLCALL		strListCopyBlock(char* block);
DLLEXPORT char* DLLCALL		strListAppendBlock(char* block, str_list_t);
133
DLLEXPORT size_t DLLCALL	strListBlockLength(char* block);
deuce's avatar
deuce committed
134
DLLEXPORT void DLLCALL		strListFreeBlock(char*);
135

deuce's avatar
deuce committed
136
/* Duplicates a list */
deuce's avatar
deuce committed
137
DLLEXPORT str_list_t DLLCALL	strListDup(str_list_t list);
deuce's avatar
deuce committed
138
139

/* Compares two lists */
deuce's avatar
deuce committed
140
DLLEXPORT int DLLCALL			strListCmp(str_list_t list1, str_list_t list2);
deuce's avatar
deuce committed
141

142
143
144
145
146
147
/* Modifies strings in list (returns count of items in list) */
DLLEXPORT int DLLCALL			strListTruncateTrailingWhitespaces(str_list_t);
DLLEXPORT int DLLCALL			strListTruncateTrailingLineEndings(str_list_t);
/* Truncate strings in list at first occurrence of any char in 'set' */
DLLEXPORT int DLLCALL			strListTruncateStrings(str_list_t, const char* set);

148
149
150
151
/************/
/* File I/O */
/************/

152
/* Read lines from file appending each line (with '\n' char) to string list */
153
/* Pass NULL list to have list allocated for you */
deuce's avatar
deuce committed
154
155
DLLEXPORT str_list_t DLLCALL	strListReadFile(FILE*, str_list_t*, size_t max_line_len);
DLLEXPORT size_t DLLCALL		strListInsertFile(FILE*, str_list_t*, size_t index, size_t max_line_len);
156
157

/* Write to file (fp) each string in the list, optionally separated by separator (e.g. "\n") */
deuce's avatar
deuce committed
158
DLLEXPORT size_t DLLCALL		strListWriteFile(FILE*, const str_list_t, const char* separator);
159

160
161
162
163
164
#if defined(__cplusplus)
}
#endif

#endif	/* Don't add anything after this line */