O1Library Docs
Fall 2023
Docs API

# o1.util

package o1.util

## Members list

### Type members

#### Classlikes

object nice

The objects nested herein extend various standard API classes with nice convenience methods.

The objects nested herein extend various standard API classes with nice convenience methods.

## Attributes

Supertypes
  class Object
  trait Matchable
  class Any
Self type
  nice.type

#### Types

type Closeable = AutoCloseable

A structural supertype for everything that has a `close` method. This is an alias for `java.lang.AutoCloseable`.

A structural supertype for everything that has a `close` method. This is an alias for `java.lang.AutoCloseable`.

## Attributes

See also

  useAndClose

type Failure[T] = Failure[T]

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

## Attributes

type Path = Path

An alias for convenient use of `java.nio.file.Path` via `import o1.util.*`.

An alias for convenient use of `java.nio.file.Path` via `import o1.util.*`.

## Attributes

type Random = Random

An alias for convenient use of `scala.util.Random` via `import o1.util.*`.

An alias for convenient use of `scala.util.Random` via `import o1.util.*`.

## Attributes

type Source = Source

An alias for convenient use of `scala.io.Source` via `import o1.util.*`.

An alias for convenient use of `scala.io.Source` via `import o1.util.*`.

## Attributes

type Success[T] = Success[T]

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

## Attributes

type Try[T] = Try[T]

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

## Attributes

type URL = URL

An alias for convenient use of `java.net.URL` via `import o1.util.*`.

An alias for convenient use of `java.net.URL` via `import o1.util.*`.

## Attributes

### Value members

#### Concrete methods

def Path(name: String): Path

Constructs a new `Path` object from a given string.

Constructs a new `Path` object from a given string.

## Attributes

def Path(url: URL): Path

Constructs a new `Path` object from a given string URL.

Constructs a new `Path` object from a given string URL.

## Attributes

inline def ast(inline expr: Any): String

A macro that returns a string describing the structure (abstract syntax tree) of the given Scala expression.

A macro that returns a string describing the structure (abstract syntax tree) of the given Scala expression.

## Attributes

def findReadable(name: String): Option[Path]

Searches the working directory and, failing that, the classpath for a readable file or folder with the given relative path. Returns the `Path` in an `Option` wrapper.

Searches the working directory and, failing that, the classpath for a readable file or folder with the given relative path. Returns the `Path` in an `Option` wrapper.

## Attributes

def forEachLine(source: Source)(effect: String => Unit): Unit

Calls `getLines` on the given `Source` and performs the specified `effect` on each of the lines. Calls `close()` on the source even if an exception occurs, but doesn’t catch any exceptions.

Calls `getLines` on the given `Source` and performs the specified `effect` on each of the lines. Calls `close()` on the source even if an exception occurs, but doesn’t catch any exceptions.

## Attributes

def ifImplemented[Result](computation: => Result): Option[Result]

Performs a given computation and checks to see if it crashes with a `NotImplementedError`. Returns the result of the computation in an `Option`; returns `None` only in the computation wasn’t implemented. Any other exception is thrown.

Performs a given computation and checks to see if it crashes with a `NotImplementedError`. Returns the result of the computation in an `Option`; returns `None` only in the computation wasn’t implemented. Any other exception is thrown.

## Type parameters

Result

  the type of the given computation

## Parameters

computation

  a computation that may or may not be implemented

## Attributes

def isImplemented[Result](computation: => Result): Boolean

Performs a given computation and determines whether it crashes with a `NotImplementedError`. Returns `true` if it did and `false` otherwise.

Performs a given computation and determines whether it crashes with a `NotImplementedError`. Returns `true` if it did and `false` otherwise.

## Type parameters

Result

  the type of the given computation

## Parameters

computation

  a computation that may or may not be implemented

## Attributes

def localFile(resourcePath: String): Option[Path]

Searches the classpath for a file with the given relative path and returns the corresponding `Path`. The result comes in an `Option` wrapper in case no such file is accessible.

Searches the classpath for a file with the given relative path and returns the corresponding `Path`. The result comes in an `Option` wrapper in case no such file is accessible.

## Attributes

def localSource(resourcePath: String): Option[Source]

Searches the classpath for a file with the given relative path and returns a corresponding `Source`. The result comes in an `Option` wrapper in case no such file is accessible. Assumes UTF-8 encoding.

Searches the classpath for a file with the given relative path and returns a corresponding `Source`. The result comes in an `Option` wrapper in case no such file is accessible. Assumes UTF-8 encoding.

## Attributes

def localURL(resourcePath: String): Option[URL]

Searches the classpath for a file with the given relative path. Delegates the task to the class loader. Returns the URL of any found file in an `Option` wrapper.

Searches the classpath for a file with the given relative path. Delegates the task to the class loader. Returns the URL of any found file in an `Option` wrapper.

## Attributes

def readFileLines(relativePath: String, trimEach: Boolean, excludeIfEmpty: Boolean): Option[Vector[String]]

Reads and returns the lines from a classpath-relative text file. The result comes in an `Option` wrapper in case no such file is accessible. Calls `close()` on the file even if an exception occurs, but doesn’t catch any exceptions. Assumes UTF-8 encoding.

Reads and returns the lines from a classpath-relative text file. The result comes in an `Option` wrapper in case no such file is accessible. Calls `close()` on the file even if an exception occurs, but doesn’t catch any exceptions. Assumes UTF-8 encoding.

