built-in-functions.md

Built-in functions

I/O

• andika(kitu: any[, ...vitu: any[]]): SWNull
  Prints given arguments to the console.

  andika("Jambo Dunia") // => "Jambo Dunia"

• soma(swali: SWString): SWString
  Gets and returns user input as a string. Uses the value of swali as a prompt message

  wacha jina = soma()
  > "Wendo" // User Input
  andika(jina) // => "Wendo"

• somaNambari(swali: SWString): SWNumber
  Gets and returns user input as a number. Uses the value of swali as a prompt message

  wacha umri = somaNambari()
  > 22 // User Input
  andika(umri) // => 22

• futa(): SWNull
  Clears the console window

Type methods

Checking type

• aina(kitu: any): SWString
  Returns a string indicating the data type of kitu

  wacha x = [1,2,3]
  andika(aina(x)) // => "Orodha"

• niKamusi(kitu: any): SWBoolean
  Returns kweli if kitu is of type SWObject

  wacha mtu = {jina: "John", umri: 23}
  andika(niKamusi(mtu)) // => kweli

• niTarehe(kitu: any): SWBoolean
  Returns kweli if kitu is of type SWDateTime

  wacha leo = Tarehe()
  andika(niTarehe(leo)) // => kweli

• niTupu(kitu: any): SWBoolean
  Returns kweli if kitu is SWNull

  wacha bure = tupu
  andika(niTupu(bure)) // => kweli

• niNambari(kitu: any): SWBoolean
  Returns kweli if kitu is of type SWNumber

  wacha pi = 3.141592
  andika(niNambari(pi)) // => kweli

• niJina(kitu: any): SWBoolean
  Returns kweli if kitu is of type SWString

  wacha neno="Wamlambez"
  andika(niJina(neno)) // => kweli

• niOrodha(kitu: any): SWBoolean
  Returns kweli if kitu is of type SWList

  wacha list = [1,2,3,4]
  andika(niOrodha(list)) // => kweli

• niShughuli(kitu: any): SWBoolean
  Returns kweli if kitu is of type SWBaseFunction

  shughuli salimu(jina){
    andika("Habari" + jina)
  }
  andika(niShughuli(salimu)) // =>kweli

Type casting

• Nambari(kitu: SWString | SWBoolean | SWNumber): SWNumber
  Returns an SWNumber representation of the value passed in

• Jina(kitu: any): SWString
  Returns an SWString representation of the value passed in

• Tarehe(siku: SWDateTime | SWString): SWDateTime
  Returns the current date, or a date with the value matching the parameter siku. For info on SWDateTime formatting, read the guide

• RegEx(muundo: SWString, bendera: SWString): SWRegEx
  Returns SWRegEx representation of the value passed in

Modification and reading (see also Grammar and Types)

Iterables

• iterable.idadi(): SWNumber
  Returns the length of a list or string

  wacha list = [1,2,3,4]
  andika(list.idadi()) // => 4

  wacha str = "Something"
  andika(str.idadi()) // => 9

• iterable.ina(kitafuto: any): SWBoolean
  Returns a boolean indicating whether a string/list contains the element kitu or not.

  wacha list = [1,2,3,4]
  andika(list.ina(3)) // => kweli

  wacha str = "Something"
  andika(str.ina("x")) // => uwongo

• iterable.pahala(kitafuto: any): SWNumber
  Returns an SWNumber indicating the position of kitafuto in the iterable, or a -1 if it does not exist.

  wacha list = [1,2,3,4]
  andika(list.pahala(3)) // => 2

  wacha str = "Something"
  andika(str.pahala("x")) // => -1

• iterable.sehemu(mwanzo: SWNumber[, mwisho: SWNumber]): iterable
  Returns a section of the string/list delimited by mwanzo and mwisho

  wacha list = [1,2,3,4]
  andika(list.sehemu(1,2)) // => [2,3]

  wacha str = "Something"
  andika(str.sehemu(-3)) // => "ing"

Strings

• str.badili(kitafuto: SWString | SWRegEx , mbadala: SWString): SWString
  Returns a new SWString made by replacing the string that matches kitafuto with the value provided for mbadala.

  wacha str = "Something"
  andika(str.badili("thing", "body")) // => "Somebody"

• str.tenga(kitengo: SWString | SWRegEx): SWList
  Returns an SWList made by splitting str, delimited by the value of kitengo

  wacha str = "Everybody-was-kungfu-fighting"
  andika(str.tenga("-")) // => ["Everybody", "was", "kungfu", "fighting"]

• str.herufiKubwa(): SWString
  Returns the uppercase equivalent of an SWString

  wacha str = "abcde"
  andika(str.herufiKubwa()) // => "ABCDE"

• str.herufiNdogo(): SWString
  Returns the lowercase equivalent of an SWString

  wacha str = "FGHIJ"
  andika(str.herufiNdogo()) // => "fghij"

Lists

