The Ring programming language version 1.5 book - Part 4 of 31

Ring Documentation, Release 1.5
try {
Block of statements
catch
Block of statements
}
21.3. Exceptions 152

CHAPTER
TWENTYTWO
GETTING INPUT
We can get input from the keyboard using
• The Give Command
• The GetChar() Function
• The Input() Function
22.1 Give Command
Syntax:
Give VariableName
Example:
See "Enter the first number : " Give nNum1
See "Enter the second number : " Give nNum2
See "Sum : " + ( 0 + nNum1 + nNum2 )
Output:
Enter the first number : 3
Enter the second number : 4
Sum : 7
22.2 GetChar() Function
We can get one character from the standard input using the GetChar() function
Syntax:
GetChar() ---> Character
Example:
While True
See "
Main Menu
(1) Say Hello
(2) Exit
"
Option = GetChar()
153

GetChar() GetChar() # End of line
# the previous two lines can be replaced with the next line
# Give Option
if Option = 1
see "Enter your name : " give cName
see "Hello " + cName
else
bye
ok
End
22.3 Input() Function
We can get input from the keyboard using the Input() function
Syntax:
Input(nCount) ---> string
The function will wait until nCount characters (at least) are read
Example:
See "Enter message (30 characters) : " cMsg = input(30)
See "Message : " + cMsg
22.3. Input() Function 154

CHAPTER
TWENTYTHREE
FUNCTIONS - FIRST STYLE
In this chapter we are going to learn about the next topics :-
• Define functions
• Call functions
• Declare parameters
• Send parameters
• Main Function
• Variables Scope
• Return Value
• Recursion
23.1 Define Functions
To define new function
Syntax:
func <function_name> [parameters]
Block of statements
Note: No keyword is required to end the function definition.
Example:
func hello
see "Hello from function" + nl
23.2 Call Functions
To call function without parameters, we type the function name then ()
Tip: We can call the function before the function definition and the function code.
Example:
155

hello()
func hello
see "Hello from function" + nl
Example:
first() second()
func first see "message from the first function" + nl
func second see "message from the second function" + nl
23.3 Declare parameters
To declare the function parameters, after the function name type the list of parameters as a group of identifiers separated
by comma.
Example:
func sum x,y
see x+y+nl
23.4 Send Parameters
To send parameters to function, type the parameters inside () after the function name
Syntax:
funcname(parameters)
Example:
/* output
** 8
** 3000
*/
sum(3,5) sum(1000,2000)
func sum x,y see x+y+nl
23.5 Main Function
Using the Ring programming language, the Main Function is optional, when it’s defined, it will be executed after the
end of other statements.
if no other statements comes alone, the main function will be the first entry point
Example:
23.3. Declare parameters 156

# this program will print the hello world message first then execute the main function
See "Hello World!" + nl
func main
see "Message from the main function" + nl
23.6 Variables Scope
The Ring programming language uses lexical scoping to determine the scope of a variable.
Variables defined inside functions (including function parameters) are local variables. Variables defined outside func-
tions (before any function) are global variables.
Inside any function we can access the variables defined inside this function beside the global variables.
Example:
# the program will print numbers from 10 to 1
x = 10 # x is a global variable.
func main
for t = 1 to 10 # t is a local variable
mycounter() # call function
next
func mycounter
see x + nl # print the global variable value
x-- # decrement
Note: Using the main function before the for loop declare the t variable as a local variable, It’s recommended to use
the main functions instead of typing the instructions directly to set the scope of the new variables to local.
23.7 Return Value
The function can return a value using the Return command.
Syntax:
Return [Expression]
Tip: the Expression after the return command is optional and we can use the return command to end the function
execution without returning any value.
Note: if the function doesn’t return explicit value, it will return NULL (empty string = “” ).
Example:
23.6. Variables Scope 157

if novalue() = NULL
See "the function doesn't return a value" + nl
ok
func novalue
23.8 Recursion
The Ring programming language support Recursion and the function can call itself using different parameters.
Example:
see fact(5) # output = 120
func fact x if x = 1 return 1 else return x * fact(x-1) ok
23.8. Recursion 158

CHAPTER
TWENTYFOUR
FUNCTIONS - SECOND STYLE
• Call functions
• Send parameters
• Main Function
• Variables Scope
• Return Value
• Recursion
Syntax:
def <function_name> [parameters]
Block of statements
[end]
Note: the keyword ‘end’ is optional.
Example:
def hello
put "Hello from function" + nl
end
24.2 Call Functions
Example:
159

hello()
def hello
put "Hello from function" + nl
end
Example:
first() second()
def first put "message from the first function" + nl
def second put "message from the second function" + nl
by comma.
Example:
def sum x,y
put x+y+nl
end
Syntax:
Example:
/* output
** 8
** 3000
*/
sum(3,5) sum(1000,2000)
def sum x,y put x+y+nl
24.5 Main Function
Example:

put "Hello World!" + nl
def main
put "Message from the main function" + nl
end
Example:
def main
for t = 1 to 10 # t is a local variable
end
end
def mycounter
put x + nl # print the global variable value
x-- # decrement
end
24.7 Return Value
Syntax:
Return [Expression]
Example:
24.6. Variables Scope 161

if novalue() = NULL
put "the function doesn't return a value" + nl
end
def novalue
24.8 Recursion
Example:
put fact(5) # output = 120
def fact x if x = 1 return 1 else return x * fact(x-1) end
24.8. Recursion 162

CHAPTER
TWENTYFIVE
FUNCTIONS - THIRD STYLE
• Call functions
• Send parameters
• Main Function
• Variables Scope
• Return Value
• Recursion
Syntax:
func <function_name> [parameters] ['{']
Block of statements
['}']
Example:
load "stdlib.ring"
func hello {
print("Hello from function n")
}
25.2 Call Functions
Example:
163

load "stdlib.ring"
hello()
func hello {
print("Hello from function n")
}
Example:
load "stdlib.ring"
first() second()
func first { print("message from the first function n") }
func second { print("message from the second function n") }
by comma.
Example:
load "stdlib.ring"
func sum(x,y) {
print(x+y)
}
Syntax:
Example:
/* output
** 8
** 3000
*/
load "stdlib.ring"
sum(3,5) sum(1000,2000)
func sum(x,y) { print(x+y) }

