str_list.h 5.12 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)		*
 *																			*
rswindell's avatar
rswindell committed
11
 * Copyright 2005 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 44 45 46 47 48
#include "gen_defs.h"

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

49
#define STR_LIST_LAST_INDEX	(~0)
50

51 52
typedef char** str_list_t;

53
/* Returns an allocated and terminated string list */
54
str_list_t	strListInit(void);
55 56

/* Frees the strings in the list (and the list itself) */
rswindell's avatar
rswindell committed
57
void		strListFree(str_list_t*);
58

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

62
/* Pass a pointer to a string list, the string to add (append) */
63
/* Returns the updated list or NULL on error */
rswindell's avatar
rswindell committed
64
char*		strListAppend(str_list_t*, const char* str, size_t index);
65

66
/* Append a string list onto another string list */
rswindell's avatar
rswindell committed
67
size_t		strListAppendList(str_list_t*, const str_list_t append_list);
68 69

/* Inserts a string into the list at a specific index */
rswindell's avatar
rswindell committed
70
char*		strListInsert(str_list_t*, const char* str, size_t index);
71

72
/* Insert a string list into another string list */
rswindell's avatar
rswindell committed
73
size_t		strListInsertList(str_list_t*, const str_list_t append_list, size_t index);
74

75
/* Remove a string at a specific index */
rswindell's avatar
rswindell committed
76
char*		strListRemove(str_list_t*, size_t index);
77 78

/* Remove and free a string at a specific index */
rswindell's avatar
rswindell committed
79
BOOL		strListDelete(str_list_t*, size_t index);
80 81

/* Replace a string at a specific index */
rswindell's avatar
rswindell committed
82 83 84 85
char*		strListReplace(const str_list_t, size_t index, const char* str);

/* Swap the strings at index1 and index2 */
BOOL		strListSwap(const str_list_t, size_t index1, size_t index2);
86

87 88 89 90
/* 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)

91 92
/* Add to an exiting or new string list by splitting specified string (str) */
/* into multiple strings, separated by one of the delimit characters */
rswindell's avatar
rswindell committed
93
str_list_t	strListSplit(str_list_t*, char* str, const char* delimit);
94 95

/* Same as above, but copies str to temporary heap buffer first */
rswindell's avatar
rswindell committed
96
str_list_t	strListSplitCopy(str_list_t*, const char* str, const char* delimit);
97

98
/* Merge 2 string lists (no copying of string data) */
rswindell's avatar
rswindell committed
99
size_t		strListMerge(str_list_t*, str_list_t append_list);
100

101
/* Count the number of strings in the list and returns the count */
rswindell's avatar
rswindell committed
102
size_t		strListCount(const str_list_t);
103

104
/* Sort the strings in the string list */
rswindell's avatar
rswindell committed
105 106
void		strListSortAlpha(str_list_t);
void		strListSortAlphaReverse(str_list_t);
107 108

/* Case-sensitive sorting */
rswindell's avatar
rswindell committed
109 110
void		strListSortAlphaCase(str_list_t);
void		strListSortAlphaCaseReverse(str_list_t);
rswindell's avatar
rswindell committed
111

112 113
/* Create/Copy/Append/Free NULL-terminated string block */
/* (e.g. for environment variable blocks) */
114
char*		strListCreateBlock(str_list_t);
115 116 117
char*		strListCopyBlock(char* block);
char*		strListAppendBlock(char* block, str_list_t);
size_t		strListBlockLength(char* block);
118 119
void		strListFreeBlock(char*);

120 121 122 123 124 125
/************/
/* File I/O */
/************/

/* Read lines from file appending each line to string list */
/* Pass NULL list to have list allocated for you */
rswindell's avatar
rswindell committed
126
str_list_t	strListReadFile(FILE*, str_list_t*, size_t max_line_len);
127
size_t		strListInsertFile(FILE*, str_list_t*, size_t index, size_t max_line_len);
128 129

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

132 133 134 135 136
#if defined(__cplusplus)
}
#endif

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