*********************************************************************
                            LibString 1.0
	      (c) 1998 Giulio Vistoli & Alex Pedretti
*********************************************************************

Index

1.	Introduction
2.	Installation
3.	Usage
4.	Concluding Remarks


1. Introduction
===============

This fortran77 library is developed to simplify strings handling
and i/o parsing operation.
In fortan the read operation of free format files (like C files) is 
not very easy, because this language requires fields with formatted 
position.
On the other hand the native fortran77 does'nt have directed functions 
to manage the strings also for simpliest operations.
In this library you can find functions & routines to read also the 
free format files and handle the strings.

2. Installation
===============

In archive file you can find a Makefile to build a libstr.a library
in order to use routines & functions in your program.
Check in makefile compilation and link options for your computer.
Default options are for SGI machines.
If you can move the libstr.a in your lib directory, make install and 
link your programs with -lstr option, otherwise use -L<PATH> -lstr 
options (PATH is directory who is placed libstr.a).


3. Usage
========

3.1 Functions
~~~~~~~~~~~~~

3.1.1. Length - Return the string length without the blanks characters

Synopsis:

	integer function length(char)
	character *N char

Description:
Instead of the standard len function, this routine returns the 
real length of a string (without the blanks).

3.1.2 Isnumber - Check if the string argument contain a number 

Synopsis:

	logical function isnumber(char)
	character *N char

Description:
This routine returns a true value if char contain a number otherwise
returns false.

3.1.3 Valnum - Return the real value contained into string argument

Synopsis:

	real function valnum(char)
	character *N char

Description:
Obviously this routine can be used also with an integer value making a 
final casting.


3.2 Subroutines
~~~~~~~~~~~~~~~

3.2.1 Right - return the right string portion.

Synopsis:

	subroutine right(input,nchar,output)
	character *N input,output
	integer nchar

Description:
This routine returns in output argument the right nchar portion 
of input string.

3.2.2 Union - Join two strings 

Synopsis:

	subroutine union(input1,input2,output)
	character *N input1,input2,output

Description:
This routine chains two input strings in output argument.

3.2.3 Uniblk - Join two strings with spacing

Synopsis:

	subroutine uniblk(input1,input2,nblank,output)
	character *N input1,input2,output
	integer nblank

Description:
This routine returns in output argument the chaining of the
two input strings with nblank blank characters between them

3.2.4 Intstr - Translate a integer value into string
Synopsis:

	subroutine intstr(int,char,nchar)
	character *N char
	integer nchar,int

Description:
This routine translates the int integer into char string. Nchar is
the output string length to obtain a fixed size of output (example:
001,002,....,023,etc). If nchar is zero, the routine generates a 
string with the exact size of the int number 
(example:1,2,....,3423,etc).


3.2.5 Flostr - Translate a real*8 value into string
Synopsis:

	subroutine intstr(real,char,ndec)
	character *N char
	integer	ndec
	real*8  real

Description:
This routine translates the real value into char string. The real value
must be in double precision. Ndec value is the size of decimal part
      

3.2.6 Pars - Perform the string parsing

Synopsis:

	subroutine pars(char,word,nword)
	character *N char,word(*)
	integer nword

Description:
This routine parses a string in word defined by blank 
characters. The routine output is a string array (word(*)) and the 
nword value is the word number obtained from string parsing.

Example:
	character *20 char,word(5)
        integer nword,i

	char='Fortran77 is a beautiful language'
	call pars(char,word,nword)
	doi=1,nword 
	write(6,*)word(i)
	end do
	end

This program shows this output:
	Fortran77	(word(1))
	is		 ......
	a		 ......
	beautiful	 ......
	language	(word(5))

3.2.7 readf - Parse a string with specified template
Synopsis:

	subroutine readf(line,format,float,int,char,success)
	character *N line,format,char(*)
	integer int(*)
	real float(*)
        logical success

Description:
This routine searchs elements indicated into format string and puts
them in float, int and char arrays.
Possibilities for format elements are:
a	string field
i	integer field
f	float field
x	skip a field
the logical success is returned false if routine readf finds a format
error.

Example:
With readf routine you can read a PDB file with this simple program:

	implicit integer (k-l)
	parameter (maxatom=10000)
	character *80 line
	character *4 str(2)	! atom name and residue name
	character *4 atmname(maxatom),resname(maxatom)
	real flo(3)		! x,y,z coordinates
	real x(maxatom),y(maxatom),z(maxatom)
	integer in(2)		! atom e residue number
	integer atmnum(maxatom),resnum(maxatom)
	logical suc

	open(10,file='file.pdb')
	i=0
10	read(10,'(a80)',end=99)line
	if(line(1:4).eq.'ATOM')then
	i=i+1
	call readf(line,'xiaaxifff',flo,in,str,suc)
	if(.not.suc)stop
	X(i)=flo(1)
	Y(i)=flo(2)
	Z(i)=flo(3)
	atmnum(i)=in(1)
	resnum(i)=in(2)
	atmname(i)=str(1)
	resname(i)=str(2)
	end if
	goto 10
99	end

Note:
The utility of this routine is very remarkeable with files written
in free format such the Quanta/Chemnote mol files or Hyperchem hin
files, unreadable with native fortran read instruction. 
  
4. Concluding Remarks
=====================

All trademarks and  softwares  directly  or  indirectly  referred  in  this
document,  are  copyrighted from legal owners. LibString is a program freeware
and can be spreaded trough Internet, BBS, CD-ROM and each other electronic form.
Authors of this library accepts no responsabilty for hardware/software
damages resulting from the use of this package.


Authors of this library are:

Giulio Vistoli	&   Alex Pedretti
School of Pharmacy
Medicinal Chemistry Institute
Milan University
e-mail giulio@indigo.farma.unimi.it

Bugs and suggestios are willcommed