Stdlib Functions

In this chapter we are going to learn about functions in the stdlib.ring

Before using the functions in the library, We must load the library first

load "stdlib.ring"

Instead of using stdlib.ring we can use stdlibcore.ring

Using stdlibcore.ring we can use the StdLib functions (Without Classes)

load "stdlibcore.ring"

This is useful when developing standalone console applications

Because using stdlib.ring (functions & classes) will load libraries like RingLibCurl, RingOpenSSL, etc.

Also, Using stdlibclasses.ring we can load stdlib classes without loading functions or extensions like RingLibCurl, RingOpenSSL, etc.

load "stdlibclasses.ring"

IsAppCompiled() function

check whether the application has been compiled using Ring2EXE

Syntax:

IsAppCompiled() ---> True/False

Example:

Load "stdlib.ring"

Puts("Test IsAppCompiled()")
if IsAppCompiled() see "Application has been compiled using Ring2EXE"
else see "Application is running under Ring interpreter" ok

AppArguments() function

Get the effective arguments passed to the Ring script

Syntax:

AppArguments() ---> The arguments as a list of strings

Example:

Load "stdlib.ring"

# Application Arguments
Puts("Test AppArguments()")
argsList = AppArguments()
argsCount = Len(argsList)
if argsCount = 0 see "No arguments passed to the Ring script" + nl
else see "Ring script arguments = " + nl + list2str(argsList) + nl ok

AppPath() function

Get the path of the application folder

Syntax:

AppPath() ---> The path as String

Example:

Load "stdlib.ring"

# Application Path
Puts("Test AppPath()")
See AppPath() + nl

JustFilePath() function

Get the path of the file, remove the file name.

Syntax:

JustFilePath(cFile) ---> The path as String

Example:

load "stdlib.ring"

see  justfilePath("b:\ring\applications\rnote\rnote.ring")

Output:

b:\ring\applications\rnote\

JustFileName() function

Get the file, remove the file path.

Syntax:

JustFileName(cFile) ---> The file name as String

Example:

load "stdlib.ring"

see justfileName("b:\ring\applications\rnote\rnote.ring")

Output:

rnote.ring

Value() function

create a copy from a list or object

Syntax:

value(List) ---> new list

Example:

Load "stdlib.ring"

aList = 1:10
del(value(aList),1) # delete first item
see aList           # print numbers from 1 to 10

Times() function

Execute a Function nCount times

Syntax:

Times(nCount,function)

Example:

Load "stdlib.ring"

Puts("Test Times()")
Times ( 3 , func { see "Hello, World!" + nl } )

Map() function

Execute a Function on each list item

Syntax:

Map(alist,function) ---> List

Example:

Load "stdlib.ring"

Puts("Test Map()")
See Map( 1:10, func x { return x*x } )

Filter() function

Execute a Function on each list item to filter items

Syntax:

Filter(alist,function) ---> List

Example:

Load "stdlib.ring"

Puts("Test Filter()")
See Filter( 1:10 , func x { if x <= 5 return true else return false ok } )

Reduce() function

Apply function cFunc to each result xResult from a list aList, return an accumulated value xResult

The input list aList, the optional intial value xInitial and the output xResult, need to be the same Type

Syntax:

Reduce(aList,cFunc,xInitial) ---> final value

Example:

Load "stdlib.ring"

? Reduce( 1:3, func x, y { return x + y }, 0 )
? Reduce( ["I","Love","Ring"], func x, y { return x + y }, "" )

Output:

6
ILoveRing

Split() function

Convert string words to list items

Syntax:

Split(cstring,delimiter) ---> List

Example:

Load "stdlib.ring"

Puts("Test Split()")
See Split("one two three four five"," ")

SplitMany() function

Convert string words to list items. Allow many delimiters.

Syntax:

SplitMany(cstring,delimiters as string or list) --> List

Example:

Load "stdlib.ring"

Puts("Test SplitMany()")
See SplitMany("one,two,three,four and five"," ,")

Capitalized() function

Return a copy of a string with the first letter capitalized

Syntax:

Capitalized(string) ---> string

Example:

Load "stdlib.ring"

Puts("Test Capitalized()")
See capitalized("welcome to the Ring Programming Language")

IsSpecial() function

Check whether a character is special or not

Syntax:

IsSpecial(char) ---> True/False

Example:

Load "stdlib.ring"

Puts("Test Isspecial()")
See "Isspecial  = " + isSpecial("%") + nl

