## 11.9. util: Miscellaneous utility functions.

Miscellaneous utility functions.

### 11.9.1. `Random`

`site Random() :: Integer`

Return a random integer chosen from the range of all possible 32-bit integers.

### 11.9.2. `Random`

`site Random(Integer) :: Integer`

Return a pseudorandom, uniformly distributed integer between 0 (inclusive) and the specified value (exclusive). If the argument is 0, halt silently.

### 11.9.3. `URandom`

`site URandom() :: Number`

Return a pseudorandom, uniformly distributed number between 0.0 (inclusive) and 1.0 (exclusive).

### 11.9.4. `UUID`

`site UUID() :: String`

Return a random (type 4) UUID represented as a string.

### 11.9.5. `Prompt`

`site Prompt(String) :: String`

 Indefinite

Prompt the user for some input. The user may cancel the prompt, in which case the site fails silently. Otherwise their response is returned as soon as it is received.

Example:

```-- Publishes the user's name

The user response is always taken to be a string. Thus, integer 3 as a response will be treated as "3". To convert the response to its appropriate data type, use the library function `Read`:

```-- Prompts the user to enter an integer, then parses the response.

### 11.9.6. `signals`

`def signals(Integer) :: Signal`

Publish the given number of signals, simultaneously.

Example:

```-- Publishes five signals
signals(5)```

Implementation.

```
def signals(Integer) :: Signal
def signals(n) = if n :> 0 then (signal | signals(n-1)) else stop

```

### 11.9.7. `for`

`def for(Integer, Integer) :: Integer`

Publish all values in the given half-open range, simultaneously.

Example:

```-- Publishes: 1 2 3 4 5
for(1,6)```

Implementation.

```
def for(Integer, Integer) :: Integer
def for(low, high) =
if low >= high then stop
else ( low | for(low+1, high) )

```

### 11.9.8. `upto`

`def upto(Integer) :: Integer`

`upto(n)` publishes all values in the range `(0..n-1)` simultaneously.

Example:

```-- Publishes: 0 1 2 3 4
upto(5)```

Implementation.

```
def upto(Integer) :: Integer
def upto(high) = for(0, high)

import class Iterable = "java.lang.Iterable"

```

### 11.9.9. `IterableToStream`

`site IterableToStream[A](Iterable[A]) :: lambda () :: A`

Converts a Java object implementing the Iterable interface into an Orc stream backed by the object's iterator. When the site is called, if the iterator has items remaining, the next item is returned. If the iterator has no items remaining, the call halts.

### 11.9.10. `iterableToList`

`def iterableToList[A](Iterable[A]) :: List[A]`

Given a Java object implementing the Iterable interface, create an Orc list whose elements are the values produced by the object's iterator, in the same order.

Implementation.

```
def iterableToList[A](Iterable[A]) :: List[A]
def iterableToList(iterable) =
val s = IterableToStream[A](iterable)
def walk(List[A]) :: List[A]
def walk(l) = s():l >m> walk(m) ; reverse(l)
walk([])

```

### 11.9.11. `arrayToList`

`def arrayToList[A](Array[A]) :: List[A]`

Given an array, create an Orc list whose elements are exactly the contents of the array, in the same order.

Implementation.

```
def arrayToList[A](Array[A]) :: List[A]
def arrayToList(a) =
def walk(Integer, List[A]) :: List[A]
def walk(0,acc) = acc
def walk(i,acc) = walk(i-1, a(i-1)? : acc)
walk(a.length?, [])

import class JavaList = "java.util.List"

```

### 11.9.12. `listToJavaList`

`def listToJavaList[A](List[A]) :: JavaList[A]`

Given an Orc list, create a java.util.List with the same elements.

Implementation.

```
def listToJavaList[A](List[A]) :: JavaList[A]
def listToJavaList(list) =
def copy(List[A]) :: Bot
def copy(x:xs) = javalist.add(x) >> copy(xs)
copy(list) ; javalist

```

### 11.9.13. `listToArray`

`def listToArray[A](List[A]) :: Array[A]`

Given an Orc list, create an array whose elements are exactly the contents of the list, in the same order. The size of the array is exactly the list length.

Implementation.

```
def listToArray[A](List[A]) :: Array[A]
def listToArray(list) =
val array = Array[A](length(list))
def copy(List[A], Integer) :: Bot
def copy(x:xs, i) = (array(i) := x) >> copy(xs, i+1)
copy(list, 0) ; array

```

### 11.9.14. `fillArray`

`def fillArray[A](Array[A], lambda (Integer) :: A) :: Array[A]`

Given an array and a function from indices to values, populate the array by calling the function for each index in the array. Publish the array once it has been populated.

For example, to set all elements of an array to zero:

```-- Publishes: 0 0 0
val a = fillArray(Array(3), lambda (_) = 0)
a(0)? | a(1)? | a(2)?```

Implementation.

```
def fillArray[A](Array[A], lambda (Integer) :: A) :: Array[A]
def fillArray(a, f) =
val n = a.length?
def fill(Integer, lambda(Integer) :: A) :: Bot
def fill(i, f) =
if i = n then stop
else ( a(i) := f(i) >> stop
| fill(i+1, f) )
fill(0, f) ; a

```

