# amphiblib
a collection of functions that may or may not be useful depending on what you need
mostly a bunch of table and string functions...


functions included;
	table.tostring:
		converts a table into a string, it is suitable for dofile() or dostring()
		supports nested tables, string values, number values, but NOT function values. function values are instead converted into their memory representation due to a tostring operation
		there is also an optional argument "keepkeys" (default false), which will preserve number keys. string keys are always preserved.
		another "humanreadable" argument (default off) will output a much better looking string, but should only be used for debugging due to file size.
		
		example:
			a={1,2,3}
			print(table.tostring(a))
			> {1,2,3}
			print(table.tostring(a,true))
			= > {[1]=1,[2]=2,[3]=3}
			a={1,2} a.test="foo" a.test2="bar"
			print(table.tostring(a))
			> {1,2,["test2"]="bar",["test"]="foo"}
			print(table.tostring(a,true))
			> {[1]=1,[2]=2,["test"]="foo",["test2"]="bar"}

	has:
		checks to see if the first argument has the second in it, and returns a boolean
		number values are converted into strings, other types are ignored
		if the first value is a table, then it is iterated through to check for the second argument appearing in the first
		if the first is instead a string, a :find() operation will be performed and will look for a result
		this has also been added as string.has(), so you can use a colon to call it with a string value

		example:
			a="foobar"
			b="foo"
			print(a:has(b))
			> true
			print(b:has(a))
			>false
			a={"foo","bar"}
			= b="foo"
			print(has(a,b))
			>true
			b="hello"
			print(has(a,b))
			>false

	isin:
		the isin function operates exactly like the has function, but the inputs are flipped. this can be useful for string checking so that one can use a colon for cleaner looking/more readable code
		
		example:
			a="foobar"
			b="foo"
			print(a:isin(b))
			> false
			print(b:isin(a))
			>true
			a={"foo","bar"}
			b="foo"
			print(b:isin(a))
			>true
			b="hello"
			print(b:isin(a))
			>false

	string.cap:
		capitalises the first letter of each word. words are seperated with " " or "."
		optional argument forcelower makes all non capitals lowercase
		can be called with :cap()

		example:
			a="foo bar"
			print(a:cap())
			>Foo Bar
			a="fOO BAr"
			print(a:cap())
			>FOO BAr
			print(a:cap(true))
			>Foo Bar

	string.plural:
		makes the given word plural using standard english rules. notice that some exceptions may not be caught, any may be added at a later daye
		can be called on a string with :plural()

		example:
			a="foo"
			print(a:plural())
			>foos
			a="bar"
			print(a:plural())
			>bars
			a="box"
			print(a:plural())
			>boxes

	string.letters:
		returns a table of all of the letters in a string
		if a non string value is provided, an empty table will be returned
		can be called with :letters()

	example:
		a="foo"
		print(table.concat(a:letters()," "))
		>f o o

	string.words:
		returns a table of all the words in a string
		the separator is " " by default, but can be optionally set
		a non string input will return an empty table

		example:
			a="hello world"
			print(table.concat(a:words(),"\n"))
			>hello
			>world

	pickrandom:
		picks a random value from the provided table. if not provided with a table, returns with hte provided statement

		example:
			a={1,2,3}
			print(pickrandom(a))
			>2
			print(pickrandom(a))
			>1
			print(pickrandom(a))
			>3
			a="foo"
			print(pickrandom(a))
			>foo

	cif:
		an if statement, but more compact. takes 3 arguments, the condition, true output and false output

		example:
			a="foo"
			b="bar"
			print(cif(1==1,a,b))
			> foo
			print(cif(1==2,a,b))
			> bar

	prompt:
		calls for user input in a termilal. optional seperator command to put something like a newline afterwards. returns a string

		example:
		a=prompt("enter a number")
		  enter a number
		  enter a number15
		print(a)
		> 15
		a=prompt("enter a number","\n")
		  enter a number
		  15
		print(a)
		> 15

	getfiles:
		returns a table of all the files in a directory. works on both linux and windows.
		it is recommended to use the full path instead of the direct folder name (or none), as the io.popen might not call from the right location.

		example:
			files = getfiles("Desktop/sample")
			files={"foo.txt","bar.png",.....}

	table.copy:
		returns a copy of the inputed table using the pairs() function. returned table does not share the same memory space as input, meaning they will not affect eachother
		
		example:
			t={1,2,3}
			t2=table.copy(t)
			t==t2
			>false
			print(table.concat(t,",") , table.concat(t2,","))
			>1,2,3	1,2,3
			t2[4]=4
			print(table.concat(t,",") , table.concat(t2,","))
			>1,2,3	1,2,3,4
			
	math.normalrandom:
		returns a random float. float values will tend to be in a normal distribution with a selectable mean and standard deviation
		
		example:
			print(math.normalrandom()) --mean default is 0, stdev is 1
			>-0.03
			print(math.normalrandom(100,15))
			>75.035
			print(math.normalrandom(0,1,300)) --third argument "samples" determines accuracy of distribution at the cost of speed
			>40.124329
			
	math.sum:
		returns the sum of a table
		
		example:
			t={1,2,3,4,5}
			print(math.sum(t))
			>15

	math.mean:
		returns the mean (average) of a table
		
		example:
			t={1,2,3,4,5}
			print(math.mean(t))
			>3
			
	math.stdev:
		returns the standard deviation of a table
		
		example:
			t={1,2,3,4,5}
			print(math.stdev(t))
			>1.581...
			
	table.next
		returns the next value in a table after a supplied value. will not work properly in table with more than 1 of the same value
		
		example:
			t={"foo","bar","hello","world"}
			print(table.next(t,"foo"))
			>bar
			print(table.next(t,"world"))
			>foo
			print(table.next(t,"world",true)) --third argument "nocycle" makes function stop at the end instead of wrapping
			>world
			
	table.prev
		returns the previous value in a table after a supplied value. will not work properly in table with more than 1 of the same value
		
		example:
			t={"foo","bar","hello","world"}
			print(table.next(t,"bar"))
			>foo
			print(table.next(t,"foo"))
			>world
			print(table.next(t,"foo",true)) --third argument "nocycle" makes function stop at the begining instead of wrapping
			>foo
			
	table.convolve
		reuturns the result of convoluting 2 tables. uses the slower method. keys do not need to be numerical, however values do.
		
		example:
			a={1,2,3}
			b={1,2,3}
			print(table.convolve(a,b))
			>{1,4,10,12,9}
			b={4,5,6}
			print(table.convolve(a,b))
			>{4,13,28,27,18}
			
	consoleformat
		returns a string that, when written to the output of a compatible terminal, will be formatted with ANSI escape codes.
		first parameter is the text, the second is a table with the formatting, with named key-value pairings. check code for exact details