25.5 Main Function
Example:
load "stdlib.ring"
print("Hello, World! n")
func main {
print("Message from the main function n")
}
Example:
load "stdlib.ring"
func main {
for t = 1 to 10 { # t is a local variable
}
}
func mycounter {
print("#{x}n") # print the global variable value
x-- # decrement
}
25.7 Return Value
Syntax:
25.5. Main Function 165

Return [Expression]
Example:
load "stdlib.ring"
if novalue() = NULL {
print("the function doesn't return a valuen")
}
func novalue { }
25.8 Recursion
Example:
load "stdlib.ring"
print( fact(5) ) # output = 120
func fact(x) { if x = 1 { return 1 else return x * fact(x-1) } }
25.8. Recursion 166

CHAPTER
TWENTYSIX
PROGRAM STRUCTURE
In this chapter we will learn about using many source code files in the same project.
26.1 Source Code File Sections
Each source code file may contains the next sections (in the same order).
Source Code File Sections
Load Files
Statements and Global Variables
Functions
Packages and Classes
The application maybe one or more of files.
26.2 Using Many Source Code Files
To include another source file in the project, just use the load command.
Syntax:
Load "filename.ring"
Note: The Load command is executed directly by the compiler in the parsing stage
Tip: if you don’t know the file name until the runtime, or you need to use functions to get the file path, just use eval().
Example:
# File : Start.ring
Load "sub.ring"
sayhello("Mahmoud")
# File : sub.ring
func sayhello cName
see "Hello " + cName + nl
167

CHAPTER
TWENTYSEVEN
LISTS
In this chapter we are going to learn how to deal with lists.
27.1 Create Lists
We can create new lists by deﬁning the list items inside square bracts.
Example:
aList = [1,2,3,4,5]
Also we can create new lists using the : operator
Example:
aList = 1:5
aList2 = "a":"z"
Example:
aList = 5:1
aList2 = "z":"a"
Also we can create lists using the list() function
Syntax:
list = list(size)
Example
aList = list(10) # aList contains 10 items
Note: the list index start from 1
27.2 Add Items
To add new items to the list, we can use the Add() function.
Syntax:
Add(List,Item)
168

Example:
aList = ["one","two"]
add(aList,"three")
see aList
Also we can do that using the + operator.
Syntax:
List + item
Example:
aList = 1:10 # create list contains numbers from 1 to 10
aList + 11 # add number 11 to the list
see aList # print the list
27.3 Get List Size
We can get the list size using the len() function
Syntax:
Len(List)
Example:
aList = 1:20 see len(aList) # print 20
27.4 Delete Item From List
To delete an item from the list, we can use the del() function
Syntax:
del(list,index)
Example:
aList = ["one","two","other","three"]
Del(aList,3) # delete item number three
see aList # print one two three
27.5 Get List Item
To get an item from the list, we uses the next syntax
List[Index]
Example:
aList = ["Cairo","Riyadh"]
see "Egypt : " + aList[1] + nl +
"KSA : " + aList[2] + nl
27.3. Get List Size 169

27.6 Set List Item
To set the value of an item inside the list, we can use the next syntax
List[Index] = Expression
Example:
aList = list(3) # create list contains three items
aList[1] = "one" aList[2] = "two" aList[3] = "three"
see aList
27.7 Search
To ﬁnd an item inside the list we can use the ﬁnd() function
Syntax:
Find(List,ItemValue) ---> Item Index
Find(List,ItemValue,nColumn) ---> Search in nColumn, returns the Item Index
Find(List,ItemValue,nColumn,cAttribute) ---> Item Index
Example:
aList = ["one","two","three","four","five"]
see find(aList,"three") # print 3
Example:
mylist = [["one",1],
["two",2],
["three",3]]
see find(mylist,"two",1) + nl # print 2
see find(mylist,2,2) + nl # print 2
Also we can use the binarysearch() function to search in sorted list.
Syntax:
BinarySearch(List,ItemValue) ---> Item Index
BinarySearch(List,ItemValue,nColumn) ---> Search in nColumn, returns the Item Index
Example:
aList = ["one","two","three","four","five"]
aList = sort(aList)
see binarysearch(aList,"three")
Output:
five
four
one
three
two
4
27.6. Set List Item 170

27.8 Sort
We can sort the list using the sort() function.
Syntax:
Sort(List) ---> Sorted List
Sort(List,nColumn) ---> Sorted List based on nColumn
Sort(List,nColumn,cAttribute) ---> Sorted List based on Object Attribute
Example:
aList = [10,12,3,5,31,15]
aList = sort(aList) see aList # print 3 5 10 12 15 31
We can sort list of strings
Example:
mylist = ["mahmoud","samir","ahmed","ibrahim","mohammed"]
see mylist # print list before sorting
mylist = sort(mylist) # sort list
see "list after sort"+nl
see mylist # print ahmed ibrahim mahmoud mohammed samir
We can sort a list based on a speciﬁc column.
Example:
aList = [ ["mahmoud",15000] ,
["ahmed", 14000 ] ,
["samir", 16000 ] ,
["mohammed", 12000 ] ,
["ibrahim",11000 ] ]
aList2 = sort(aList,1)
see aList2
Output:
ahmed
14000
ibrahim
11000
mahmoud
15000
mohammed
12000
samir
16000
27.9 Reverse
We can reverse a list using the reverse() function.
Syntax:
27.8. Sort 171

Reverse(List) ---> Reversed List
Example:
aList = [10,20,30,40,50]
aList = reverse(aList)
see aList # print 50 40 30 20 10
27.10 Insert Items
To insert an item in the list we can use the insert() function.
Syntax:
Insert(List,Index,Item)
The inserted item will be AFTER the Index
Example:
aList = ["A","B","D","E"]
insert(aList,2,"C") # Inserts AFTER Index 2, "C" into Position 3
see aList # print A B C D E
27.11 Nested Lists
The list may contain other lists
Example:
aList = [ 1 , [10,20,30] , 5 , [100,1000,5000] ]
aList2 = [
"one","two",
[3,4],
[20,30], ["three",
"four",
"five",[100,200,300]
]
]
see aList[2] # print 10 20 30
see aList[4][3] + nl # print 5000
see aList2[5][2] + nl # print four
see aList2[5][4][3] # print 300
27.12 Copy Lists
We can copy lists (including nested lists) using the Assignment operator.
Example:
27.10. Insert Items 172

