str_list.h 8.47 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 */
55
DLLEXPORT str_list_t	strListInit(void);
56 57

/* Frees the strings in the list (and the list itself) */
58
DLLEXPORT void			strListFree(str_list_t*);
59

rswindell's avatar
rswindell committed
60
/* Frees the strings in the list */
61
DLLEXPORT void			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 */
68
DLLEXPORT char*			strListAppend(str_list_t*, const char* str, size_t index);
69

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

73
/* Append a malloc'd formatted string to the end of the list */
74
DLLEXPORT char*			strListAppendFormat(str_list_t* list, const char* format, ...);
75

76
/* Inserts a string into the list at a specific index */
77 78
/* 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 */
79
DLLEXPORT char*			strListInsert(str_list_t*, const char* str, size_t index);
80

81
/* Insert a string list into another string list */
82
DLLEXPORT size_t		strListInsertList(str_list_t*, const str_list_t append_list, size_t index);
83

84
/* Insert a malloc'd formatted string into the list */
85
DLLEXPORT char*			strListInsertFormat(str_list_t* list, size_t index, const char* format, ...);
86

87
/* Remove a string at a specific index */
88
DLLEXPORT char*			strListRemove(str_list_t*, size_t index);
89 90

/* Remove and free a string at a specific index */
91
DLLEXPORT BOOL			strListDelete(str_list_t*, size_t index);
92 93

/* Replace a string at a specific index */
94
DLLEXPORT char*			strListReplace(const str_list_t, size_t index, const char* str);
rswindell's avatar
rswindell committed
95

96
/* Return a single-string representation of the entire string list, joined with the specified separator */
97
DLLEXPORT char*			strListJoin(const str_list_t, char* buf, size_t buflen, const char* separator);
98

99 100 101 102 103 104 105 106
/* Call a modification callback function for each string in a list */
/* and replace each string with the result of the modification callback. */
/* If the modification callback function returns NULL, the string is not modified. */
/* If the modification callback function returns the same string item pointer it was passed, the string is not realloc'd. */
/* If the modification callback function needs to expand the string item (make it bigger), it must return a new valid pointer */
/* (possibly, the cbdata, a global array or a static automatic variable). Since the new pointer is not free'd here, it should */
/* not be dynamically allocated by the callback function. */
/* Returns the number of modified strings (normally, the list count unless there was a failure) */
107
DLLEXPORT size_t		strListModifyEach(const str_list_t list, char*(modify(size_t index, char* str, void*)), void* cbdata);
108

rswindell's avatar
rswindell committed
109
/* Swap the strings at index1 and index2 */
110
DLLEXPORT BOOL			strListSwap(const str_list_t, size_t index1, size_t index2);
111

112 113 114 115
/* 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)

116 117
/* Add to an exiting or new string list by splitting specified string (str) */
/* into multiple strings, separated by one of the delimit characters */
118
DLLEXPORT str_list_t	strListSplit(str_list_t*, char* str, const char* delimit);
119 120

/* Same as above, but copies str to temporary heap buffer first */
121
DLLEXPORT str_list_t	strListSplitCopy(str_list_t*, const char* str, const char* delimit);
122

123
/* Merge 2 string lists (no copying of string data) */
124
DLLEXPORT size_t		strListMerge(str_list_t*, str_list_t append_list);
125

126 127 128
/* 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 */
129
DLLEXPORT char*			strListCombine(str_list_t, char* buf, size_t maxlen, const char* delimit);
130

131
/* Count the number of strings in the list and returns the count */
132 133
DLLEXPORT size_t		strListCount(const str_list_t);
DLLEXPORT BOOL			strListIsEmpty(const str_list_t);
134

135
/* Returns the index of the specified str (by ptr compare) or -1 if not found */
136
DLLEXPORT int			strListIndexOf(const str_list_t, const char* str);
137
/* Returns the index of the specified str (by string compare) or -1 if not found */
138
DLLEXPORT int			strListFind(const str_list_t, const char* str, BOOL case_sensitive);
139

140
/* Sort the strings in the string list */
141 142
DLLEXPORT void			strListSortAlpha(str_list_t);
DLLEXPORT void			strListSortAlphaReverse(str_list_t);
143 144

/* Case-sensitive sorting */
145 146
DLLEXPORT void			strListSortAlphaCase(str_list_t);
DLLEXPORT void			strListSortAlphaCaseReverse(str_list_t);
rswindell's avatar
rswindell committed
147

148 149
/* Create/Copy/Append/Free NULL-terminated string block */
/* (e.g. for environment variable blocks) */
150 151 152 153 154
DLLEXPORT char*			strListCreateBlock(str_list_t);
DLLEXPORT char*			strListCopyBlock(char* block);
DLLEXPORT char*			strListAppendBlock(char* block, str_list_t);
DLLEXPORT size_t		strListBlockLength(char* block);
DLLEXPORT void			strListFreeBlock(char*);
155

deuce's avatar
deuce committed
156
/* Duplicates a list */
157
DLLEXPORT str_list_t	strListDup(str_list_t list);
deuce's avatar
deuce committed
158 159

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

162
/* Modifies strings in list (returns count of items in list) */
163 164
DLLEXPORT int			strListTruncateTrailingWhitespaces(str_list_t);
DLLEXPORT int			strListTruncateTrailingLineEndings(str_list_t);
165
/* Truncate strings in list at first occurrence of any char in 'set' */
166
DLLEXPORT int			strListTruncateStrings(str_list_t, const char* set);
rswindell's avatar
rswindell committed
167 168
/* Remove all occurrences of chars in set from string in list */
DLLEXPORT int			strListStripStrings(str_list_t, const char* set);
169

170 171 172 173
/************/
/* File I/O */
/************/

174
/* Read lines from file appending each line (with '\n' char) to string list */
175
/* Pass NULL list to have list allocated for you */
176 177
DLLEXPORT str_list_t	strListReadFile(FILE*, str_list_t*, size_t max_line_len);
DLLEXPORT size_t		strListInsertFile(FILE*, str_list_t*, size_t index, size_t max_line_len);
178 179

/* Write to file (fp) each string in the list, optionally separated by separator (e.g. "\n") */
180
DLLEXPORT size_t		strListWriteFile(FILE*, const str_list_t, const char* separator);
181

182 183 184 185 186
#if defined(__cplusplus)
}
#endif

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