String Functions

Aurora has a large number of string functions included as standard compiler and library functions. Here is a list of these functions (click on the function name to get detailed information about the function):


ToAscii - Character to Integer Conversion Function

someinteger = ToAscii ( somestring );

Description

Returns the integer (decimal) value of ASCII character (first character of a string)

Parameter:

somestring - character or string (only converts the first character of a string).

Return value:

The ASCII decimal integer value is returned as an integer (int).

Usage:
asciivalue = ToAscii( "Aurora" );
Remarks:

In the example above,   ToAscii ("A") = ToAscii("Aurora") = 65

See Character Table for a list of ASCII Values and Character equivalents.

top of page



ToChar - Integer to Character Conversion Function

somestring = ToChar ( someinteger );

Description

Returns the ASCII character equivalent of an integer value

Parameter:

someinteger - an integer value (int)

Return value:

A string value (string).

Usage:
NameString = ToChar ( 65 ) + "urora"; 
Remarks:

In the example above,   ToChar(65) = "A", NameString = "Aurora"

See Character Table for a list of ASCII Values and Character equivalents.

top of page



StrToNum - String to Number Conversion Function

somedouble = StrToNum ( somestring );

Description

Returns the numeric (double) value of string

Parameter:

somestring - a character or string.

Return value:

The ASCII decimal integer value is returned as an integer (int).

Usage:
asciivalue = StrToNum( "123.45" ); 
Remarks:

In the example above,   StrToNum("123.45") = 123.45

top of page



NumToStr - Number to String Conversion Function

somestring = NumToStr ( somenumber );

somestring = NumToStr ( somenumber, optnum );

Description

Converts a double precision number to the string equivalent. If the (optional) number of decimals is not specified, the returned string will be rounded to the nearest whole number.

Parameter:

somenumber - as a double precision number (double)

optnum - an integer specifying the number of digits to include in the string.

Return value:

A string value (string).

Usage:
   //  NumToStr.src 
   global sub main() 
   {
     float x = 1234.56;
     writeln(" x = " + NumToStr( x ) + "\n");
     writeln(" x = " + NumToStr( x, 3 ) + "\n");
     while (GetKey() = "");
     return;
   } 
Remarks:

The example above prints to the console the following:

  x = 1235
  x = 1234.560



top of page



NumToHex - Function to Convert Number to String in Hexidecimal Format

hexstring = NumToHex ( someint );

Description

Converts an integer to a string representing a hexidecimal.

Parameter:

someint - an integer (int)

Return value:

A string value (string). NumToHex can handle 64 bit numbers, the maximum string returned will be 16 digits long. Negative quantities are represented by their twos compliment in hexadecimal.