aList = [
"one","two",
[3,4],
[20,30], ["three",
"four",
"five",[100,200,300]
]
]
aList2 = aList # Copy aList to aList2
aList2[5] = "other" # modify item number five
see aList2[5] + nl # print other
see aList[5] # print three four five 100 200 300
27.13 First-class lists
Lists are first-class citizens where we can store lists in variables, pass lists to functions, and return lists from functions.
Example:
aList = duplicate( [1,2,3,4,5] )
see aList[10] + nl # print 5
see mylist() # print 10 20 30 40 50
func duplicate list
nMax = len(list)
for x = 1 to nMax
list + list[x]
next
return list
func mylist return [10,20,30,40,50]
27.14 Using Lists during definition
We can use the list items while we are defining the list for the first time.
Example:
aList = [ [1,2,3,4,5] , aList[1] , aList[1] ]
see aList # print 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5
27.15 Passing Lists to Functions
Lists are passed to functions by reference, This means that the called function will work on the same list and can
modify it.
Example:
func main
aList = [1,2,3,4,5] # create list, local in function main
27.13. First-class lists 173

myfunc(aList) # call function, pass list by reference
see aList # print 1 2 3 4 5 6 7 8 9 10
func myfunc list
list + [6,7,8,9,10]
27.16 Access List Items by String Index
Instead of using numbers to determine the item index when we get item value or set item value, We can access items
using string index if the item is a list contains two items and the first item is a string.
Example:
aList = [ ["one",1] , ["two",2] , ["three",3] ]
see aList["one"] + nl +
aList["two"] + nl +
aList["three"] # print 1 2 3
This type of lists can be defined in a better syntax using the : and = operators.
Example:
aList = [ :one = 1 , :two = 2 , :three = 3 ]
see aList["one"] + nl +
aList["two"] + nl +
aList["three"] + nl # print 1 2 3
see aList[1] # print one 1
Tip: using : before identifier (one word) means literal
Note: using = inside list definition create a list of two items where the first item is the left side and the second item is
the right side.
We can add new items to the list using the string index
Example:
aList = []
aList["Egypt"] = "Cairo"
aList["KSA"] = "Riyadh"
see aList["Egypt"] + nl + # print Cairo
aList["KSA"] + nl # print Riyadh
27.17 Passing Parameters Using List
This type of lists is very good for passing parameters to functions Where the order of parameters will not be important
(we can change the order).
Also some parameters maybe optional.
Example:
27.16. Access List Items by String Index 174

myconnect ( [ :server = "myserver.com" , :port = 80 ,
:username = "mahmoud" , :password = "password" ] )
func myconnect mypara
# print connection details
see "User Name : " + mypara[:username] + nl +
"Password : " + mypara[:password] + nl +
"Server : " + mypara[:server] + nl +
"Port : " + mypara[:port]
27.18 Swap Items
We can swap the list items using the Swap() function.
Example:
aList = [:one,:two,:four,:three]
see aList
see copy("*",50) + nl
swap(aList,3,4)
see aList
Output
one
two
four
three
**************************************************
one
two
three
four
27.18. Swap Items 175

CHAPTER
TWENTYEIGHT
STRINGS
In this chapter we are going to learn about strings creation and manipulation.
28.1 String Literals
Syntax:
cStr = "This is a string"
cStr2 = 'Another string'
cStr3 = :JustAnotherString
cStr4 = `Yet "another" 'string' ! `
28.2 Get String Length
We can get the string length (letters count inside a string) using the len() function
Syntax:
len(string) ---> string length
Example:
cStr = "How are you?"
see cStr + nl
see "String size : " + len(cStr) + nl
28.3 Convert Letters Case
Syntax:
lower(string) ---> convert string letters to lower case
upper(string) ---> convert string letters to UPPER case
Example:
cStr = "Welcome To The Ring Programming Language"
see cStr + nl + upper(cStr) + nl + lower(cStr)
176

28.4 Access String Letters
We can access a letter inside a string by the letter index
Syntax:
string[index] ---> get string letter
string[index] = letter # set string letter
Example:
# print user name letter by letter (each letter in new line)
See "Hello, Enter your name : " give cName
for x = 1 to len(cName)
see nl + cName[x]
next
We can use for in to get string letters.
Example:
# print user name letter by letter (each letter in new line)
See "Hello, Enter your name : " give cName
for x in cName
see nl + x
next
We can modify the string letters
Example:
# convert the first letter to UPPER case
See "Enter your name : " give cName
cName[1] = upper(cName[1])
see "Hello " + cName
28.5 Left() Function
We can get a speciﬁed number of characters from a string using the Left() function.
The starting position is 1.
Syntax:
Left(string,count)
Example:
see left("Hello World!",5) # print Hello
28.6 Right() Function
We can get a speciﬁed number of characters from a string using the Right() function.
28.4. Access String Letters 177

The starting position is the last character on the right.
Syntax:
Right(string,count)
Example:
see Right("Hello World!",6) # print World!
28.7 Trim() Function
We can remove all leading and trailing spaces from a string using the Trim() function.
Syntax:
trim(string)
Example:
cMsg = " Welcome "
see trim(cMsg) # print Welcome
28.8 Copy() Function
We can duplicate a string more than one time using the copy() function.
Syntax:
copy(string,nCount) ---> string replicated nCount times
Example
see copy("***hello***",3) # print ***hello******hello******hello***
28.9 Lines() Function
We can count the number of lines inside a string using the Lines() function.
Syntax:
lines(string) ---> Number of lines inside the string
Example:
cStr = "Hello
How are you?
are you fine?"
see lines(cStr) # print 3
28.7. Trim() Function 178

28.10 Substr() Function
We can work on sub strings inside a string using the substr() function. Using Substr() we can
• Find substring
• Get substring from position to end
• Get Number of characters from position
• Transform Substring To Another Substring
28.11 Find substring
Syntax:
substr(string,substring) ---> the starting position of substring in string
Example:
cStr = "Welcome to the Ring programming language"
see substr(cStr,"Ring") # print 16
28.12 Get substring from position to end
Syntax:
substr(string,position) ---> Get substring starting from position to end
Example:
nPos = substr(cStr,"Ring") # nPos = 16
see substr(cStr,nPos) # print Ring programming language
28.13 Get Number of Characters From Position
Syntax:
substr(string,position,count) ---> Get characters starting from position
Example:
nPos = substr(cStr,"Ring") # nPos = 16
see substr(cStr,nPos,4) # print Ring
28.14 Transform Substring To Another Substring
Syntax:
28.10. Substr() Function 179