IsVowel() function

Check whether a character is vowel or not

Syntax:

IsVowel(char) ---> True/False

Example:

Load "stdlib.ring"

Puts("Test Isvowel()")
See "Isvowel = " + isVowel("c") + nl

LineCount() function

Return the lines count in a text file.

Syntax:

LineCount(cFileName) ---> Lines Count as number

Example:

Load "stdlib.ring"

Puts("Test Linecount()")
See "the number of lines = " + lineCount("test.ring")

Factorial() function

Return the factorial of a number

Syntax:

Factorial(number) ---> number

Example:

Load "stdlib.ring"

Puts("Test Factorial()")
see "6 factorial is : " + Factorial(6)

Fibonacci() function

Return the fibonacci number

Syntax:

Fibonacci(number) ---> number

Example:

Load "stdlib.ring"

Puts("Test Fibonacci()")
see "6 Fibonacci is : " + Fibonacci(6)

IsPrime() function

Check whether a number is prime or not

Syntax:

isprime(number) ---> Number

Example:

Load "stdlib.ring"

Puts("Test Isprime()")
if isPrime(16) see "16 is a prime number"
else see "16 is not a prime number" ok

Sign() function

Returns an integer value indicating the sign of a number.

Syntax:

Sign(number) ---> number ( -1 = negative , 0 , 1 (positive) )

Example:

Load "stdlib.ring"

Puts("Test Sign()")
see "sign of 12 is = " + sign(12) + nl

List2File() function

Write list items to text file (each item in new line).

Syntax:

List2File(aList,cFileName)

Example:

Load "stdlib.ring"

# Test List2File
Puts("Test List2File()")
list2file(1:100,"myfile.txt")

File2List() function

Read text file and convert lines to list items

Syntax:

File2List(cFileName) ---> List

Example:

Load "stdlib.ring"

# Test File2List
Puts("Test File2List()")
see len(file2list("myfile.txt"))

StartsWith() function

Returns true if the given string starts with the specified substring.

Leading white spaces are ignored.

Syntax:

StartsWith(string, substring) ---> True/False

Example:

Load "stdlib.ring"

Puts("Test Startswith()")
see Startswith("CalmoSoft", "Calmo") + nl

EndsWith() function

Returns true if the given string ends with the specified substring.

Trailing white spaces are ignored.

Syntax:

Endswith(string, substring) ---> True/False

Example:

Load "stdlib.ring"

Puts("Test Endswith()")
see endsWith("CalmoSoft", "Soft") + nl

GCD() function

Finding of the greatest common divisor of two integers.

Syntax:

Gcd(number,number) ---> number

Example:

Load "stdlib.ring"

Puts("Test Gcd()")
see gcd (24, 32) + nl

LCM() function

Compute the least common multiple of two integers.

Syntax:

lcm(number,number) ---> number

Example:

Load "stdlib.ring"

Puts("Test Lcm()")
see Lcm(24,36) + nl

SumList() function

Compute the sum of a list of integers.

Syntax:

sumlist(list) ---> number

Example:

Load "stdlib.ring"

Puts("Test Sumlist()")
aList = [1,2,3,4,5]
see Sumlist(aList) + nl

ProdList() function

Compute the product of a list of integers.

Syntax:

prodlist(list) ---> number

Example:

Load "stdlib.ring"

Puts("Test Prodlist()")
aList = [1,2,3,4,5]
see Prodlist(aList) + nl

EvenOrOdd() function

Test whether an integer is even or odd.

Result of test (1=odd 2=even).

Syntax:

evenorodd(number) ---> 1 (odd) or 2 (even)

Example:

Load "stdlib.ring"

Puts("Test Evenorodd()")
nr = 17
see Evenorodd(nr) + nl

Factors() function

Compute the factors of a positive integer.

Syntax:

factors(number) ---> list

Example:

Load "stdlib.ring"

Puts("Test Factors()")
n = 45
aList = factors(n)
see "Factors of " + n + " = "
for i = 1 to len(aList)
    see "" + aList[i] + " "
next

IsPalindrome() function

Check if a sequence of characters is a palindrome or not.

Syntax:

IsPalindrome(String) ---> True/False

Example:

Load "stdlib.ring"

Puts("Test IsPalindrome()")
cString = "radar"
see IsPalindrome(cString)

IsLeapYear() function

Check whether a given year is a leap year in the Gregorian calendar.

Syntax:

Isleapyear(number) ---> True/False

Example:

