[splint.git] / src / Headers / cstring.h

/*
** Copyright (C) University of Virginia, Massachusetts Institue of Technology 1994-2001.
** See ../LICENSE for license information.
**
*/
/*
** cstring.h
*/

# ifndef CSTRING_H
# define CSTRING_H

/* does this cause problems on Solaris?  linux?  */
/* sgi's don't like it */
# ifndef IRIX
# ifdef NULL   /* hack so <strings.h> works */
# undef NULL
# endif
# endif

/* typedefs in forwardTypes */

extern /*@notnull@*/ cstring cstring_create (int p_n) /*@*/ ;
extern /*@only@*/ /*@notnull@*/  cstring cstring_newEmpty (void) ;
extern /*@notnull@*/ cstring cstring_appendChar (/*@only@*/ cstring p_s1, char p_c);

extern cstring cstring_concatLength (/*@only@*/ cstring p_s1, char *p_s2, int p_len) /*@*/ ;

extern /*@notnull@*/ cstring cstring_prependChar (char p_c, /*@temp@*/ cstring p_s1);
extern /*@notnull@*/ cstring cstring_prependCharO (char p_c, /*@only@*/ cstring p_s1);
extern cstring cstring_downcase (cstring p_s) /*@*/ ;
extern cstring cstring_copy (cstring p_s) /*@*/ ;
extern cstring cstring_copyLength (char *p_s, int p_len) /*@*/ ;

extern int cstring_toPosInt (cstring p_s) /*@*/ ;

typedef enum {
  CGE_SAME,     /* no differences */
  CGE_DISTINCT, /* significant differences */
  CGE_CASE,     /* case differences */
  CGE_LOOKALIKE /* lookalike differences */
} cmpcode;

extern cmpcode cstring_genericEqual (cstring p_s, cstring p_t,
				     int p_nchars,
				     bool p_caseinsensitive,
				     bool p_lookalike) /*@*/ ;

# ifdef WIN32
extern void cstring_replaceAll (cstring p_s, char p_old, char p_snew) /*@modifies p_s@*/ ;
# endif

extern void cstring_replaceLit (/*@unique@*/ cstring p_s, char *p_old, char *p_snew);
extern char cstring_firstChar (cstring p_s) /*@*/ ;
extern char cstring_secondChar (cstring p_s) /*@*/ ;
extern char cstring_lastChar (cstring p_s) /*@*/ ;
extern char cstring_getChar (cstring p_s, int p_n);
extern void cstring_setChar (cstring p_s, int p_n, char p_c);

# define cstring_secondChar(s) cstring_getChar (s, 2)

extern /*@exposed@*/ /*@notnull@*/ /*@untainted@*/ char *
  cstring_toCharsSafe (/*@temp@*/ /*@exposed@*/ /*@returned@*/ cstring p_s)
     /*@*/ ;

extern int cstring_length (cstring p_s) /*@*/ ;
extern bool cstring_contains (/*@unique@*/ cstring p_c, cstring p_sub) /*@*/ ;
extern bool cstring_containsChar (cstring p_c, char p_ch) /*@*/ ;
extern bool cstring_equal (cstring p_c1, cstring p_c2) /*@*/ ;
extern bool cstring_equalCaseInsensitive (cstring p_c1, cstring p_c2) /*@*/ ;
extern bool cstring_equalLen (cstring p_c1, cstring p_c2, int p_len) /*@*/ ;
extern bool cstring_equalLenCaseInsensitive (cstring p_c1, cstring p_c2, int p_len) /*@*/ ;
extern bool cstring_equalPrefix (cstring p_c1, char *p_c2) /*@*/ ;
extern bool cstring_equalCanonicalPrefix (cstring p_c1, char *p_c2) /*@*/ ;
extern bool cstring_equalLit (cstring p_c1, char *p_c2) /*@*/ ;
extern int cstring_compare (cstring p_c1, cstring p_c2) /*@*/ ;
extern int cstring_xcompare (cstring *p_c1, cstring *p_c2) /*@*/ ;

# ifndef NOLCL
extern bool cstring_hasNonAlphaNumBar (cstring p_s) /*@*/ ;
# endif