substr(string,substring,newsubstring) ---> Transformed string (Match case)
substr(string,substring,newsubstring,1) ---> Transformed string (Ignore case)
Example:
cStr = "Welcome to the New programming language"
see substr(cStr,"New","Ring") + nl # print Welcome to the Ring programming language
see substr(cStr,"new","Ring",1)+ nl # print Welcome to the Ring programming language
28.15 strcmp() Function
We can compare between two strings using the strcmp() function.
Syntax:
strcmp(cString1,cString2) ---> value = 0 if cString1 = cString2
value < 0 if cString1 < cString2
value > 0 if cString1 > cString2
Example:
see strcmp("hello","hello") + nl +
strcmp("abc","bcd") + nl +
strcmp("bcd","abc") + nl
Output:
0
-1
1
28.16 str2list() and list2str() Functions
We can convert string lines to list items using the str2list() function. Also we can convert the list to a string using
list2str() function.
Syntax:
str2list(string) ---> list contains the string lines
list2str(list) ---> string contains the list items
Example:
/* output:
** Items : 4
** Item : Hello
** Item : How are you ?
** Item : are you fine ?
** Item : ok
** list2Str result = Hello
** How are you ?
** are you fine ?
** ok
** Done
*/
28.15. strcmp() Function 180

mystr = "Hello
How are you ?
are you fine ?
ok"
mylist = str2list(mystr)
see "Items : " + len(mylist) + nl
for x in mylist
see "Item : " + x + nl
next
newstr = list2str(mylist)
see "list2Str result = " + newstr
if mystr = newstr
see nl + "Done"
else
see nl + "Error!"
ok
28.16. str2list() and list2str() Functions 181

CHAPTER
TWENTYNINE
DATE AND TIME
In this chapter we are going to learn about the date and time functions.
29.1 Clock() Function
Syntax:
Clock() ---> The number of clock ticks from program start
Example:
See "Calculate performance" + nl
t1 = clock()
for x = 1 to 1000000 next
see clock() - t1
29.2 ClocksPerSecond() Function
Return how many clocks in one second
Syntax:
clockspersecond() ---> Number of clocks in one second
Example:
# Wait 1 second
t = clock()
while clock() - t <= clockspersecond() end
29.3 Time() Function
We can get the system time using the Time() function.
Example:
See "Time : " + time()
182

29.4 Date() Function
We can get the date using the Date() function.
Syntax:
Date() ---> String represent the date "dd/mm/yyyy"
Example:
See "Date : " + date() # Date : 24/05/2015
29.5 TimeList() Function
We can print the date and the time information using the TimeList() function.
Syntax:
TimeList() ---> List contains the time and date information.
The next table presents the list items
index value
1 abbreviated weekday name
2 full weekday name
3 abbreviated month name
4 full month name
5 Date & Time
6 Day of the month
7 Hour (24)
8 Hour (12)
9 Day of the year
10 Month of the year
11 Minutes after hour
12 AM or PM
13 Seconds after the hour
14 Week of the year (sun-sat)
15 day of the week
16 date
17 time
18 year of the century
19 year
20 time zone
21 percent sign
Example:
/* Output:
** Sun abbreviated weekday name
** Sunday full weekday name
** May abbreviated month name
** May full month name
** 05/24/15 09:58:38 Date & Time
** 24 Day of the month
** 09 Hour (24)
29.4. Date() Function 183

** 09 Hour (12)
** 144 Day of the year
** 05 Month of the year
** 58 Minutes after hour
** AM AM or PM
** 38 Seconds after the hour
** 21 Week of the year (sun-sat)
** 0 day of the week
** 05/24/15 date
** 09:58:38 time
** 15 year of the century
** 2015 year
** Arab Standard Time time zone
** % percent sign
*/
See TimeList()
Example:
See "Day Name : " + TimeList()[2] # Sunday
Example:
See "Month Name : " + TimeList()[4] # May
29.6 AddDays() Function
Syntax:
AddDays(cDate,nDays) ---> Date from cDate and after nDays
Example:
cDate = date()
see cDate + nl # 24/05/2015
cDate = adddays(cDate,10)
see cDate + nl # 03/06/2015
29.7 DiffDays() Function
Syntax:
DiffDays(cDate1,cDate2) ---> number of days (Date1 - Date2)
Example:
cDate1 = date()
see cDate1 + nl # 24/05/2015
cDate2 = adddays(cDate1,10)
see cDate2 + nl # 03/06/2015
see "DiffDays = " + diffdays(cDate1,cDate2) + nl # -10
see "DiffDays = " + diffdays(cDate2,cDate1) + nl # 10
29.6. AddDays() Function 184

29.8 EpochTime() Function
Syntax:
EpochTime( cDate, cTime ) ---> Epoch Seconds
Example:
###-------------------------------------------------------------
# EpochTime()
# Example --- EpochSec = EpochTime( Date(), Time() )
# Call Format: EpochSec = EpochTime( "15/07/2016", "10:15:30" )
# EpochSec = 1468577730
#---------------------------------------------------------------
Func EpochTime(Date, Time)
arrayDate = split(Date, "/")
arrayTime = split(Time, ":")
Year = arrayDate[3] ; Month = arrayDate[2] ; Day = arrayDate[1]
Hour = arrayTime[1] ; Minute = arrayTime[2] ; Second = arrayTime[3]
cDate1 = Day +"/"+ Month +"/"+ Year
cDate2 = "01/01/" + Year
DayOfYear = DiffDays( cDate1, cDate2)
### Formula
tm_sec = Second * 1
tm_min = Minute * 60
tm_hour = Hour * 3600
tm_yday = DayOfYear * 86400
tm_year = Year - 1900
tm_year1 = ( tm_year - 70) * 31536000
tm_year2 = ( floor(( tm_year - 69) / 4 )) * 86400
tm_year3 = ( floor(( tm_year - 1) / 100 )) * 86400
tm_year4 = ( floor(( tm_year + 299) / 400 )) * 86400
### Result
EpochSec = tm_sec + tm_min + tm_hour + tm_yday + tm_year1 + tm_year2 - tm_year3 + tm_year4
return EpochSec
29.8. EpochTime() Function 185