Load "stdlib.ring"

Puts("Test Isleapyear()")
year = 2016
if Isleapyear(year) see "" + year + " is a leap year."
else see "" + year + " is not a leap year." ok

BinaryDigits() function

Compute the sequence of binary digits for a given non-negative integer.

Syntax:

binarydigits(number) ---> string

Example:

Load "stdlib.ring"

Puts("Test Binarydigits()")
b = 35
see "Binary digits of " + b + " = " + Binarydigits(b)

MatrixMulti() function

Multiply two matrices together.

Syntax:

Matrixmulti(List,List) ---> List

Example:

Load "stdlib.ring"

# Multiply two matrices together.
Puts("Test Matrixmulti()")
A = [[1,2,3], [4,5,6], [7,8,9]]
B = [[1,0,0], [0,1,0], [0,0,1]]
see Matrixmulti(A, B)

MatrixTrans() function

Transpose an arbitrarily sized rectangular Matrix.

Syntax:

Matrixtrans(List) ---> List

Example:

Load "stdlib.ring"

# Transpose an arbitrarily sized rectangular Matrix.
Puts("Test Matrixtrans()")
matrix = [[78,19,30,12,36], [49,10,65,42,50], [30,93,24,78,10], [39,68,27,64,29]]
see Matrixtrans(matrix)

DayOfWeek() function

Return the day of the week of given date. (yyyy-mm-dd)

Syntax:

dayofweek(string) ---> string

Example:

Load "stdlib.ring"

# Return the day of the week of given date.
Puts("Test Dayofweek()")
date = "2016-04-24"
see "Data : " + date + " - Day : " + Dayofweek(date) + nl

Permutation() function

Generates all permutations of n different numerals.

Syntax:

permutation(list)

Example:

Load "stdlib.ring"

# Generates all permutations of n different numerals
Puts("Test Permutation()")
list = [1, 2, 3, 4]
for perm = 1 to 24
        for i = 1 to len(list)
                see list[i] + " "
        next
        see nl
        Permutation(list)
next

ReadLine() function

Read line from file

Syntax:

readline(fp) ---> string

Example:

Load "stdlib.ring"

# Read a file line by line.
Puts("Test Readline()")
fp = fopen("test.ring","r")
while not feof(fp)
See Readline(fp) end
fclose(fp)

SubString() function

Return a position of a substring starting from a given position in a string.

Syntax:

Substring(str,substr,npos) ---> string

Example:

Load "stdlib.ring"

# Return a position of a substring starting from a given position in a string.
Puts("Test Substring()")
a = "abcxyzqweabc"
b = "abc"
i = 4
see substring(a,b,i)

ChangeString() function

Change substring from given position to a given position with another substring.

Syntax:

Changestring(cString, nPos1, nPos2, cSubstr) ---> cString

Example:

Load "stdlib.ring"

# Change substring from given position for given position with a substring.
Puts("Test Changestring()")
see Changestring("Rmasdg",2,5,"in")     # Ring

Sleep() function

Sleep for the given amount of time.

Syntax:

sleep(nSeconds)

Example:

Load "stdlib.ring"

Puts("Test Sleep()")
see "Wait 3 Seconds!"
Sleep(3)
see nl

IsMainSourceFile() function

Check if the current file is the main source file

Syntax:

IsMainSourceFile() ---> True/False

Example:

Load "stdlib.ring"

if ismainsourcefile()
        # code
ok

MakeDir() function

Make Directory

Syntax:

MakeDir(String)

Example:

Load "stdlib.ring"

# Create Directory
puts("create Directory : myfolder")
makedir("myfolder")

Fsize() function

The function return the file size in bytes.

Syntax:

FSize(File Handle) ---> Number (File Size in Bytes)

TrimAll() function

Remove all spaces and tabs characters from a string

Syntax:

TrimAll(cString) ---> cString # Without Spaces and Tabs

TrimLeft() function

Remove all spaces and tabs characters from the left side of a string

Syntax:

TrimLeft(cString) ---> cString # Without Spaces and Tabs from the left side

TrimRight() function

Remove all spaces and tabs characters from the right side of a string

Syntax:

TrimRight(cString) ---> cString # Without Spaces and Tabs from the right side

EpochTime() function

Return the Epoch Time

Syntax:

EpochTime(cDate,cTime) ---> nEpochTime

Example:

see EpochTime( Date(), Time() )

SystemCmd() Function

We can execute system commands using the SystemCmd() function that outputs to a variable