### 11.9.15. `sliceArray`

`def sliceArray[A](Array[A], Integer, Integer) :: Array[A]`

Given an array and a half-open index range, create a new array which contains the elements of the original array in that index range.

Implementation.

```
def sliceArray[A](Array[A], Integer, Integer) :: Array[A]
def sliceArray(orig, from, until) =
val size = until - from
val a = Array[A](size)
def copy(i :: Integer) :: Bot =
Ift(i <: size) >>
a(i) := orig(from + i)? >>
copy(i+1)
copy(0) ; a

```

### 11.9.16. `takePubs`

`def takePubs[A](Integer, lambda () :: A) :: A`

`takePubs(n, f)` calls `f()`, publishes the first `n` values published by `f()` (as they are published), and then halts.

Implementation.

```

def takePubs[A](Integer, lambda () :: A) :: A
def takePubs(n, f) =
val out = Channel[A]()
val c = Counter(n)
Let(
f() >x>
Ift(c.dec() >> out.put(x) >> false
; out.closeD() >> true)
) >> stop | repeat(out.get)

```

### 11.9.17. `withLock`

`def withLock[A](Semaphore, lambda () :: A) :: A`

Acquire the semaphore and run a thunk which is expected to publish no more than one value. Publishes the value published by the thunk and releases the semaphore.

Implementation.

```

def withLock[A](Semaphore, lambda () :: A) :: A
def withLock(s, f) =
s.acquire() >> (
Let(f()) >x>
s.release() >>
x
; s.release() >> stop
)

```

### 11.9.18. `synchronized`

`def synchronized[A](Semaphore, lambda () :: A)() :: A`

Given a lock and thunk, return a new thunk which is serialized on the lock. Similar to Java's synchronized keyword.

Implementation.

```

def synchronized[A](Semaphore, lambda () :: A) :: lambda() :: A
def synchronized(s,f) = lambda() = withLock(s, f)

```

### 11.9.19. `InvokeExecutable`

`site InvokeExecutable(command :: List[String])`

Run an executable file in the host OS, with input/output addressable from Orc.

The executable file is invoked in a new OS process, and is passed the command arguments given to `InvokeExecutable`. The process is created with an input character stream, to which the Orc program can send strings. The process is also created with two output character strings, one for conventional output and one for error/diagnostic output, from which the Orc program can read. Upon process termination, the Orc program can read the exit status value.

Output streams from the process can be read while the process is running. The "chunk" of the stream that is returned from any one read operation is of an unspecified length, because of buffer sizes and operation granularity between the sender and receiver. Callers may need to reassemble output segments prior to further processing. If this is inconvenient, there are "read all" methods that wait for process termination, and then return the output as a single character string.

Assumptions: <ul> <li>The supplied "command" string refers to an executable file that is understandable by the OS hosting the Orc runtime engine.</li> <li>Input and output to the executable program are character strings encoded in the host OS's default character encoding.</li> </ul>

` invokeexecutable.writeIn(String) :: Signal`

 Definite

Send the given string to the process's standard input stream. If the process has completed, halt silently.

` invokeexecutable.closeIn(String) :: Signal`

 Definite Idempotent

Close the process's standard input stream.

` invokeexecutable.readOut() :: String`

Receive a "chunk" of available characters from the process's standard output stream. The chunk size is not specified. If there is no output available from the process, wait for some. If there is no output available and the process has closed its output stream, halt silently.

 Indefinite

` invokeexecutable.readOutD() :: String`

Receive a "chunk" of available characters from the process's standard output stream. The chunk size is not specified. If there is no output available from the process, halt silently.

 Definite

` invokeexecutable.readOutAll() :: String`

 Indefinite

If the process is running, wait for it to complete; then, receive all remaining standard output stream contents from the process as a single string. If there is no further output, halt silently.

` invokeexecutable.readErr() :: String`

 Indefinite

Receive a "chunk" of available characters from the process's standard error (diagnostic) stream. The chunk size is not specified. If there is no output available from the process, wait for some. If there is no output available and the process has closed its output stream, halt silently.

` invokeexecutable.readErrD() :: String`

 Definite

Receive a "chunk" of available characters from the process's standard error (diagnostic) stream. The chunk size is not specified. If there is no output available from the process, halt silently.

` invokeexecutable.readErrAll() :: String`

 Indefinite

If the process is running, wait for it to complete; then, in any case, receive all remaining standard error (diagnostic) output from the process as a single string. If there is no further output, halt silently.

` invokeexecutable.exitValue() :: Integer`

 Definite

Returns the exit status byte from the process running the executable. If the process has not completed, halt silently. Conventionally, a zero exit status value indicates a successful termination.

` invokeexecutable.terminate() :: Signal`

 Indefinite

Send a termination signal (for example, SIGTERM) to the process running the executable. If the process has completed, then this method has no effect.

### 11.9.20. `OrcVersion`

`site OrcVersion() :: String`

Return a name, version, URL, and copyright string for Orc.