CHAPTER
THIRTY
CHECK DATA TYPE AND CONVERSION
In this chapter we are going to learn about the functions that can be used for
• Checking Data Type
• Checking Character
• Conversion
30.1 Check Data Type
The next functions can be used to check the data type
• isstring()
• isnumber()
• islist()
• type()
• isnull()
30.2 IsString() Function
Using the IsString() function we can know if the value is a string or not
Syntax:
IsString(value) ---> 1 if the value is a string or 0 if not
Example:
see isstring(5) + nl + # print 0
isstring("hello") + nl # print 1
30.3 IsNumber() Function
Using the IsNumber() function we can know if the value is a number or not
Syntax:
186

IsNumber(value) ---> 1 if the value is a number or 0 if not
Example:
see isnumber(5) + nl + # print 1
isnumber("hello") + nl # print 0
30.4 IsList() Function
Using the IsList() function we can know if the value is a list or not
Syntax:
IsList(value) ---> 1 if the value is a list or 0 if not
Example:
see islist(5) + nl + # print 0
islist("hello") + nl + # print 0
islist([1,3,5]) # print 1
30.5 Type() Function
We can know the type of a value using the Type() Function.
Syntax:
Type(value) ---> The Type as String
Example:
see Type(5) + nl + # print NUMBER
Type("hello") + nl + # print STRING
Type([1,3,5]) # print LIST
30.6 IsNULL() Function
We can check the value to know if it’s null or not using the IsNULL() function
Syntax:
IsNULL(value) ---> 1 if the value is NULL or 0 if not
Example:
see isnull(5) + nl + # print 0
isnull("hello") + nl + # print 0
isnull([1,3,5]) + nl + # print 0
isnull("") + nl + # print 1
isnull("NULL") # print 1
30.4. IsList() Function 187

30.7 Check Character
The next functions can be used to check character
• isalnum()
• isalpha()
• iscntrl()
• isdigit()
• isgraph()
• islower()
• isprint()
• ispunct()
• isspace()
• isupper()
• isxdigit()
30.8 IsAlNum() Function
We can test a character or a string using the IsAlNum() Function
Syntax:
IsAlNum(value) ---> 1 if the value is digit/letter or 0 if not
Example:
see isalnum("Hello") + nl + # print 1
isalnum("123456") + nl + # print 1
isalnum("ABCabc123") + nl + # print 1
isalnum("How are you") # print 0 because of spaces
30.9 IsAlpha() Function
We can test a character or a string using the IsAlpha() Function
Syntax:
IsAlpha(value) ---> 1 if the value is a letter or 0 if not
Example:
see isalpha("Hello") + nl + # print 1
isalpha("123456") + nl + # print 0
isalpha("ABCabc123") + nl + # print 0
isalpha("How are you") # print 0
30.7. Check Character 188

30.10 IsCntrl() Function
We can test a character or a string using the IsCntrl() Function
Syntax:
IsCntrl(value) ---> 1 if the value is a control character (no printing position) or 0 if not
Example:
See iscntrl("hello") + nl + # print 0
iscntrl(nl) # print 1
30.11 IsDigit() Function
We can test a character or a string using the IsDigit() Function
Syntax:
IsDigit(value) ---> 1 if the value is a digit or 0 if not
Example:
see isdigit("0123456789") + nl + # print 1
isdigit("0123a") # print 0
30.12 IsGraph() Function
We can test a character or a string using the IsGraph() Function
Syntax:
IsGraph(value) ---> 1 if the value can be printed (Except space) or 0 if not
Example:
see isgraph("abcdef") + nl + # print 1
isgraph("abc def") # print 0
30.13 IsLower() Function
We can test a character or a string using the IsLower() Function
Syntax:
IsLower(value) ---> 1 if the value is lowercase letter or 0 if not
Example:
see islower("abcDEF") + nl + # print 0
islower("ghi") # print 1
30.10. IsCntrl() Function 189

30.14 IsPrint() Function
We can test a character or a string using the IsPrint() Function
Syntax:
IsPrint(value) ---> 1 if the value occupies a printing position or 0 if not
Example:
see isprint("Hello") + nl + # print 1
isprint("Nice to see you") + nl + # print 1
isprint(nl) # print 0
30.15 IsPunct() Function
We can test a character or a string using the IsPunct() Function
Syntax:
IsPunct(value) ---> 1 if the value is a punctuation character or 0 if not
Example:
see ispunct("hello") + nl + # print 0
ispunct(",") # print 1
30.16 IsSpace() Function
We can test a character or a string using the IsSpace() Function
Syntax:
IsSpace(value) ---> 1 if the value is a white-space or 0 if not
Example:
see isspace(" ") + nl + # print 1
isspace("test") # print 0
30.17 IsUpper() Function
We can test a character or a string using the IsUpper() Function
Syntax:
IsUpper(value) ---> 1 if the value is an uppercase alphabetic letter or 0 if not
Example:
see isupper("welcome") + nl + # print 0
isupper("WELCOME") # print 1
30.14. IsPrint() Function 190

30.18 IsXdigit() Function
We can test a character or a string using the IsXdigit() Function
Syntax:
IsXdigit(value) ---> 1 if the value is a hexdecimal digit character or 0 if not
Example:
see isxdigit("0123456789abcdef") + nl + # print 1
isxdigit("123z") # print 0
30.19 Conversion
The next functions can be used for conversion
• number()
• string()
• ascii()
• char()
• hex()
• dec()
• str2hex()
• hex2str()
30.20 Number() Function
We can convert strings to numbers using the Number() function or the + operator.
Syntax:
Number(string) ---> Number
0 + string ---> Number
Example:
see number("5") + 5 + nl # print 10
see 0 + "10" + 2 # print 12
30.21 String() Function
We can convert numbers to strings using the String() function or the + operator.
Syntax:
String(number) ---> String
"" + number ---> String
30.18. IsXdigit() Function 191

