Summary

###########################################################################

	File:     strings.icn

	Subject:  Procedures for manipulating strings

	Author:   Ralph E. Griswold, additions by Kostas Oikonomou

	Date:     August 2, 2012

###########################################################################

   This file is in the public domain.

###########################################################################
  
  These procedures perform operations on strings.

	cat(s1, s2, ...)   concatenates an  arbitrary number of strings.
  
	charcnt(s, c)	   returns the number of instances of characters in
			   c in s.

	collate(s1, s2)    collates the characters of s1 and s2.  For example,

                              collate("abc", "def")

                          produces "adbecf".

	comb(s, i)	   generates the combinations of characters from s
			   taken i at a time.

       compress(s, c)     compresses consecutive occurrences of charac-
                          ters in c that occur in s; c defaults to &cset.

	csort(s)           produces the characters of s in lexical order.
  
	decollate(s, i)    produces a string consisting of every other
                          character of s. If i is odd, the odd-numbered
                          characters are selected, while if i is even,
                          the even-numbered characters are selected.
			   The default value of i is 1.

	deletec(s, c)	   deletes occurrences of characters in c from s.

	deletep(s, L)	   deletes all characters at positions specified in
			   L.

	deletes(s1, s2)    deletes occurrences of s2 in s1.

	diffcnt(s)	   returns count of the number of different
			   characters in s.

	extend(s, n)	   replicates s to length n.

	fchars(s)	   returns characters of s in order of decreasing
			   frequency

	interleave(s1, s2) interleaves characters s2 extended to the length
			   of s1 with s1.

	ispal(s)	   succeeds and returns s if s is a palindrome

	maxlen(L, p)	   returns the length of the longest string in L.
			   If p is given, it is applied to each string as
			   as a "length" procedure.  The default for p is
			   proc("*", 1).

	meander(s, n)      produces a "meandering" string that contains all
                          n-tuples of characters of s.

	multicoll(L)	   returns the collation of the strings in L.

	ochars(s)          produces the unique characters of s in the order
			   that they first appear in s.

	odd_even(s)	   inserts values in a numerical string so that
			   adjacent digits follow an odd-even pattern.

	palins(s, n)       generates all the n-character palindromes from the
			   characters in s.

	permutes(s)         generates all the permutations of the string s.

	pretrim(s, c)	   trims characters from beginning of s.

	reflect(s1, i, s2)
			   returns s1 concatenated s2 and the reversal of s1
			   to produce a palindroid; the values of i
			   determine "end conditions" for the reversal:

				0	pattern palindrome; the default
				1	pattern palindrome with center duplicated
				2	true palindrome with center not duplicated
				3	true palindrome with center duplicated

			   s2 defaults to the empty string, in which case the
			   result is a full palindrome

       replace(s1, s2, s3)
			   replaces all occurrences of s2 in s1 by s3; fails
			   if s2 is null.

	replacem(s, ...)   performs multiple replacements in the style of
			   of replace(), where multiple argument pairs
			   may be given, as in

				replacem(s, "a", "bc", "d", "cd")

			   which replaced all "a"s by "bc"s and all
			   "d"s by "cd"s.  Replacements are performed
			   one after another, not in parallel.

	replc(s, L)	   replicates each character of c by the amount
			   given by the values in L.
  
       rotate(s, i)       rotates s i characters to the left (negative i
                          produces rotation to the right); the default
                          value of i is 1.

	schars(s)          produces the unique characters of s in lexical
			   order.

	scramble(s)	   scrambles (shuffles) the characters of s randomly.

	selectp(s, L)	   selects characters of s that are at positions
			   given in L.

	slugs(s, n, c)	   generates column-sized chunks (length <= n)
			   of string s broken at spans of cset c.

			   Defaults:	n	80
					c	' \t\r\n\v\f'

			   Example:  every write(">  ", slugs(msg, 50))

	starseq(s) 	   sequence consisting of the closure of s
		  	   starting with the empty string and continuing
			   in lexical order as given in s

	strcnt(s1, s2)	   produces a count of the number of non-overlapping
			   times s1 occurs in s2; fails is s1 is null

	substrings(s, i, j)
			   generates all the substrings of s with lengths
			   from i to j, inclusive; i defaults to 1, j
			   to *s

	transpose(s1, s2, s3)
			   transposes s1 according to label s2 and
			   transposition s3.
  
	words(s, c)	   generates the "words" from the string s that
			   are separated by characters from the cset
			   c, which defaults to ' \t\r\n\v\f'.

###########################################################################

  Links:  lists

###########################################################################

This file is part of the (main) package.

cat(args)

: concatenate strings

charcnt(s, c)

: character count

collate(s1, s2)

: string collation

comb(s, i)

: character combinations

compress(s, c)

: character compression

csort(s)

: lexically ordered characters

decollate(s, i)

  decollate s according to even or odd i

: string decollation

deletec(s, c)

: delete characters

deletep(s, L)

deletes(s1, s2)

: delete string

diffcnt(s)

: number of different characters

extend(s, n)

: extend string

fchars(s)

: characters in order of frequency

fieldlist(s, sep)

 fieldlist(s,c): produce list of fields from string
 Will produce empty words (fields), if they occur between two consecutive
 separators.
 Example expected format: "a|bc| |d|||fg"

interleave(s1, s2)

: interleave strings

ispal(s)

: test for palindrome

maxlen(L, p)

: maximum string length

meander(alpha, n)

: meandering strings

multicoll(L)

: collate strings in list

numlist(s, sep)

 numlist(s,c): produce list of numbers from string
 Given a string, this procedure returns a list of the numbers in it, if
 any.  Subtlety: suppose we eliminate "n := "; then if the numeric()
 fails, we never tab() and the while loop never terminates!.

ochars(w)

: first appearance unique characters

odd_even(s)

: odd-even numerical string

palins(s, n)

: palindromes

permutes(s)

: string permutations

pretrim(s, c)

: pre-trim string

reflect(s1, i, s2)

: string reflection

replace(s1, s2, s3)

: string replacement

replacem(s, pairs)

: multiple string replacement

replc(s, L)

: replicate characters

rotate(s, i)

: string rotation

schars(s)

: lexical unique characters

scramble(s)

: scramble string

selectp(s, L)

: select characters

slugs(s, n, c)

: generate s in chunks of size <= n

starseq(s)

: closure sequence

strcnt(s1, s2)

: substring count

substrings(s, i, j)

: generate substrings

transpose(s1, s2, s3)

: transpose characters

wordlist(s, sep)

 wordlist(s,c): produce list of words from string
 Multiple consecutive separators are counted as one, so this procedure
 will not return empty words.

words(s, c)

: generate words from string