std.stringbuffer

[Janice Caron]

Hi all,

More than one person has complained about the lack of string functions
in Phobos which operate on mutable chars. In the thread titled "Is all
this Invariant ****....", I suggested creating a new module,
std.stringbuffer, to contain two things:

(1) a StringBuffer class
(2) parallel mutable versions of the functions in std.string.

Walter OKed the idea, so it looks like that's a go. To that end, I've
looked through the functions in std.string and sorted them into
different groups. I think it's important to get the API right so
comments are welcome on all of the below:

The following functions are incorrectly declared in std.string because
they are currently declared to take strings, not const(char)[]. They
should be:

	long atoi(in char[] s)
	real atof(in char[] s)
	size_t count(in char[] s, in char[] sub)
	bool inPattern(dchar c, in char[] pattern)
	int inPattern(dchar c, in char[][] patterns)
	size_t countchars(in char[] s, in char[] pattern)
	bool isNumeric(in char[] s, in bool bAllowSep = false)
	size_t column(char[] str, int tabsize = 8)

The following functions are badly declared in std.string because they
are declared to take and return strings. With the following change,
they become type agnostic

	size_t isEmail(in char[] s)
	size_t isURL(in char[] s)

The following function is the /only/ function currently in std.string
which takes an optional mutable buffer to use instead of allocating on
the heap. For consistency, let's put the mutable version into
std.stringbuffer, and let std.string have an invariant version, as
follows:

	string soundex(string s)

The remaining functions go in std.stringbuffer.

The following functions all take an optional mutable buffer as input
into which to write the return value to avoid allocation.

	char[] tolower(in char[] s, char[] buffer=null)
	char[] toupper(in char[] s, char[] buffer=null)
	char[] capitalize(in char[] s, char[] buffer=null)
	char[] capwords(in char[] s, char[] buffer=null)
	char[] repeat(in char[] s, size_t n, char[] buffer=null)
	char[] join(in char[][] words, char[] sep, char[] buffer=null)
	char[] ljustify(in char[] s, int width, char[] buffer=null)
	char[] rjustify(in char[] s, int width, char[] buffer=null)
	char[] center(in char[] s, int width, char[] buffer=null)
	char[] zfill(in char[] s, int width, char[] buffer=null)
	char[] replace(in char[] s, in char[] from, in char[] to, char[] buffer=null)
	char[] replaceSlice(in char[] s, in char[] slice, in char[]
replacement, char[] buffer=null)
	char[] insert(in char[] s, size_t index, in char[] sub, char[] buffer=null)
	char[] expandtabs(in char[] str, int tabsize=8, char[] buffer=null)
	char[] entab(in char[] s, int tabsize=8, char[] buffer=null) // in place?
	char[] maketrans(in char[] from, in char[] to, char[] buffer=null)
	char[] translate(in char[] s, in char[] transtab, in char[] delchars,
char[] buffer=null)
	char[] succ(in char[] s, char[] buffer=null)
	char[] soundex(in char[] s, char[] buffer=null)
	char[] wrap(in char[] s, int columns = 80, in char[] firstindent =
null, in char[] indent = null, int tabsize = 8, char[] buffer=null)

The following functions I am uncertain about. They could be declared
to take a mutable buffer as input, consistent with the above. /Or/
they could operate on data in place. Opinions are welcome.

	char[] removechars(in char[] s, in char[] pattern, char[]
buffer=null) // in place?
	char[] squeeze(in char[] s, in char[] pattern = null, char[]
buffer=null) // in place?
	char[] tr(in char[] str, in char[] from, in char[] to, in char[]
modifiers=null, char[] buffer=null) // in place?

The following functions need to be overloaded for both const and mutable input

	char[][] split(char[] s)
	const(char)[][] split(const(char)[] s)
	char[][] split(char[] s, in char[] delim)
	const(char)[][] split(const(char)[] s, in char[] delim)
	char[][] splitlines(char[] s)
	const(char)[][] splitlines((char)[] s)

	char[] stripl(char[] s)
	const(char)[] stripl(const(char)[] s)
	char[] stripr(char[] s)
	const(char)[] stripr(const(char)[] s)
	char[] strip(char[] s)
	const(char)[] strip(const(char)[] s)
	char[] chop(char[] s)
	const(char)[] chop(const(char)[] s)

Not sure what to do about the following one. AAs of mutable arrays are
notoriously difficult to get bug free. Should we bother with this one?

	char[][char[]] abbrev(in char[][] values) // May be impractical

Finally - what do we all think about the inconstitent capitalization
thoughout std.string. (toupper versus toString, capwords versus
endsWith, etc.)