Example:
see string(5) + 5 + nl # print 55
see "" + 10 + 2 # print 102
30.22 Ascii() Function
We can get the ASCII code for a letter using the Ascii() function
Syntax:
Ascii(character) ---> ASCII Code
Example:
See ascii("m") + nl + # print 109
ascii("M") # print 77
30.23 Char() Function
We can convert the ASCII code to character using the Char() function.
Syntax:
Char(ASCII Code) ---> character
Example:
See char(109) + nl + # print m
char(77) # print M
30.24 Hex() Function
We can convert decimal to hexadecimal using the Hex() function.
Syntax:
Hex(decimal) ---> hexadecimal
Example:
See hex(10) + nl + # print a
hex(200) # print c8
30.25 Dec() Function
We can convert hexadecimal to decimal using the Dec() function
Syntax:
Dec(hexadecimal) ---> decimal
30.22. Ascii() Function 192

Example:
See dec("a") + nl + # print 10
dec("c8") # print 200
30.26 Str2hex() Function
We can convert string characters to hexadecimal characters using the Str2hex() function.
Syntax:
Str2hex(string) ---> hexadecimal string
Example:
See str2hex("hello") # print 68656c6c6f
30.27 Hex2str() Function
We can convert hexadecimal characters to string using the Hex2str() function
Syntax:
Hex2Str(Hexadecimal string) ---> string
Example:
See hex2str("68656c6c6f") # print hello
30.26. Str2hex() Function 193

CHAPTER
THIRTYONE
MATHEMATICAL FUNCTIONS
In this chapter we are going to learn about the mathematical functions
31.1 List of functions
The Ring programming language comes with the next mathematical functions
Function Description
sin(x) Returns the sine of an angle of x radians
cos(x) Returns the cosine of an angle of x radians
tan(x) Returns the tangent of an angle of x radians
asin(x) Returns the principal value of the arc sine of x, expressed in radians
acos(x) Returns the principal value of the arc cosine of x, expressed in radians
atan(x) Returns the principal value of the arc tangent of x, expressed in radians
atan2(y,x) Returns the principal arc tangent of y/x, in the interval [-pi,+pi] radians
sinh(x) Returns the hyperbolic sine of x radians
cosh(x) Returns the hyperbolic cosine of x radians
tanh(x) Returns the hyperbolic tangent of x radians
exp(x) Returns the value of e raised to the xth power
log(x) Returns the natural logarithm of x
log10(x) Returns the common logarithm (base-10 logarithm) of x
ceil(x) Returns the smallest integer value greater than or equal to x
ﬂoor(x) Returns the largest integer value less than or equal to x
fabs(x) Returns the absolute value of x.
pow(x,y) Returns x raised to the power of y
sqrt(x) Returns the square root of x
random(x) Returns a random number in the range [0,x]
unsigned(n,n,c) Perform operation using unsigned numbers
decimals(n) Determine the decimals digits after the point in ﬂoat/double numbers
31.2 Example
See "Mathematical Functions" + nl
See "Sin(0) = " + sin(0) + nl
See "Sin(90) radians = " + sin(90) + nl
See "Sin(90) degree = " + sin(90*3.14/180) + nl
See "Cos(0) = " + cos(0) + nl
See "Cos(90) radians = " + cos(90) + nl
194

See "Cos(90) degree = " + cos(90*3.14/180) + nl
See "Tan(0) = " + tan(0) + nl
See "Tan(90) radians = " + tan(90) + nl
See "Tan(90) degree = " + tan(90*3.14/180) + nl
See "asin(0) = " + asin(0) + nl
See "acos(0) = " + acos(0) + nl
See "atan(0) = " + atan(0) + nl
See "atan2(1,1) = " + atan2(1,1) + nl
See "sinh(0) = " + sinh(0) + nl
See "sinh(1) = " + sinh(1) + nl
See "cosh(0) = " + cosh(0) + nl
See "cosh(1) = " + cosh(1) + nl
See "tanh(0) = " + tanh(0) + nl
See "tanh(1) = " + tanh(1) + nl
See "exp(0) = " + exp(0) + nl
See "exp(1) = " + exp(1) + nl
See "log(1) = " + log(1) + nl
See "log(2) = " + log(2) + nl
See "log10(1) = " + log10(1) + nl
See "log10(2) = " + log10(2) + nl
See "log10(10) = " + log10(10) + nl
See "Ceil(1.12) = " + Ceil(1.12) + nl
See "Ceil(1.72) = " + Ceil(1.72) + nl
See "Floor(1.12) = " + floor(1.12) + nl
See "Floor(1.72) = " + floor(1.72) + nl
See "fabs(1.12) = " + fabs(1.12) + nl
See "fabs(1.72) = " + fabs(1.72) + nl
See "pow(2,3) = " + pow(2,3) + nl
see "sqrt(16) = " + sqrt(16) + nl
Program Output:
Mathematical Functions
Sin(0) = 0
Sin(90) radians = 0.89
Sin(90) degree = 1.00
Cos(0) = 1
Cos(90) radians = -0.45
Cos(90) degree = 0.00
Tan(0) = 0
Tan(90) radians = -2.00
Tan(90) degree = 1255.77
asin(0) = 0
acos(0) = 1.57
atan(0) = 0
atan2(1,1) = 0.79
sinh(0) = 0
sinh(1) = 1.18
cosh(0) = 1
31.2. Example 195

cosh(1) = 1.54
tanh(0) = 0
tanh(1) = 0.76
exp(0) = 1
exp(1) = 2.72
log(1) = 0
log(2) = 0.69
log10(1) = 0
log10(2) = 0.30
log10(10) = 1
Ceil(1.12) = 2
Ceil(1.72) = 2
Floor(1.12) = 1
Floor(1.72) = 1
fabs(1.12) = 1.12
fabs(1.72) = 1.72
pow(2,3) = 8
sqrt(16) = 4
31.3 Random() Function
The Random() function generate a random number and we can set the maximum value (optional).
Syntax:
Random(x) ---> Random number in the range [0,x]
Example:
for x = 1 to 20
see "Random number : " + random() + nl +
"Random number Max (100) : " + random(100) + nl
next
Program Output:
Random number : 31881
Random number Max (100) : 80
31.3. Random() Function 196

31.4 Unsigned() Function
We can use unsigned numbers using the Unsigned() function.
Syntax:
Unsigned(nNum1,nNum2,cOperator) --> result of cOperator operation on nNum1,nNum2
Example:
see oat_hash("hello") + nl
# Jenkins hash function - https://en.wikipedia.org/wiki/Jenkins_hash_function
func oat_hash cKey
h = 0
for x in cKey
h = unsigned(h,ascii(x),"+")
h = unsigned(h,unsigned(h,10,"<<"),"+")
r = unsigned(h,6,">>")
h = unsigned(h, r,"^")
next
h = unsigned(h,unsigned(h,11,">>"),"^")
return h
Output:
3372029979.00
31.5 Decimals() Functions
We can determine the decimals numbers count after the point in ﬂoat/double numbers using the decimals() function.
Syntax:
31.4. Unsigned() Function 197

