String Handling Functions

Open GENIE supports a "String" type which allows the normal programming operations to be carried out on string variables, see also String operations (in the chapter on Storage).

There are also several functions designed for working with Open GENIE strings.

The functions which operate on strings directly are:

Substring()
Locate()
Length()

There are also two powerful functions which handle conversions to and from strings and are very useful for input and output formatting.

As_string()
As_variable()

Many other functions take strings as parameters or return them as results. Arrays of strings are handled similarly to arrays of other Open GENIE types except that no arithmetic operations are permitted (for obvious reasons!).

Examples

     # 1.
     # play around using Locate() and Substring()
     >> nth = 2      # find the 2nd occurrence
     >> printn Locate("you fish you",  "you", nth)
     10              # start position of 2nd "you"
     >> pos = 6; length = 4
     >> printn Substring("Blackbird", pos, length)
     bird
     # 2.
     # convert some variables
     >> printn as_variable(".34e1") * 5.6
     19.04
     >> t = 19.04
     >> temp_string = as_string(t) + "mK"
     >> printn temp_string
     # 3.
     # or even a whole workspace
     >> w=s(1)
     >> x = as_string(w)
     >> printn is_a(w, "string")
     false
     >> printn is_a(x, "string")
     true

Command Reference

Substring()

Extracts a smaller string out of a larger string using the given indices.

SUBSTRING() astring=String [start=Integer] [length=Integer] Select a string of a specified length from a given starting position.

example:

	# pick the user name from this string
	>> printn substring("Run: no, User: A Neutron", 16)
	A Neutron
	
	# Select just the initial
	>> printn substring("Run: no, User: A Neutron", 16, 1)
	A

Note: if the length value is null, the rest of the string is returned.

Substring

The Substring() command extracts a smaller string from a larger string. Characters in the string are selected by an index starting at 1 for the first character position in the string.

Parameters:

Atring (String)

The string from which a sub-string is to be selected

Start (Integer)

Starting position of the sub-string to take.

length (Integer)

The length of the sub-string to take.

RESULT = (String)

The sub-string selected.

Locate()

Finds the position (or positions) of a given sub-string within a string.

LOCATE astring=String substring=String [count=Integer] Returns the index position of a sub-string within the string

example:

	# Look for all the positions of the string "quick"
	>> position = 0
	>> words = "The quick brown quick fox&
            jumped quick over the lazy quick dog"
	LOOP i FROM 1 TO 10
	    position = locate(words,"quick",i)
	    EXITIF position = 0
	    print position
	ENDLOOP
	5 17 33 53>>

Note: Locate() is most useful when used in conjunction with the Substring() function.

Locate

Locate allows the position of a substring to be found within a string. If necessary, it is possible to specify an extra count parameter to locate which will allow the position of the nth occurrence of a string to be found. In all cases, if a sub-string is not found, a zero is returned.

Parameters:

Astring (String)

The string which is to be searched for sub-strings.

Substring (String)

The sub-string to search for within the string

count (Integer) [ default=1 ]

Optional parameter to allow the position of the nth substring to be found. This parameter defaults to 1 to look for the first occurrence of the substring.

RESULT = (Integer)

The position of the sub-string within the searched string. The character positions are numbered from 1 for the first character in the string, the same way as for the Substring() command.

Length()

Generic command for returning the length of something

LENGTH item=Generic Returns the length of a variable

example:

	# a String
	>> printn length("abcd")
	4
	# an array
	>> a = dimensions(2,3)
	>> printn length(a)
	[2 3 ] Array(2 )

Note: for workspaces, Length() returns the number of defined elements, for arrays the dimensions.

Length

This is a generic command which may be used on nearly all Open GENIE data types but most usefully on Strings, Arrays and Workspaces.

Parameters:

Item (Generic)

This is an Array, String, or Workspace parameter where the type of the item is of variable length. For arrays, the length is returned as an array of integer dimension lengths, for workspaces it is the number of fields.  Note that to find the overall dimensionality of an array you can use the Dimensionality() function.

RESULT = (Integer)

The length or size of the item.

As_string()

Converts any genie variable into a string.

AS_STRING var=Generic Print a variable into an internal string

example:

	# Format a real to two decimal places
	>> printn myval
	34.234567
	>> str = as_string(myval)
	>> prec = Substring( str, _, locate(str,".") + 2 )
	>> printn prec
	34.23
	# useful for graphics
	>> Draw/text xcoord=0.5 ycoord=0.5 prec

Note: Has a similar purpose to the FORTRAN internal write.

As_string

This function is used in much the same way as the FORTRAN internal write statement. It allows a GCL program to get access to the string which would normally be printed out to a terminal with a Print() command. A likely use of this command is formatting text which is going to be displayed on the graphics screen (which the Print() commands do not write to). Being a generic function, the As_string() command will work with any sort of Open GENIE variable.

Parameters:

Var (Generic)

Any Open GENIE variable or expression can be put here.

RESULT = (String)

A string exactly as if the variable had been printed to the console window with the Print() command.

As_variable()

Converts a string into an internal Open GENIE variable type.

AS_VARIABLE astring=String Read a string into a variable

example:

	# Obtain a number from an awkward string
	>> printn w.title
	BaCuO2 Sprogget & Sylvester t=.589E+1K
	>> tstr = Substring(w.title, locate(w.title,"=")+1)
	>> printn as_variable(tstr)
	5.89

Note: Only reads valid numbers otherwise returns the string.

As_variable

This function is used in much the same way as the FORTRAN internal read statement. It allows a GCL program to get a real or integer value from a string. Normally for user input this is done automatically by the Inquire() command but there may be situations where, as in the example above a number already comes as a string type.

The As_variable() command will attempt to return either a real or integer depending on whether a decimal point is in evidence. If the string passed to the command starts with something which cannot be a number, the original string is returned. It is assumed that, as in the example above, the numeric part of the string is being passed. There is no need to trim the end of the string (unless it makes the number ambiguous) as any extra text will be discarded.

Parameters:

Astring (String)

A string which starts with the number to be read. Any white space in front of the number will be ignored.

RESULT = (Real, Integer or String)

Either a String, Integer or Real depending on whether the function was able to decode a number.