extern cstring cstring_elide (cstring p_s, int p_len) /*@*/ ;
extern cstring cstring_clip (/*@returned@*/ cstring p_s, int p_len) 
   /*@modifies p_s@*/ ;
extern void cstring_stripChars (cstring p_s, const char *p_clist) /*@modifies p_s@*/ ;

extern /*@dependent@*/ cstring 
  cstring_bsearch (cstring p_key,
		   char **p_table,
		   int p_nentries);

extern bool cstring_lessthan (cstring p_s1, cstring p_s2) /*@*/ ;
# define cstring_lessthan(s1, s2) (cstring_compare (s1, s2) < 0)

# define cstring_equalLit(s, lit) \
  (mstring_equal (cstring_toCharsSafe (s), lit))

extern bool cstring_equalFree (/*@only@*/ cstring p_c1, /*@only@*/ cstring p_c2);

/* really exposed! */

/*
** Don't allow tainted cstring's
*/

extern /*@untained@*/ cstring 
  cstring_fromChars (/*@returned@*/ /*@null@*/ 
		     const /*:untainted@*/ /*@exposed@*/ /*@temp@*/ char *p_cp) /*@*/ ;

extern cstring
   cstring_fromCharsO (/*@null@*/ /*:untainted@*/ /*@only@*/ char *p_cp) /*@*/ ;
/*@-mustfree@*/
# define cstring_fromCharsO(s) cstring_fromChars(s)
/*@=mustfree@*/

extern cstring cstring_fromCharsNew (/*:untainted@*/ /*@null@*/ char *p_s) /*@*/ ;
# define cstring_fromCharsNew(s) cstring_copy(cstring_fromChars(s))

# ifndef NOLCL
extern /*@exposed@*/ /*@notnull@*/ /*@untainted@*/
  char *cstring_toCharsSafeO (/*@only@*/ /*@exposed@*/ /*@returned@*/ cstring p_s);
/*@-mustfree@*/
# define cstring_toCharsSafeO(s) cstring_toCharsSafe(s)
/*@=mustfree@*/
# endif

extern void cstring_free (/*@only@*/ cstring p_s);

/*@constant null cstring cstring_undefined;@*/
# define cstring_undefined     ((cstring)NULL)

extern /*@falsenull@*/ bool cstring_isDefined (cstring p_s) /*@*/ ;
extern /*@truenull@*/ bool cstring_isUndefined (cstring p_s) /*@*/ ;

extern /*@truenull@*/ bool cstring_isEmpty (cstring p_s) /*@*/ ;
extern /*@falsenull@*/ bool cstring_isNonEmpty (cstring p_s) /*@*/ ;

# define cstring_isDefined(s)   ((s) != cstring_undefined)
# define cstring_isUndefined(s) (!cstring_isDefined(s))

# define cstring_isEmpty(s)     (cstring_length(s) == 0)
# define cstring_isNonEmpty(s)  (!cstring_isEmpty(s))

extern cstring cstring_makeLiteral (char *) /*@*/ ;
extern /*@observer@*/ /*@dependent@*/ cstring 
  cstring_makeLiteralTemp (char *) /*@*/ ;

# define cstring_makeLiteral(s) (cstring_copy (cstring_fromChars (s)))
# define cstring_makeLiteralTemp(s) (cstring_fromChars (s))

extern cstring cstring_capitalize (cstring p_s) /*@*/ ;
extern cstring cstring_capitalizeFree (/*@only@*/ cstring p_s) /*@modifies p_s@*/ ;
extern cstring cstring_fill (cstring p_s, int p_n) /*@*/ ;
extern cstring cstring_prefix (cstring p_s, int p_n) /*@*/ ;
extern /*@observer@*/ cstring cstring_suffix (cstring p_s, int p_n) /*@*/ ;
extern cstring cstring_concat (cstring p_s, cstring p_t) /*@*/ ;

extern cstring 
  cstring_concatFree (/*@only@*/ cstring p_s, /*@only@*/ cstring p_t)
  /*@modifies p_s, p_t@*/ ;

extern cstring 
  cstring_concatFree1 (/*@only@*/ cstring p_s, cstring p_t) 
  /*@modifies p_s@*/ ;