Decimals(nDecimalsCount)
Example:
x = 1.1234567890123
for d = 0 to 14
decimals(d)
see x + nl
next
Output:
1
1.1
1.12
1.123
1.1235
1.12346
1.123457
1.1234568
1.12345679
1.123456789
1.1234567890
1.12345678901
1.123456789012
1.1234567890123
1.12345678901230
31.5. Decimals() Functions 198

CHAPTER
THIRTYTWO
FILES
In this chapter we are going to learn about files functions.
• Read()
• Write()
• Dir()
• Rename()
• Remove()
• fopen()
• fclose()
• fflush()
• freopen()
• tempfile()
• tempname()
• fseek()
• ftell()
• rewind()
• fgetpos()
• fsetpos()
• clearerr()
• feof()
• ferror()
• perror()
• fgetc()
• fgets()
• fputc()
• fputs()
• ungetc()
• fread()
199

• fwrite()
• fexists()
• Numbers and Bytes
32.1 Read() Function
We can read the file content using the Read() function
Syntax:
Read(cFileName) ---> String contains the file content
Example:
see read("myfile.txt")
The read function can read binary files too
Example:
see read("myapp.exe")
32.2 Write() Function
We can write string to file using the Write() function
The write function can write binary data to binary files.
Syntax:
Write(cFileName,cString) # write string cString to file cFileName
Example:
# copy file
cFile = read("ring.exe")
write("ring2.exe",cFile)
32.3 Dir() Function
We can get the folder contents (files & sub folders) using the Dir() function.
Syntax:
Dir(cFolderPath) ---> List contains files & sub folders.
This function returns a list and each list item is a list of two items
• File/sub folder name
• Type (0 = File , 1 = Folder/Directory)
Example:
32.1. Read() Function 200

see "Testing DIR() " + nl
mylist = dir("C:myfolder")
for x in mylist
if x[2]
see "Directory : " + x[1] + nl
else
see "File : " + x[1] + nl
ok
next
see "Files count : " + len(mylist)
32.4 Rename() Function
We can rename files using the Rename() function
Syntax:
Rename(cOldFileName,cNewFileName)
Example:
rename("file.txt","help.txt")
32.5 Remove() Function
We can delete a file using the Remove() function
Syntax:
Remove(cFileName)
Example:
remove("test.txt")
32.6 Fopen() Function
We can open a file using the Fopen() function
Syntax:
Fopen(cFileName,cMode) ---> File Handle
Mode Description
“r” Reading (The file must exist)
“w” Writing (create empty file / overwrite)
“a” Appends (create file if it doesn’t exist)
“r+” update (reading/writing)
“w+” Create empty file (reading/writing)
“a+” reading & appending
32.4. Rename() Function 201

32.7 Fclose() Function
When we open a file using fopen() function, we can close it using the Fclose() function
Syntax:
Fclose(file handle)
32.8 Fflush() Function
We can flushes the output buffer of a stream using the Fflush() function
Syntax:
Fflush(file handle)
32.9 Freopen() Function
We can open another file using the same file handle and at the same time close the old file
Syntax:
Freopen(cFileName,cMode,file handle) ---> file handle
Example:
freopen("myprogoutput.txt","w+",stdout)
see "welcome" + nl
for x = 1 to 10
see x + nl
next
/*
** Read : https://en.wikipedia.org/wiki/Device_file#Device_files
** The next code is not portable, we can use iswindows() before
** using it and we can write special code for each operating system.
*/
freopen("CON","w",stdout) # For Microsoft Windows
see "Done" + nl # print to stdout again
Output:
# Output to stdout
Done
# Output to file : myprogoutput.txt
welcome
1
2
3
4
5
6
7
32.7. Fclose() Function 202

8
9
10
32.10 Tempfile() Function
The function Tempfile() creates a temp. file (binary).
The file will be deleted automatically when the stream is closed
Syntax:
TempFile() ---> file handle
32.11 Tempname() Function
We can generate temp. file name using the Tempname() function
The generated name will be different from the name of any existing file
Syntax:
Tempname() ---> generated file name as string
32.12 Fseek() Function
We can set the file position of the stream using the Fseek() function
Syntax:
Fseek(file handle, nOffset, nWhence) ---> zero if successful
The next table presents the nWhence values
Value Description
0 Beginning of file
1 Current position
2 End of file
32.13 Ftell() Function
We can know the current file position of a stream using the Ftell() function
Syntax:
Ftell(file handle) ---> file position as number
32.10. Tempfile() Function 203

32.14 Rewind() Function
We can set the file position to the beginning of the file using the Rewind() function
Syntax:
Rewind(file handle)
32.15 Fgetpos() Function
We can get handle to the current file position using the Fgetpos() function
Syntax:
Fgetpos(file handle) ---> position handle
32.16 Fsetpos() Function
We can set the current file position using the Fgetpos() function
Syntax:
Fsetpos(file handle,position handle)
32.17 Clearerr() Function
We can clear the EOF error and the error indicators of a stream using the clearerr() function
Syntax:
Clearerr(file handle)
32.18 Feof() Function
We can test the end-of-file indicator using the Feof() function
Syntax:
Feof(file handle) ---> returns 1 if EOF and 0 if not
32.19 Ferror() Function
We can test the error indicator of a given stream using the Ferror() function
Syntax:
Ferror(file handle) ---> returns 1 if error and 0 if not
32.14. Rewind() Function 204

32.20 Perror() Function
We can print error message to the stderr using the Perror() function
Syntax:
Perror(cErrorMessage)
32.21 Fgetc() Function
We can get the next character from the stream using the Fgetc() function
Syntax:
Fgetc(file handle) ---> returns character or EOF
32.22 Fgets() Function
We can read new line from the stream using the Fgets() function
Syntax:
Fgets(file handle,nSize) ---> string
The function stop when nSize characters are read, new line character is read or EOF.
32.23 Fputc() Function
We can write a character to the stream using the Fputc() function
Syntax:
Fputc(file handle,cChar)
32.24 Fputs() Function
We can write a string to the stream using the Fputs() function
Syntax:
Fputs(file handle,cString)
32.25 Ungetc() Function
We can push a character to the stream using the Ungetc() function
The character will be available for the next read
Syntax:
32.20. Perror() Function 205