Usage:

  //  NumToHex.src 
  global sub main() 
  {
    unsigned int64 x = 15;
    int y = 16;
    writeln("15 = x = " + NumToHex( x ) + " in hexidecimal \n");
    writeln("16 = y = " + NumToHex( y ) + " in hexidecimal \n");
    writeln("-16 = -y = " + NumToHex( -y ) + " in hexidecimal \n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console the following:

  15 = x = F in hexidecimal
  16 = y = 10 in hexidecimal
  -16 = -y = FFFFFFFFFFFFFFF0 in hexidecimal



top of page



StrLower - Convert all Characters in a String to Lower Case

StrUpper - Convert all Characters in a String to Upper Case

somenewstring = StrLower ( somestring );

somenewstring = StrUpper ( somestring );

Description

StrLower - convert all characters in a string to Lower Case ("ABC" to "abc")

StrUpper - convert all characters in a string to Upper Case ("abc" to "ABC")

Parameter:

somestring - a string variable or constant

Return value:

somenewstring a string with alphabet characters converted to all lower case or upper case.

Usage:

  //  uStrLower.src 
  global sub main() 
  {
    string x = "123 LOOK AT ME";
    string y = "456 i do tricks";
    writeln(" x = " + StrLower( x ) + "\n");
    writeln(" y = " + StrUpper( y ) + "\n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console the following:

  x = 123 look at me
  y = 456 I DO TRICKS



top of page



FormatDate - Returns System Date as a String

datestring = FormatDate ( );

datestring = FormatDate ( OptString );

Description

Returns system time as a string.

Parameter:

OptString - Optional date formatting string. Default format is dddd/MMMM/yyyy.

   Formatting specifiers:

     d Day of month as digits with no leading zero for single-digit days.

     dd Day of month as digits with leading zero for single-digit days.

     ddd Day of week as a three-letter abbreviation.

     dddd Day of week as its full name.

     M Month as digits with no leading zero for single-digit months.

     MM Month as digits with leading zero for single-digit months.

     MMM Month as a three-letter abbreviation.

     MMMM Month as its full name.

     y Year as last two digits, but with no leading zero for years less than 10.

     yy Year as last two digits, but with leading zero for years less than 10.

     yyyy Year represented by full four digits.

Return value:

datestring - a string value (string).

Usage:
  //  FormatDate.src 
  global sub main() 
  {
    writeln("The date is: " + FormatDate() + "\n");
    writeln("The date is: " + FormatDate("dd-MM-yyyy") + "\n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console "The date is: 2/19/2006" (or whatever the current date is)

and "The date is: 19-02-2006".

top of page



FormatTime - Returns System Time as a String

timestring = FormatTime ( );

Description

Returns system time as a string.

Parameter:

none

Return value:

String value (string).

Usage:
  //  FormatTime.src 
  global sub main() 
  {
    writeln("The time is: " + FormatTime() + "\n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console "The time is: 09:37:21" (or whatever the current time is)

top of page



GetStartPath - Returns Path from where Program Started

pathstring = GetStartPath ( );

Description

GetStartPath returns the full path to the directory containing the running executable including a trailing slash.

Parameter:

none

Return value:

String value (string).

Usage:
  //  GetStartPath.src 
  global sub main() 
  {
    writeln("The program path is: " + GetStartPath () + "\n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console "The program path is: D:\Aurora\examples\tutorial\"

top of page



StrLeft - Returns the leftmost part of a string

PartofString = StrLeft ( StartString, somenum );

Description

StrLeft extracts the leftmost characters which are a portion of the parent (base) string.

Parameters:

StartString is a string value or variable which is the parent string; somenum is an integer (int) which is the number of characters to be extracted.

Return value:

PartofString is a string value (string).

Usage:
  //  StrLeft.src 
  global sub main() 
  {
    string parent = "this is text";
    for (int n = 1; n <= 12; n++)
      {
        writeln("  " + StrLeft (parent, n) + "\n");
      }
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console:

  t
  th
  thi
  this
  this 
  this i
  this is
  this is 
  this is t
  this is te
  this is tex
  this is text

top of page



StrRight - Returns the rightmost part of a string

PartofString = StrRight ( StartString, somenum );

Description

StrRight extracts the rightmost characters which are a portion of the parent (base) string.

Parameters:

StartString is a string value or variable which is the parent string; somenum is an integer (int) which is the number of characters to be extracted.

Return value:

PartofString is a string value (string).

Usage:
  //  StrRight.src 
  global sub main() 
  {
    string parent = "this is text";
    for (int n = 1; n <= 12; n++)
      {
        writeln("  " + StrRight (parent, n) + "\n");
      }
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console:

  t
  xt
  ext
  text
   text
  s text
  is text
   is text
  s is text
  is is text
  his is text
  this is text

top of page



StrMid - Returns the middle portion of a string

PartofString = StrMid ( StartString, startpos, somenum );

Description

StrMid extracts the characters from the middle portion of the parent (base) string.

Parameters:

StartString is a string value or variable which is the parent string

startpos is an integer (int) which indicates the starting position (character) from which to extract

somenum is an integer (int) which is the number of characters to be extracted.

Return value:

PartofString is a string value (string).

Usage:
  //  StrMid.src 
  global sub main() 
  {
	int n;
    string parent = "this is text";
    for (n = 6; n >= 1; n--)
      {
        writeln("  " + StrMid (parent, n, 14-2*n) + "\n");
      }
    writeln("\n\n");
    for (n = 1; n <= 12; n++)
      {
        writeln("  " + StrMid (parent, 1, n) + "\n");
      }
   while (GetKey() = "");
    return;
  }
Remarks:

Besides extracting text from the middle of a string, StrMid() can be used to simulate StrLeft() and StrRigHt(). The example above prints to the console:

  is
   is
  s is t
  is is te
  his is tex
  this is text

  t
  th
  thi
  this
  this 
  this i
  this is
  this is 
  this is t
  this is te
  this is tex
  this is text

top of page



TrimLeft - Trims white space(s) off of the leftmost end of a string

RemainingString = TrimLeft ( StartString );

Description

Trims white space characters off of left (leading) end of a string.

Parameters:

StartString is a string value or variable which is the parent string.

Return value:

RemainingString is a string value (string) which is left over (not trimmed).

Usage:
  //  TrimLeft.src 
  global sub main() 
  {
    string parent = "                  white spaces used to lead this text";
    writeln("  " + TrimLeft (parent) + ".\n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console: " white spaces used to lead this text."

top of page



TrimRight - Trims white space(s) off of the rightmost end of a string

RemainingString = TrimRight ( StartString );

Description

Trims white space characters off of right (trailing) end of a string.

Parameters:

StartString is a string value or variable which is the parent string.

Return value:

RemainingString is a string value (string) which is left over (not trimmed).

Usage:
  //  TrimRight.src 
  global sub main() 
  {
    string parent = "white spaces used to follow this text                  ";
    writeln("  " + TrimRight (parent) + ".\n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console: " white spaces used to follow this text."

top of page



StrFind - finds a string within a string

location = StrFind ( SubjectString, SearchString );

location = StrFind ( SubjectString, SearchString, Start );

Description

Locates (finds) a string within a string and returns its position.

Parameters:

SubjectString is a string value or variable which is the subject of the search.

SearchString is a string value or variable which is the searched for.

Start is an unsigned integer value or variable which identifiies where (position) to start the search in the SubjectString.

Return value:

location is an unsigned integer value (unsigned int) which identifies the position of the found string.

Returns 0 if the search string could not be found.

Usage:
  //  StrFind.src 
  global sub main() 
  {
    writeln("  " + NumToStr(StrFind ("this is some text", "some")) + " \n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above searches for "some" in "this is some text" prints to the console: " 9 "

top of page



StrSpace - returns a string filled with multiples of the space character

manySpaces = StrSpace ( somenum );

Description

Creates a string with a number of blank spaces (ASCII character 032).

Parameters:

somenum is an integer value or variable which is the number (quantity) of spaces to create.

Return value:

manySpaces is a string value or variable which is filled with blank spaces.

Usage:
  //  StrSpace.src 
  global sub main() 
  {
    writeln("  put spaces here >" + StrSpaces(6) + "< \n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console: " put spaces here >          < "

top of page



StrRpt - returns a string filled with multiples of a character

manyCharacters = StrRpt ( somenum, SomeChar );

Description

Creates a string with a number of repeated characters.

Parameters:

somenum is an integer value or variable which is the number (quantity) of characters to create.

SomeChar is a character value or variable which is to be repeated.

Return value:

manyCharacters is a string value or variable which is filled with repeated characters.

Usage:
  //  StrRpt.src 
  global sub main() 
  {
    writeln("  put six b's here >" + StrRpt(6,"b") + "< \n");
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console: " put six b's here >bbbbbb< "

top of page



Using - detailed formatting of numbers, etc.

formattedString = Using ( formatString, param1, param2, ... );

Description

Creates a string which is formatted based on formatting characters.

Parameters:

formatString is a string variable or value which defines the format of numeric data.

param1, param2, ... numeric value(s) or variable(s) to be formatted.

Return value:

formattedString is a string value or variable which has been formatted according to specific formatting characters (strings).

Usage:
  //  Using.src 
  global sub main() 
  {
    double SalesTax, TotalSale, SubTotal = 100.0;
    SalesTax = 0.08*SubTotal;
    TotalSales = SubTotal + SalesTax;
    writeln("   Subtotal = " + using ( "$####.##", SubTotal ) + " USD\n");
    writeln("  Sales Tax = " + using ( "$####.##", SalesTax ) + " USD\n");
    writeln("      Total = " + using ( "$####.##", TotalSales ) + " USD\n");
    writeln("\n\n");
    writeln("      Total = " + using ( "$####.## + $####.## = $####.## ", SubTotal, SalesTax, TotalSales ) + " USD\n");
    while (GetKey() = "");
    return;
  }
Remarks:

The following are valid format specifier characters (strings):

Symbol

Action/Meaning

#Reserves a place for one digit
. (Point)Determines decimal point locations
- (Minus)Left justifies within field. Default is right.
0Prints leading zeros instead of spaces. Ignored if used with left justification.
, (Comma)Prints a comma before every third digit to the left of the decimal point and reserves a place for one digit or digit separator.
&Copies the string parameter directly
%dTreat the parameter as a DOUBLE
%fTreat the parameter as a FLOAT
%qTreat the parameter as a 64 bit integer (INT64)
%%Inserts a % sign into the output string


top of page



IsAlpha - checks if character is a letter

booleanValue = IsAlpha ( SomeChar );

Description

C-type function, Checks if a character is an alphabet letter and returns True or False (1 or 0).

Parameters:

SomeChar is a character value or variable which is to be tested.

Return value:

booleanValue is an integer value or variable which is 1 for True or 0 for False.

Usage:
  //  isalpha.src 
  global sub main() 
  {
    writeln("  b is ");
    if ( IsAlpha ("b") )            // tests the return value from IsAlpha
        {
          writeln("a letter\n\n");  // if true (1)
        }
    else
        {
          writeln("not a letter\n\n");  // if false (0)
        }

    writeln("  2 is ");
    if ( IsAlpha ("2") )            // tests the return value from IsAlpha
        {
          writeln("a letter\n\n");  // if true (1)
        }
    else
        {
          writeln("not a letter\n\n");  // if false (0)
        }

    writeln("  the return value for IsAlpha (\"b\") is " + numtostr( IsAlpha ("b") ) + "\n\n" );
    writeln("  the return value for IsAlpha (\"2\") is " + numtostr( IsAlpha ("2") ) + "\n\n" );
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console the following:

       b is a letter

       2 is not a letter

       the return value for IsAlpha ("b") is 1

       the return value for IsAlpha ("2") is 0    


top of page



IsAlNum - checks if character is a letter or number

booleanValue = IsAlNum ( SomeChar );

Description

C-type function, Checks if a character is an alphanumeric (0-9 or a-z or A-Z) and returns True or False (1 or 0).

Parameters:

SomeChar is a character value or variable which is to be tested.

Return value:

booleanValue is an integer value or variable which is 1 for True or 0 for False.

Usage:
  //  isalnum.src 
  global sub main() 
  {
    writeln("  the return value for IsAlNum (\"5\") is " + numtostr( IsAlNum ("5") ) + "\n\n" );
    writeln("  the return value for IsAlNum (\"M\") is " + numtostr( IsAlNum ("M") ) + "\n\n" );
    writeln("  the return value for IsAlNum (\"?\") is " + numtostr( IsAlNum ("?") ) + "\n\n" );
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console the following:

       the return value for IsAlNum ("5") is 1

       the return value for IsAlNum ("M") is 1  

       the return value for IsAlNum ("?") is 0    


top of page



IsNum - checks if character is a number

booleanValue = IsNum ( SomeChar );

Description

C-type function, Checks if a character is a number (0-9) and returns True or False (1 or 0).

Parameters:

SomeChar is a character value or variable which is to be tested.

Return value:

booleanValue is an integer value or variable which is 1 for True or 0 for False.

Usage:
  //  isnum.src 
  global sub main() 
  {
    writeln("  5 is ");
    if ( IsNum ("5") )            // tests the return value from IsNum
        {
          writeln("a number\n\n");  // if true (1)
        }
    else
        {
          writeln("not a number\n\n");  // if false (0)
        }

    writeln("  M is ");
    if ( IsNum ("M") )            // tests the return value from IsAlpha
        {
          writeln("a number\n\n");  // if true (1)
        }
    else
        {
          writeln("not a number\n\n");  // if false (0)
        }

    writeln("  the return value for IsNum (\"5\") is " + numtostr( IsNum ("5") ) + "\n\n" );
    writeln("  the return value for IsNum (\"M\") is " + numtostr( IsNum ("M") ) + "\n\n" );
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console the following:

       5 is a number

       M is a not a number

       the return value for IsNum ("5") is 1

       the return value for IsNum ("M") is 0    


top of page



IsPunct - checks if character is a punctuation

booleanValue = IsPunct ( SomeChar );

Description

C-type function, Checks if a character is a punctuation character ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ and returns True or False (1 or 0).

Parameters:

SomeChar is a character value or variable which is to be tested.

Return value:

booleanValue is an integer value or variable which is 1 for True or 0 for False.

Usage:
  //  ispunct.src 
  global sub main() 
  {
    writeln("  the return value for IsPunct (\"5\") is " + numtostr( IsPunct ("5") ) + "\n\n" );
    writeln("  the return value for IsPunct (\"M\") is " + numtostr( IsPunct ("M") ) + "\n\n" );
    writeln("  the return value for IsPunct (\"?\") is " + numtostr( IsPunct ("?") ) + "\n\n" );
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console the following:

       the return value for IsPunct ("5") is 0

       the return value for IsPunct ("M") is 0  

       the return value for IsPunct ("?") is 1    


top of page



IsSpace - checks if character is a white space

booleanValue = IsSpace ( SomeChar );

Description

C-type function, Checks if a character is a white space character and returns True or False (1 or 0).

White space characters are: Space=ToChar(32), Tab=ToChar(9), Line Feed=ToChar(10), Vertical Tab=ToChar(11), Form Feed=ToChar(12), Carriage Return=ToChar(13)

Parameters:

SomeChar is a character value or variable which is to be tested.

Return value:

booleanValue is an integer value or variable which is 1 for True or 0 for False.

Usage:
  //  isspace.src 
  global sub main() 
  {
    writeln("  the return value for IsSpace (\"A\") is " + numtostr( IsSpace ("A") ) + "\n\n" );
    writeln("  the return value for IsSpace (\" \") is " + numtostr( IsSpace (" ") ) + "\n\n" );
    writeln("  the return value for IsSpace (ToChar(9)) is " + numtostr( IsSpace (ToChar(9)) ) + "\n\n" );
    writeln("  the return value for IsSpace (ToChar(11)) is " + numtostr( IsSpace (ToChar(11)) ) + "\n\n" );
    writeln("  the return value for IsSpace (ToChar(12)) is " + numtostr( IsSpace (ToChar(12)) ) + "\n\n" );
    writeln("  the return value for IsSpace (ToChar(13)) is " + numtostr( IsSpace (ToChar(13)) ) + "\n\n" );
    while (GetKey() = "");
    return;
  }
Remarks:

The example above prints to the console the following:

      the return value for IsSpace ("A") is 0

      the return value for IsSpace (" ") is 1

      the return value for IsSpace (ToChar(9)) is 1

      the return value for IsSpace (ToChar(11)) is 1

      the return value for IsSpace (ToChar(12)) is 1

      the return value for IsSpace (ToChar(13)) is 1


top of page

prev

next