## Parameters

excludeIfEmpty

  whether to exclude (possibly trimmed) empty lines from the return value; if unspecified, defaults to `true`

relativePath

  the path to a resource; relative to a classpath entry

trimEach

  whether to remove whitespace around each of the lines; if unspecified, defaults to `true`

## Attributes

def readLinesFromSource(source: Source, trimEach: Boolean, excludeIfEmpty: Boolean): Vector[String]

Calls `getLines` on the given `Source` and returns the lines in a vector. Calls `close()` on the source even if an exception occurs, but doesn’t catch any exceptions.

Calls `getLines` on the given `Source` and returns the lines in a vector. Calls `close()` on the source even if an exception occurs, but doesn’t catch any exceptions.

## Parameters

excludeIfEmpty

  whether to exclude (possibly trimmed) empty lines from the return value; if unspecified, defaults to `true`

source

  the source to read the lines from

trimEach

  whether to remove whitespace around each of the lines; if unspecified, defaults to `true`

## Attributes

def readTextFile(relativePath: String): Option[String]

Returns, as a single `String`, the entire contents of a classpath-relative text file. The result comes in an `Option` wrapper in case no such file is accessible. Calls `close()` on the file even if an exception occurs, but doesn’t catch any exceptions. Assumes UTF-8 encoding.

Returns, as a single `String`, the entire contents of a classpath-relative text file. The result comes in an `Option` wrapper in case no such file is accessible. Calls `close()` on the file even if an exception occurs, but doesn’t catch any exceptions. Assumes UTF-8 encoding.

## Parameters

relativePath

  the path to a resource; relative to a classpath entry

## Attributes

inline def report(inline exprs: Any*): Unit

A macro that prints out the given expressions. Literals are printed as they are, other expressions as `"expr=value"`. Potentially useful for debugging.

A macro that prints out the given expressions. Literals are printed as they are, other expressions as `"expr=value"`. Potentially useful for debugging.

## Attributes

def tryForSource(pathOrURL: String): Try[Source]

Takes in a path or a URL as a string and tries to construct a corresponding `Source`. Tries to interpret the given string as one of the following, in order:

Takes in a path or a URL as a string and tries to construct a corresponding `Source`. Tries to interpret the given string as one of the following, in order:

1. A resource relative to the classpath (as per localURL).
2. A complete URL string, with protocol and all (e.g., "http://example.com/").
3. A URL string with `"http://"` missing (e.g., "example.com").
4. A URL string with `"https://"` missing. Calls `scala.io.Source.fromURL` on each of those candidates until a source is successfully constructed or all attempts have failed. Assumes UTF-8 encoding.

## Parameters

pathOrURL

  the possible path or URL to a resource

## Attributes

Returns

  the first `Success`, or a `Failure` if none of the candidates can be read as a `Source`

def tryForURL(pathOrURL: String): Try[URL]

Takes in a path or a URL as a string and tries to locate the corresponding resource. Tries to interpret the given string as one of the following (in order until a match is found):

Takes in a path or a URL as a string and tries to locate the corresponding resource. Tries to interpret the given string as one of the following (in order until a match is found):

1. A resource relative to the classpath (as per localURL).
2. A complete URL string, with protocol and all (e.g., "http://example.com/").
3. A URL string with `"http://"` missing (e.g., "example.com").

## Parameters

pathOrURL

  the possible path or URL to a resource

## Attributes

Returns

  the first `Success`, or a `Failure` if the string isn’t even valid for forming a URL

def workingDir: String

An alias for convenient access to `java.lang.System.getProperty("user.dir")` via `import o1.util.*`.

An alias for convenient access to `java.lang.System.getProperty("user.dir")` via `import o1.util.*`.

## Attributes

def writeTextFile(filePath: String, text: String): Unit

Writes the given `text` in a new text file at the given `filePath`. Overwrites any existing file there. Encodes the output as UTF-8. Calls `close()` on the output stream even if an exception occurs, but doesn’t catch any exceptions.

Writes the given `text` in a new text file at the given `filePath`. Overwrites any existing file there. Encodes the output as UTF-8. Calls `close()` on the output stream even if an exception occurs, but doesn’t catch any exceptions.

## Parameters

filePath

  an absolute path to a local file or a path relative to the working directory

## Attributes

#### Concrete fields

val DoNothing: Unit

A label that can be used as an empty method body or other “no-op” block.

A label that can be used as an empty method body or other “no-op” block.

## Attributes

val DoubleOrdering: TotalOrdering.type

An alias for convenient use of `scala.math.Ordering.Double.TotalOrdering` via `import o1.util.*`.

An alias for convenient use of `scala.math.Ordering.Double.TotalOrdering` via `import o1.util.*`.

## Attributes

val Failure: Failure.type

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

## Attributes

val Random: Random.type

An alias for convenient use of `scala.util.Random` via `import o1.util.*`.

An alias for convenient use of `scala.util.Random` via `import o1.util.*`.

## Attributes

val Source: Source.type

An alias for convenient use of `scala.io.Source` via `import o1.util.*`.

An alias for convenient use of `scala.io.Source` via `import o1.util.*`.

## Attributes

val Success: Success.type

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

## Attributes

val Try: Try.type

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

An alias for convenient use of `scala.util.Try` via `import o1.util.*`.

## Attributes

### Givens

given given_CanEqual_Source_Source: CanEqual[Source, Source]