Ungetc(file handle,character)
32.26 Fread() Function
We can read data from a stream using the Fread() function
Syntax:
Fread(file handle,nSize)
32.27 Fwrite() Function
We can write data to a stream using the Fwrite() function
Syntax:
Fwrite(file handle,cString)
32.28 Fexists() Function
We can check if a ﬁle exists using the Fexists() function
Syntax:
Fexists(cFileName) ---> returns 1 if the file exists
Example:
see fexists("b:mahmoudappsringring.exe") + nl +
fexists("b:mahmoudappsringring2.exe") + nl
Output:
1
0
32.29 Example
The next program test some of the ﬁle functions
See "testing file functions" + nl
See "open file" + nl
fp = fopen(exefolder() + "../tests/scripts/s65.ring","r")
See "reopen" + nl
fp = freopen(exefolder() + "../tests/scripts/s78.ring","r",fp)
See "close file" + nl
fclose(fp)
see "temp file" + nl
32.26. Fread() Function 206

fp = tempfile()
fclose(fp)
see "temp name" + nl
see tempname() + nl
remove(exefolder() + "../tests/scripts/mytest2.txt")
write(exefolder() + "../tests/scripts/tests1.txt","hello")
rename(exefolder() + "../tests/scripts/test1.txt",exefolder() +
"../tests/scripts/mytests2.txt")
see "print file" + nl
fp = fopen(exefolder() + "../samples/fromdoc/filefuncs.ring","r")
r = fgetc(fp)
while isstring(r)
see r
r = fgetc(fp)
end
fclose(fp)
see nl+"print line from the file" + nl
fp = fopen(exefolder() + "../samples/fromdoc/filefuncs.ring","r")
r = fgets(fp,33)
see r + nl
fclose(fp)
fp = fopen(exefolder() + "../tests/scripts/test78.txt","w+")
fseek(fp,0,2) # goto end of file
fputc(fp,"t")
fputc(fp,"e")
fputc(fp,"s")
fputc(fp,"t")
fputs(fp,"tests2")
fclose(fp)
see "print file" + nl
see read(exefolder() + "../tests/scripts/test78.txt")
fp = fopen(exefolder() + "../tests/scripts/test78.txt","r")
see "testing ungetc() " + nl
for x = 1 to 3
r = fgetc(fp)
see r + nl
ungetc(fp,r)
next
fclose(fp)
see "testing fread() " + nl
fp = fopen(exefilename(),"rb")
r = fread(fp,100)
see r + nl
fclose(fp)
see "testing fwrite() " + nl
fp = fopen(exefolder() + "../tests/scripts/test1.txt","wb")
fwrite(fp,r)
fclose(fp)
The next example print part of the content of a binary ﬁle
32.29. Example 207

see "Testing: fread()" +" FileName: "+ exefilename() +nl +nl
fp = fopen(exefilename(),"rb")
r = fread(fp,800)
for n =1 to len(r)
if isprint(substr(r, n, 1))
see substr(r, n, 1)
else
see "."
ok
### 80 char per line
if n % 80 = 0
see nl
ok
next
fclose(fp)
32.30 Numbers and Bytes
The next functions to convert between Numbers and Bytes.
• Int2Bytes()
• Float2Bytes()
• Double2Bytes()
• Bytes2Int()
• Bytes2Float()
• Bytes2Double()
Example:
see "Test Int2Bytes() and Bytes2Int() - Value : 77" + nl
r = Int2Bytes(77)
see "Int Size : " + len(r) + nl
see r + nl
see Bytes2Int(r) + nl
see "Test Float2Bytes() and Bytes2Float() - Value 77.12" + nl
r = Float2Bytes(77.12)
see "Float Size : " + len(r) + nl
see r + nl
see Bytes2Float(r) + nl
see "Test Double2Bytes() and Bytes2Double() - Value 9999977.12345" + nl
r = Double2Bytes(9999977.12345)
see "Double Size : " + len(r) + nl
see r + nl
decimals(5)
see Bytes2Double(r) + nl
32.30. Numbers and Bytes 208

CHAPTER
THIRTYTHREE
SYSTEM FUNCTIONS
In this chapter we are going to learn about the system functions
• System()
• SystemCmd()
• SysGet()
• IsMSDOS()
• IsWindows()
• IsWindows64()
• IsUnix()
• IsMacOSX()
• IsLinux()
• IsFreeBSD()
• IsAndroid()
• Windowsnl()
• Get Command Line Arguments
• Get Active Source File Name
• CurrentDir()
• ExeFileName()
• ChDir()
• ExeFolder()
• Version()
• Shutdown()
33.1 System() Function
We can execute system commands using the system() function
Syntax:
System(cCommand)
209

Example:
System("myapp.exe") # Run myapp.exe
System("ls") # print list of files
33.2 SysGet() Function
We can get environment variables using the Get() function
Syntax:
SysGet(cVariable)
Example:
see sysget("path") # print system path information
33.3 IsMSDOS() Function
We can check if the operating system is MSDOS or not using the IsMSDOS() function
Syntax:
IsMSDOS() ---> Returns 1 if the operating system is MS-DOS, Returns 0 if it's not
33.4 IsWindows() Function
We can check if the operating system is Windows or not using the IsWindows() function
Syntax:
IsWindows() ---> Returns 1 if the operating system is Windows, Returns 0 if it's not
33.5 IsWindows64() Function
We can check if the operating system is Windows 64bit or not using the IsWindows64() function
Syntax:
IsWindows64() ---> Returns 1 if the operating system is Windows64, Returns 0 if it's not
33.6 IsUnix() Function
We can check if the operating system is Unix or not using the IsUnix() function
Syntax:
IsUnix() ---> Returns 1 if the operating system is Unix, Returns 0 if it's not
33.2. SysGet() Function 210

The Ring programming language version 1.5 book - Part 4 of 31

More Related Content

What's hot (20)

Similar to The Ring programming language version 1.5 book - Part 4 of 31 (20)

More from Mahmoud Samir Fayed (20)

Recently uploaded (20)

The Ring programming language version 1.5 book - Part 4 of 31