Syntax:

SystemCmd(cCommand)

Example:

cYou  = SystemCmd("whoami")        # User Name logged in is output a variable
cThem = SystemCmd("dir c:\Users")  # Directory List is output to a variable

ListAllFiles() Function

Using this function we can quickly do a process on a group of files in a folder and it’s sub folders.

Syntax:

ListAllFiles(cFolder,cExtension) ---> List of Files

Example:

aList = ListAllFiles("c:/ring/ringlibs","ring") # *.ring only
aList = sort(aList)
see aList

Example:

see listallfiles("b:/ring/libraries/weblib","") # All Files

SystemSilent() Function

We can execute system commands using the SystemSilent() function to avoid displaying the output!

Syntax:

SystemSilent(cCommand)

OSCreateOpenFolder() Function

Create folder then change the current folder to this new folder

Syntax:

OSCreateOpenFolder(cCommand)

OSCopyFolder() Function

Copy folder to the current folder

Parameters : The path to the parent folder and the folder name to copy

Syntax:

OSCopyFolder(cParentFolder,cFolderName)

Example

To copy the folder b:\ring\ringlibs\stdlib to the current folder

OSCopyFolder("b:\ring\ringlibs\","stdlib")

OSDeleteFolder() Function

Delete Folder in the current Directory

Syntax:

OSDeleteFolder(cFolderName)

OSCopyFile() Function

Copy File to the current directory

Syntax:

OSCopyFile(cFileName)

OSDeleteFile() Function

Delete File

Syntax:

OSDeleteFile(cFileName)

OSRenameFile() Function

Rename File

Syntax:

OSRenameFile(cOldFileName,cNewFileName)

List2Code() Function

This function convert a Ring list during the runtime to Ring source code that we can save to source files.

The list may contains strings, numbers or sub lists.

Example:

load "stdlibcore.ring"
aList = 1:10
? list2Code(aList)

Output:

[
        1,2,3,4,5,6,7,8,9,10
]

Str2ASCIIList()

Convert a string of bytes to a list of numbers where each item represent the ASCII code of one byte in the string.

Syntax:

Str2ASCIIList(String) ---> List of numbers

ASCIIList2Str()

Convert a list of numbers where each item represent the ASCII code of one byte to a string of bytes.

Syntax:

ASCIIList2Str(List of numbers) ---> String

Example:

load "stdlibcore.ring"

cStr = "MmMm"

aList = Str2ASCIILIST(cStr)
? aList

cStr2 = ASCIIList2Str(aList)
? cStr2
? len(cStr2)

Output:

77
109
77
109

MmMm
4

IsListContainsItems()

Syntax:

IsListContainsItems(aParent,aChild) ----> True/False

Example:

load "stdlibcore.ring"
aList1 = "a":"z"
aList2 = [:h,:l,:p,:u]
? IsListContainsItems(aList1,aList2)

IsBetween()

Syntax:

IsBetween(nNumber,nMin,nMax) ----> True/False

Example:

load "stdlibcore.ring"
? isBetween(1,3,4)
? isBetween(1,-3,4)
? isBetween(4,1,6)
? isBetween(4,3,4)

TimeInfo()

Syntax:

TimeInfo(cInformation) ----> String

The cInformation value could be

:hour_24
:hour_12
:minutes
:seconds
:time
:day_short
:day_long
:month_short
:month_long
:date_time
:day
:day_year
:month_year
:am_pm
:week_year
:day_week
:date
:year_century
:year
:time_zone
:percent_sign

Example:

load "stdlibcore.ring"
? timeInfo(:date)
? timeInfo(:time)
? timeInfo(:hour_12)

RandomList()

Syntax:

RandomList(aList) --> List contains the same items using Random order

Example:

load "stdlib.ring"
aList = 1:5
? RandomList(aList)

RandomItem()

Pick an item from a list (Random Choice)

Syntax:

RandomItem(aList) --> Item

Example:

load "stdlib.ring"
aList = 1:5
? RandomItem(aList)

CheckEquality()

Check if two items are equal. Deep comparison is performed if the two items are lists Return 1 if both items are equal and 0 otherwise

Syntax:

CheckEquality(aItem1,aItem2) --> value = 1 if aItem1 = aItem2
                               value = 0 if aItem1 != aItem2

Example:

load "stdlib.ring"
aList1 = ["one", 2, [3]]
aList2 = ["one", 2]
aList2 + [3]
? CheckEquality(aList1,aList2)