• list.weka(pahala: SWNumber, kitu: any): SWList
  Modifies an SWList in place by replacing the value at pahala with the value provided for kitu. Returns the value of the list

  wacha list = [1,2,3,4]
  list.weka(0, 5)
  andika(list) // => [5,2,3,4]

• list.fanya(shug: SWFunction): SWList
  Maps each element in a list to a new value using the function provided for shug. The function shug receives two arguments: el (the current element) and idx (the current index). Returns the value of the new list

  wacha list = [1,2,3,4]
  shughuli multByIndex(el, idx) {
    rudisha el * idx
  }

  andika(list.fanya(multByIndex)) // => [0,2,6,12]

• list.unga(kiungo: SWString): SWString
  Returns a new SWString from the list, joined with the delimiter provided for kiungo.

  wacha list = [1,2,3,4]
  andika(list.unga("-")) // => "1-2-3-4"

• list.kubwa(): SWNumber
  Returns the largest element in a list of numbers(SWNumber).

  wacha list = [1,2,3,4]
  andika(list.kubwa()) // => 4

• list.ndogo(): SWNumber
  Returns the smallest element in a list of numbers(SWNumber).

  wacha list = [1,2,3,4]
  andika(list.ndogo()) // => 1

• list.panga(): SWList
  Sorts a list in place and returns the sorted list.

  wacha list = [5,4,3]
  andika(list.panga()) // => [3,4,5]

Dates

• date.unda(muundo: SWString): SWString
  Formats a SWDateTime value as a SWString

  wacha date = Tarehe("01/01/2001")
  andika(date.unda("s, M t, MK")) // => "Jumatatu, Januari 01, 2001"

Objects

• obj.viingilio(): SWList
  Returns a list containing the key-value pairs of an object as tuples. This allows you to iterate through the properties of an object

  wacha obj = { jina: "John", umri: 23 }
  andika(obj.viingilio()) // => [["jina", "John"], ["umri", 23]]

• obj.ondoa(jina: SWString): SWNull
  Removes the key jina from the object.

  wacha obj = { jina: "John", umri: 23 }
  obj.ondoa("umri")
  andika(obj() // => { jina: "John" }

Modules

• expoti(kitu: any): any
  Used when creating Swahili modules by exporting bindings to functions, dictionaries or primitive values from the module so they can be used by other programs with the impoti() method. Only the last call to expoti() in a module will be made available. Because of this, it is recommended to use an object if you need multiple values in the export.

  wacha hesabu = {}

  hesabu.ongeza = shughuli (nambari) {
    wacha jumla = 0
    kwa n katika nambari {
      jumla = jumla + n
    }

    rudisha jumla
  }

  expoti(hesabu)

• impoti(faili: SWString): any
  Used to import read-only bindings which are exported by another module. The file path given for faili must be a local file and can be either absolute or relative.

  wacha hesabu = impoti("./hesabu.swh")

  wacha idadi = somaNambari("Nambari ngapi? ")
  wacha nambari = []

  kwa i = 0 mpaka idadi {
    nambari = nambari + somaNambari("Nambari: ")
  }

  andika(hesabu.ongeza(nambari))

Async (Timeouts)

• subiri(shug: SWFunction[, muda: SWNumber[, arg1, arg2, ...]]): SWTimeout
  Sets a timer which executes a function once the timer expires. muda represents the delay in ms. Additional arguments (arg1, arg2, ...) get passed through to the function specified by shug.

  If muda is omitted, a value of 0 is used, meaning execute "immediately", or more accurately, the next event cycle. Note that in either case, the actual delay may be longer than intended.

  A timeout can be cancelled using the komesha() method.

  shughuli ngojaWatu(a, b) {
    // hoja "a" na "b" hazihitajiki
    andika(a, "na", b, "wamefika.")
  }

  wacha s = subiri(ngojaWatu, 1000, "John", "Stella")

• rudia(shug: SWFunction, muda: SWNumber[, arg1, arg2, ...]): SWTimeout
  Repeatedly calls a function with a fixed time delay between each call. It returns an SWTimeout that uniquely identifies it, so you can remove it later by calling komesha(). muda must be at least 1ms to allow code to actually run.

  Ensure that execution duration is shorter than interval frequency

  If there is a possibility that your logic could take longer to execute than the interval time, it is recommended that you recursively call a named function using subiri().

  shughuli semaSaa() {
    wacha t = Tarehe()
    andika(t.unda("sa:d w"))
  }

  wacha r = rudia(semaSaa, 1000)

• komesha(muda: SWTimeout): SWNull
  Cancels a timeout created by subiri() or rudia()

  shughuli semaSaa() {
    wacha t = Tarehe()
    andika(t.unda("sa:d w"))
  }

  wacha r = rudia(semaSaa, 1000)

  wacha s = subiri(shughuli () {
    komesha(r) // stops printing the time after 5 seconds
  }, 5000)