# ifndef NOLCL
extern cstring 
  cstring_concatChars (/*@only@*/ cstring p_s, char *p_t)
  /*@modifies p_s@*/ ;

extern lsymbol cstring_toSymbol (/*@only@*/ cstring p_s) /*@*/ ;
# endif

extern void cstring_markOwned (/*@owned@*/ cstring p_s) /*@modifies p_s@*/ ;

extern cstring cstring_beforeChar (cstring p_s, char p_c) /*@*/ ;

/*@iter cstring_chars (sef cstring s, yield char c);@*/
# define cstring_chars(s, m_c) \
  if (cstring_isDefined (s)) \
    { char *m_current = (char *) (s); \
      char m_c; \
      for (; (m_c = *m_current) != '\0'; m_current++) {
# define end_cstring_chars }}

extern /*@observer@*/ cstring cstring_advanceWhiteSpace (cstring) /*@*/ ;

extern /*@only@*/ /*@notnull@*/ cstring
cstring_copySegment (cstring p_s, int p_findex, int p_tindex) /*@*/ ;

extern bool cstring_containsLit (/*@unique@*/ cstring p_c, char *p_sub) /*@*/ ;
# define cstring_containsLit(c,sub) \
  (cstring_contains (c, cstring_fromChars (sub)))

/*drl added July 2, 001 */
extern int cstring_compareLit (/*@unique@*/ cstring p_c, char *p_sub) /*@*/ ;
# define cstring_compareLit(c,sub) \
  (cstring_compare (c, cstring_fromChars (sub)))

# else
# error "Multiple include"
# endif
Commit	Line	Data
885824d3	1	/*
2934b455	2	** Copyright (C) University of Virginia, Massachusetts Institue of Technology 1994-2001.
885824d3	3	** See ../LICENSE for license information.
	4	**
	5	*/
	6	/*
	7	** cstring.h
	8	*/
	9
	10	# ifndef CSTRING_H
	11	# define CSTRING_H
	12
	13	/* does this cause problems on Solaris? linux? */
	14	/* sgi's don't like it */
	15	# ifndef IRIX
	16	# ifdef NULL /* hack so <strings.h> works */
	17	# undef NULL
	18	# endif
	19	# endif
	20
	21	/* typedefs in forwardTypes */
	22
	23	extern /@notnull@/ cstring cstring_create (int p_n) /@/ ;
2934b455	24	extern /@only@/ /@notnull@/ cstring cstring_newEmpty (void) ;
885824d3	25	extern /@notnull@/ cstring cstring_appendChar (/@only@/ cstring p_s1, char p_c);
	26
	27	extern cstring cstring_concatLength (/@only@/ cstring p_s1, char p_s2, int p_len) /@*/ ;
	28
	29	extern /@notnull@/ cstring cstring_prependChar (char p_c, /@temp@/ cstring p_s1);
	30	extern /@notnull@/ cstring cstring_prependCharO (char p_c, /@only@/ cstring p_s1);
	31	extern cstring cstring_downcase (cstring p_s) /@/ ;
	32	extern cstring cstring_copy (cstring p_s) /@/ ;
	33	extern cstring cstring_copyLength (char p_s, int p_len) /@*/ ;
	34
	35	extern int cstring_toPosInt (cstring p_s) /@/ ;
	36
	37	typedef enum {
	38	CGE_SAME, /* no differences */
	39	CGE_DISTINCT, /* significant differences */
	40	CGE_CASE, /* case differences */
	41	CGE_LOOKALIKE /* lookalike differences */
2934b455	42	} cmpcode;
885824d3	43
	44	extern cmpcode cstring_genericEqual (cstring p_s, cstring p_t,
	45	int p_nchars,
	46	bool p_caseinsensitive,
	47	bool p_lookalike) /@/ ;
	48
	49	# ifdef WIN32
	50	extern void cstring_replaceAll (cstring p_s, char p_old, char p_snew) /@modifies p_s@/ ;
	51	# endif
	52
	53	extern void cstring_replaceLit (/@unique@/ cstring p_s, char p_old, char p_snew);
990ec868	54	extern char cstring_firstChar (cstring p_s) /@/ ;
990ec868	55	extern char cstring_secondChar (cstring p_s) /@/ ;
885824d3	56	extern char cstring_lastChar (cstring p_s) /@/ ;
	57	extern char cstring_getChar (cstring p_s, int p_n);
	58	extern void cstring_setChar (cstring p_s, int p_n, char p_c);
	59
	60	# define cstring_secondChar(s) cstring_getChar (s, 2)
	61
ccf0a4a8	62	extern /@exposed@/ /@notnull@/ /@untainted@/ char *
885824d3	63	cstring_toCharsSafe (/@temp@/ /@exposed@/ /@returned@/ cstring p_s)
	64	/@/ ;
	65
	66	extern int cstring_length (cstring p_s) /@/ ;
	67	extern bool cstring_contains (/@unique@/ cstring p_c, cstring p_sub) /@/ ;
	68	extern bool cstring_containsChar (cstring p_c, char p_ch) /@/ ;
	69	extern bool cstring_equal (cstring p_c1, cstring p_c2) /@/ ;
	70	extern bool cstring_equalCaseInsensitive (cstring p_c1, cstring p_c2) /@/ ;
	71	extern bool cstring_equalLen (cstring p_c1, cstring p_c2, int p_len) /@/ ;
	72	extern bool cstring_equalLenCaseInsensitive (cstring p_c1, cstring p_c2, int p_len) /@/ ;
	73	extern bool cstring_equalPrefix (cstring p_c1, char p_c2) /@*/ ;
	74	extern bool cstring_equalCanonicalPrefix (cstring p_c1, char p_c2) /@*/ ;
	75	extern bool cstring_equalLit (cstring p_c1, char p_c2) /@*/ ;
	76	extern int cstring_compare (cstring p_c1, cstring p_c2) /@/ ;
	77	extern int cstring_xcompare (cstring p_c1, cstring p_c2) /@/ ;
	78
	79	# ifndef NOLCL
	80	extern bool cstring_hasNonAlphaNumBar (cstring p_s) /@/ ;
	81	# endif
	82
	83	extern cstring cstring_elide (cstring p_s, int p_len) /@/ ;
	84	extern cstring cstring_clip (/@returned@/ cstring p_s, int p_len)
	85	/@modifies p_s@/ ;
	86	extern void cstring_stripChars (cstring p_s, const char p_clist) /@modifies p_s@*/ ;
	87
	88	extern /@dependent@/ cstring
	89	cstring_bsearch (cstring p_key,
	90	char **p_table,
	91	int p_nentries);
	92
	93	extern bool cstring_lessthan (cstring p_s1, cstring p_s2) /@/ ;
	94	# define cstring_lessthan(s1, s2) (cstring_compare (s1, s2) < 0)
	95
	96	# define cstring_equalLit(s, lit) \
	97	(mstring_equal (cstring_toCharsSafe (s), lit))
	98
	99	extern bool cstring_equalFree (/@only@/ cstring p_c1, /@only@/ cstring p_c2);
	100
	101	/* really exposed! */
ccf0a4a8	102
	103	/*
	104	** Don't allow tainted cstring's
	105	*/
	106
	107	extern /@untained@/ cstring
885824d3	108	cstring_fromChars (/@returned@/ /@null@/
ccf0a4a8	109	const /:untainted@/ /@exposed@/ /@temp@/ char p_cp) /@*/ ;
885824d3	110
885824d3	111	extern cstring
ccf0a4a8	112	cstring_fromCharsO (/@null@/ /:untainted@/ /@only@/ char p_cp) /@*/ ;
885824d3	113	/@-mustfree@/
	114	# define cstring_fromCharsO(s) cstring_fromChars(s)
	115	/@=mustfree@/
	116
ccf0a4a8	117	extern cstring cstring_fromCharsNew (/:untainted@/ /@null@/ char p_s) /@*/ ;
885824d3	118	# define cstring_fromCharsNew(s) cstring_copy(cstring_fromChars(s))
	119
	120	# ifndef NOLCL
ccf0a4a8	121	extern /@exposed@/ /@notnull@/ /@untainted@/
885824d3	122	char cstring_toCharsSafeO (/@only@/ /@exposed@/ /@returned@*/ cstring p_s);
	123	/@-mustfree@/
	124	# define cstring_toCharsSafeO(s) cstring_toCharsSafe(s)
	125	/@=mustfree@/
	126	# endif
	127
	128	extern void cstring_free (/@only@/ cstring p_s);
	129
	130	/@constant null cstring cstring_undefined;@/
	131	# define cstring_undefined ((cstring)NULL)
	132
	133	extern /@falsenull@/ bool cstring_isDefined (cstring p_s) /@/ ;
	134	extern /@truenull@/ bool cstring_isUndefined (cstring p_s) /@/ ;
	135
2934b455	136	extern /@truenull@/ bool cstring_isEmpty (cstring p_s) /@/ ;
885824d3	137	extern /@falsenull@/ bool cstring_isNonEmpty (cstring p_s) /@/ ;
	138
	139	# define cstring_isDefined(s) ((s) != cstring_undefined)
	140	# define cstring_isUndefined(s) (!cstring_isDefined(s))
	141
	142	# define cstring_isEmpty(s) (cstring_length(s) == 0)
	143	# define cstring_isNonEmpty(s) (!cstring_isEmpty(s))
	144
	145	extern cstring cstring_makeLiteral (char ) /@*/ ;
	146	extern /@observer@/ /@dependent@/ cstring
	147	cstring_makeLiteralTemp (char ) /@*/ ;
	148
	149	# define cstring_makeLiteral(s) (cstring_copy (cstring_fromChars (s)))
	150	# define cstring_makeLiteralTemp(s) (cstring_fromChars (s))
	151
	152	extern cstring cstring_capitalize (cstring p_s) /@/ ;
	153	extern cstring cstring_capitalizeFree (/@only@/ cstring p_s) /@modifies p_s@/ ;
	154	extern cstring cstring_fill (cstring p_s, int p_n) /@/ ;
	155	extern cstring cstring_prefix (cstring p_s, int p_n) /@/ ;
	156	extern /@observer@/ cstring cstring_suffix (cstring p_s, int p_n) /@/ ;
	157	extern cstring cstring_concat (cstring p_s, cstring p_t) /@/ ;
	158
	159	extern cstring
	160	cstring_concatFree (/@only@/ cstring p_s, /@only@/ cstring p_t)
	161	/@modifies p_s, p_t@/ ;
	162
	163	extern cstring
	164	cstring_concatFree1 (/@only@/ cstring p_s, cstring p_t)
	165	/@modifies p_s@/ ;
	166
	167	# ifndef NOLCL
	168	extern cstring
	169	cstring_concatChars (/@only@/ cstring p_s, char *p_t)
	170	/@modifies p_s@/ ;
	171
	172	extern lsymbol cstring_toSymbol (/@only@/ cstring p_s) /@/ ;
	173	# endif
	174
	175	extern void cstring_markOwned (/@owned@/ cstring p_s) /@modifies p_s@/ ;
	176
	177	extern cstring cstring_beforeChar (cstring p_s, char p_c) /@/ ;
	178
	179	/@iter cstring_chars (sef cstring s, yield char c);@/
	180	# define cstring_chars(s, m_c) \
	181	if (cstring_isDefined (s)) \
	182	{ char m_current = (char ) (s); \
	183	char m_c; \
	184	for (; (m_c = *m_current) != '\0'; m_current++) {
	185	# define end_cstring_chars }}
	186
	187	extern /@observer@/ cstring cstring_advanceWhiteSpace (cstring) /@/ ;
	188
2934b455	189	extern /@only@/ /@notnull@/ cstring
	190	cstring_copySegment (cstring p_s, int p_findex, int p_tindex) /@/ ;
	191
885824d3	192	extern bool cstring_containsLit (/@unique@/ cstring p_c, char p_sub) /@*/ ;
	193	# define cstring_containsLit(c,sub) \
	194	(cstring_contains (c, cstring_fromChars (sub)))
	195
28bf4b0b	196	/drl added July 2, 001 /
	197	extern int cstring_compareLit (/@unique@/ cstring p_c, char p_sub) /@*/ ;
	198	# define cstring_compareLit(c,sub) \
	199	(cstring_compare (c, cstring_fromChars (sub)))
	200
885824d3	201	# else
	202	# error "Multiple include"
	203	# endif
	204
	205
	206