Hamster-Scripts: Functions (built-in)

Strings

isstr( <expression> )

Solves the given expression and returns true if the result is a string.

Returns: 1, if expression represents a string-value, 0 otherwise

$result = iif( isstr($a), $a, "0x"+hex($a) )

ord( <string> )

Returns the ASCII-number of the first character of <string>.

Returns: Number (0 if string is empty).

print( ord("*") )  # -> 42

chr( <number> )

Returns the ASCII-character of <number>.

Returns: String containing 1 character.

print( chr(42) )  # -> "*"

str( <number>, <length>, <leadchar> )

...
str( <number> )

Converts the given number into a string. If <length> is given, the string is padded with leading <leadchar>'s (default: "0") up to the given length.

Returns: String.

$a = 42
print( str( $a         ) )  # -> "42"
print( str( $a, 5      ) )  # -> "00042"
print( str( $a, 5, " " ) )  # -> "   42"

hex( <number>, <digits> )

hex( <number> ] )

Converts the given number into hex. If <digits> is given, the string is padded with leading "0"'s up to the given length.

Returns: String.

$a = 42
print( hex( $a, 42 ) )          # -> "002A"
print( int( "0x" + hex(42) ) )  # -> 42

len( <string> )

Returns the length of the given string.

Returns: Integer.

print( len("abc") )  # -> 3

pos( <substr>, <string>, <startpos> ] )

pos( <substr>, <string> )

Returns the position of <substr> within <string>. If a <startpos> is given, positions lower than this value are ignored.

Returns: Position or 0, if not found.

print( pos( "b", "abcde" ) )     # -> 2
print( pos( "b", "abcde", 3 ) )  # -> 0

copy( <string>, <startpos>, <length> ] )

copy( <string>, <startpos> )

Returns the part of <string>, which starts at <startpos>. If no <length> is given, the rest of the string is returned.

Returns: String.

print( copy( "abcde", 3, 1 ) )  # -> "c"
print( copy( "abcde", 3 ) )     # -> "cde"

delete( <string>, <startpos>, <length> ] )

delete( <string>, <startpos> )

Deletes the part of <string>, which starts at <startpos>. If no <length> is given, the rest of the string is deleted.

Returns: String.

print( delete( "abcde", 3, 1 ) )  # -> "abde"
print( delete( "abcde", 3 ) )     # -> "ab"
$s = delete( $s, 1, 1 )  # delete 1st char of $s

trim( <string>, <trimchars> )

trim( <string> )

Removes all leading and trailing characters from <string>, that are contained in <trimchars>. If no <trimchars> are given, leading and trailing spaces are removed.

Returns: String.

print( trim("  42  ") )  # -> "42"
$WHITESPACE = " " + chr(9)
print( trim( $line, $WHITESPACE ) )

lowercase( <string> )

Converts all upper-case characters within <string> to lower-case characters.

Returns: String.

print( lowercase( "AbCd" ) )  # -> "abcd"

uppercase( <string> )

Converts all lower-case characters within <string> to upper-case characters.

Returns: String.

print( uppercase( "AbCd" ) )  # -> "ABCD"

replace( <string>, <find>, <replace>, <all>, <ignorecase> )
...
replace( <string>, <find>, <replace> )

Looks for <find> within <string> and, if found, replaces it with <replace>. If <all> is given and has a value other than 0, all occurances of <find> are replaced. If <case> is given and has a value other than 0, upper-/lowercase is ignored for finding.

Returns: String.

print( replace( "abcABCabc", "b", "[X]" )             )  # -> "a[X]cABCabc"
print( replace( "abcABCabc", "b", "[X]", true )       )  # -> "a[X]cABCa[X]c"
print( replace( "abcABCabc", "b", "[X]", true, true ) )  # -> "a[X]cA[X]Ca[X]c"

eval( <string> )

Treats <string> as an expression, solves it and returns its value.

Returns: Result of expression.

print(       "4" + "+" + "2"   )  # -> "4+2"
print( eval( "4" + "+" + "2" ) )  # -> 6

RE_Match( <string>, <regex> )

Returns TRUE if <string> matches the (PCRE-style) regular expression <regex>.

NOTE: Upper-/lowercase is ignored by default. To make it case-sensitive, precede <regex> with a "(?-i)"-flag.

Returns: TRUE (1), FALSE (0)

$answer = "abc4efg2hij"
if( RE_Match( $answer, "4.*2" ) )
   print( "OK, it looks acceptable." )
endif

RE_Extract( <string>, <regex> )

Returns the part of <string>, which matches the (PCRE-style) regular expression <regex>.

NOTE: Upper-/lowercase is ignored by default. To make it case-sensitive, precede <regex> with a "(?-i)"-flag.

Returns: String (empty string, if not found)

$answer = "abc4efg2hij"
print( RE_Extract( $answer, "4.*2" ) )  # -> "4efg2"
print( RE_Extract( $answer, "A.*C"      ) )  # -> "abc"
print( RE_Extract( $answer, "(?-i)A.*C" ) )  # -> ""

RE_Parse( <string>, <regex>, <var1> [ , <var2> ... ] )

Splits <string> into groups defined by (PCRE-style) regular expression <regex>, where a group of characters is placed within parenthesis.

First group is stored in variable <var1>, second in <var2> and so on.

If a given <var#>-parameter is not a variable, the part is ignored.

If <string> does not contain enough groups, the given <vars> are set to empty strings.

NOTE: Upper-/lowercase is ignored by default. To make it case-sensitive, precede <regex> with a "(?-i)"-flag.

Returns: TRUE (1): OK, FALSE (0): Error (e.g. invalid <regex>)

$line = "Subject: This is a test"
RE_Parse( $line, "(\S+:)\s+(.*)", $a, $b )  # -> $a="Subject:", $b="This is a test"

RE_Split( <string>, <regex>, <var1>, <var2> [ , <var3> ... ] )

Splits <string> into parts separated by the (PCRE-style) regular expression <regex>.

First part is stored in variable <var1>, second in <var2> and so on. Last variable always receives the remainder of the string, even if it contains further parts separated by <regex>.

If a given <var#>-parameter is not a variable, the part is ignored.

If <string> does not contain enough parts, the given <vars> are set to empty strings.

NOTE: Upper-/lowercase is ignored by default. To make it case-sensitive, precede <regex> with a "(?-i)"-flag.

Returns: TRUE (1): OK, FALSE (0): Error (e.g. invalid <regex>)

$line = "this  is    a   test"
RE_Split( $line, " +", $a, $b )      # --> $a="this", $b="is    a   test"
RE_Split( $line, " +", $a, $b, $c )  # --> $a="this", $b="is", $c="a   test"

[www.elbiah.de Hamster Playground Documentation]