str_list.h 8.18 KB
Newer Older
1 2 3 4 5 6
/* Functions to deal with NULL-terminated string lists */

/****************************************************************************
 * @format.tab-size 4		(Plain Text/Source Code File Header)			*
 * @format.use-tabs true	(see http://www.synchro.net/ptsc_hdr.html)		*
 *																			*
7
 * Copyright Rob Swindell - http://www.synchro.net/copyright.html			*
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
 *																			*
 * 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									*
 *																			*
 * For Synchronet coding style and modification guidelines, see				*
 * http://www.synchro.net/source.html										*
 *																			*
 * Note: If this box doesn't appear square, then you need to fix your tabs.	*
 ****************************************************************************/

#ifndef _STR_LIST_H
#define _STR_LIST_H

25
#include <stdio.h>			/* FILE */
26
#include <stddef.h>         /* size_t */
27
#include "gen_defs.h"
deuce's avatar
deuce committed
28
#include "wrapdll.h"
29 30 31 32 33

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

34
#define STR_LIST_LAST_INDEX	(~0)
35

36 37
typedef char** str_list_t;

38
/* Returns an allocated and terminated string list */
39
DLLEXPORT str_list_t	strListInit(void);
40 41

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

rswindell's avatar
rswindell committed
44
/* Frees the strings in the list */
45
DLLEXPORT void			strListFreeStrings(str_list_t);
rswindell's avatar
rswindell committed
46

47
/* Adds a string to the end of a string list (see strListPush) */
48
/* Pass a pointer to a string list, the string to add (append) */
49 50
/* 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 */
51
/* Returns the updated list or NULL on error */
52
DLLEXPORT char*			strListAppend(str_list_t*, const char* str, size_t index);
53

54
/* Append a string list onto another string list */
55
DLLEXPORT size_t		strListAppendList(str_list_t*, const str_list_t append_list);
56

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

60
/* Inserts a string into the list at a specific index */
61 62
/* 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 */
63
DLLEXPORT char*			strListInsert(str_list_t*, const char* str, size_t index);
64

65
/* Insert a string list into another string list */
66
DLLEXPORT size_t		strListInsertList(str_list_t*, const str_list_t append_list, size_t index);
67

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

71
/* Remove a string at a specific index */
72
DLLEXPORT char*			strListRemove(str_list_t*, size_t index);
73
DLLEXPORT char*			strListFastRemove(str_list_t, size_t index);
74 75

/* Remove and free a string at a specific index */
76
DLLEXPORT BOOL			strListDelete(str_list_t*, size_t index);
77
DLLEXPORT BOOL			strListFastDelete(str_list_t, size_t index);
78 79

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

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

85 86 87 88 89 90 91 92
/* 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) */
93
DLLEXPORT size_t		strListModifyEach(const str_list_t list, char*(modify(size_t index, char* str, void*)), void* cbdata);
94

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

98 99 100 101
/* 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)

102
/* Add to an existing or new string list by splitting specified string (str) */
103
/* into multiple strings, separated by one of the delimit characters */
104
DLLEXPORT str_list_t	strListSplit(str_list_t*, char* str, const char* delimit);
105 106

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

109
/* Merge 2 string lists (no copying of string data) */
110
DLLEXPORT size_t		strListMerge(str_list_t*, str_list_t append_list);
111

112 113 114
/* 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 */
115
DLLEXPORT char*			strListCombine(str_list_t, char* buf, size_t maxlen, const char* delimit);
116

117
/* Count the number of strings in the list and returns the count */
118 119
DLLEXPORT size_t		strListCount(const str_list_t);
DLLEXPORT BOOL			strListIsEmpty(const str_list_t);
120

121
/* Returns the index of the specified str (by ptr compare) or -1 if not found */
122
DLLEXPORT int			strListIndexOf(const str_list_t, const char* str);
123
/* Returns the index of the specified str (by string compare) or -1 if not found */
124
DLLEXPORT int			strListFind(const str_list_t, const char* str, BOOL case_sensitive);
125

126
/* Sort the strings in the string list */
127 128
DLLEXPORT void			strListSortAlpha(str_list_t);
DLLEXPORT void			strListSortAlphaReverse(str_list_t);
129 130

/* Case-sensitive sorting */
131 132
DLLEXPORT void			strListSortAlphaCase(str_list_t);
DLLEXPORT void			strListSortAlphaCaseReverse(str_list_t);
rswindell's avatar
rswindell committed
133

134 135
/* Create/Copy/Append/Free NULL-terminated string block */
/* (e.g. for environment variable blocks) */
136 137 138 139 140
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*);
141

deuce's avatar
deuce committed
142
/* Duplicates a list */
143
DLLEXPORT str_list_t	strListDup(str_list_t list);
deuce's avatar
deuce committed
144 145

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

148
/* Modifies strings in list (returns count of items in list) */
149 150
DLLEXPORT int			strListTruncateTrailingWhitespaces(str_list_t);
DLLEXPORT int			strListTruncateTrailingLineEndings(str_list_t);
151
/* Truncate strings in list at first occurrence of any char in 'set' */
152
DLLEXPORT int			strListTruncateStrings(str_list_t, const char* set);
rswindell's avatar
rswindell committed
153 154
/* Remove all occurrences of chars in set from string in list */
DLLEXPORT int			strListStripStrings(str_list_t, const char* set);
rswindell's avatar
rswindell committed
155 156
/* Remove duplicate strings from list, return the new list length */
DLLEXPORT int			strListDedupe(str_list_t*, BOOL case_sensitive);
157 158 159
/* Remove blank strings from list, return the new list length */
DLLEXPORT int			strListDeleteBlanks(str_list_t*);
DLLEXPORT int			strListFastDeleteBlanks(str_list_t);
160

161 162 163 164
/************/
/* File I/O */
/************/

165
/* Read lines from file appending each line (with '\n' char) to string list */
166
/* Pass NULL list to have list allocated for you */
167 168
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);
169 170

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

173 174 175 176 177
#if defined(__cplusplus)
}
#endif

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