Module Specifications.Stdlib320

The following is the standard library that we will use for CAS CS 320: Concepts of Programming Languages at Boston University in the Fall 2024 semester (Note. This is the first time we're doing this, so it's something of an experiment).

The primary motivation for this library is to give a small subset of the OCaml Standard Library with a bit more documentation and more control on the end of the instructor to decide what functions are "allowed" for assignments. It is also minimally side-effectful.

Since nearly all functions are available in the OCaml Standard Library, you can take a look at Stdlib documentation for more information on what you see below.

Integer arithmetic

The parentheses in functions below indicate that the following functions are infix operators. This means we can, for example, write 11 + 13 instead of (+) 11 13 (though both are allowed). The associativity and precedence of all operators follow those of the OCaml Standard library. See this table for details.

val (+) : int -> int -> int

Integer addition

val (-) : int -> int -> int

Integer subtraction

val (*) : int -> int -> int

Integer multiplication

val (/) : int -> int -> int

Integer division, which rounds towards 0.

let _ =
  let _ = assert (5 / 3 = 1) in
  let _ = assert ((- 5) / 3 = -1) in
  let _ = assert (5 / (- 3) = 1) in
  ()

Raises a Division_by_zero exception if the second argument is 0 (Note. We won't be dealing with exceptions all that much in this course).

val abs : int -> int

Integer absolute value

val (mod) : int -> int -> int

Integer remainder. It satisfies the properties:

  • x mod y = x mod (abs y)
  • (- x) mod y = - (x mod y)

And for positive integers it is the remainder of x / y in the grade-school sense.

val max_int : int

The greatest representable integer

val min_int : int

The smallest representable integer

Floating-point arithmetic

From the OCaml Standard Library: "OCaml's floating-point numbers follow the IEEE 754 standard, using double precision (64 bits) numbers. Floating-point operations never raise an exception on overflow, underflow, division by zero, etc. Instead, special IEEE numbers are returned as appropriate..." See this paragraph for more details.

val (+.) : float -> float -> float

Floating-point addition (Note the .!)

val (-.) : float -> float -> float

Floating-point subtraction

val (*.) : float -> float -> float

Floating-point multiplication

val (/.) : float -> float -> float

Floating-point division

val (**) : float -> float -> float

Exponentiation

val sqrt : float -> float

Square root

val exp : float -> float

Exponential

val log : float -> float

Natural logarithm

val log10 : float -> float

Base 10 logarithm

val ceil : float -> float

Ceiling, i.e., round up to an integer (returned as a float)

val floor : float -> float

Floor, i.e., round down to an integer

val abs_float : float -> float

Floating point absolute value

Boolean operations

val not : bool -> bool

Boolean negation

val (&&) : bool -> bool -> bool

Boolean conjunction (and)

val (||) : bool -> bool -> bool

Boolean disjunction (or)

Comparing

val (=) : 'a -> 'a -> bool

Structural equality. This is == in most other languages. You should generally avoid using this for floating-point numbers.

val (<>) : 'a -> 'a -> bool

Structural inequality, i.e., x <> y is equivalent to not (x = y)

val (<) : 'a -> 'a -> bool

Structural less-than. It behaves as expected on Boolean values (false < true), characters (by integer value), string (lexicographically), etc.

val (>) : 'a -> 'a -> bool

Structural greater-than

val (<=) : 'a -> 'a -> bool

Structural less-than-or-equal-to, i.e., x <= y is equivalent to not (x > y)

val (>=) : 'a -> 'a -> bool

Structural greater-than-or-equal-to

val compare : 'a -> 'a -> int

Comparison, i.e., if x = y then compare x y = 0, if x > y then compare x y > 0, and if x < y then compare x y < 0

val min : 'a -> 'a -> 'a

Minimum of its two arguments

val max : 'a -> 'a -> 'a

Maximum of its two arguments

Converting

val float_of_int : int -> float

Converts an integer into a floating-point number.

val int_of_float : float -> int

Converts a floating-point number into an integer, rounding towards 0 (i.e., truncating).

val int_of_char : char -> int

Converts a character into its ASCII code.

val char_of_int : int -> char

Converts an ASCII code into a character.

Raises an Invalid_argument exception if its argument is not a valid ASCII code.

val string_of_bool : bool -> string

Converts a Boolean value to a string.

val bool_of_string : string -> bool

Converts a string to a Boolean value. Raises a Failure exception in the case the argument is not "true" or "false".

val bool_of_string_opt : string -> bool option

Same as the previous function, but returns None in the case of failure.

val string_of_int : int -> string

Converts an integer to a string

val int_of_string : string -> int

Converts a string to an integer. Raises a Failureexception in the case the argument does not represent a integer.

val int_of_string_opt : string -> int option

Same as the previous function, but returns None in the case of failure.

Composing

val (|>) : 'a -> ('a -> 'b) -> 'b

x |> f |> g is equivalent to g (f x). This operator is useful for pipelining.

val (@@) : ('a -> 'b) -> 'a -> 'b

f @@ g @@ x is equivalent to f (g x). This operator has low precedence, which is useful if you want to avoid parentheses, e.g., we can write abs @@ 2 + 3 instead of abs (2 + 3).

IO

Printing

val print_int : int -> unit

Prints an integer to standard output.

val print_float : float -> unit

Prints a floating-point number to standard output.

val print_char : char -> unit

Prints a character to standard output.

val print_string : string -> unit

prints a string to standard output.

val print_endline : string -> unit

Prints a string followed by a newline character to standard output.

val print_newline : unit -> unit

Prints a newline character.

val print_byte : int -> unit

Prints a byte, where the argument is taken modulo 256.

Reading

val read_file : string -> string

Reads the contents of a file given the filename. We will primarily be using this function.

val read_line : unit -> string

Reads a line (upto a newline character) from standard input, where the output does not include a the newline character.

val read_byte : unit -> int

Reads a byte from standard input.

Course-Specific Utilities

val gensym : unit -> string

Generates a string that can be used as a fresh variable in the interpreters we implement in this course.

type 'a env

Type for a map (i.e. dictionary) structure with strings for keys

module Env : sig ... end

Basic OCaml Types

Pairs

val fst : ('a * 'b) -> 'a
val snd : ('a * 'b) -> 'b

Strings

val (^) : string -> string -> string

String concatenation, e.g., "hello" ^ "world" ^ "!" = "hello world!"

module Char : sig ... end
module String : sig ... end

Lists

val (@) : 'a list -> 'a list -> 'a list

List concatenation, e.g., [1;2;3] @ [4;5;6] @ [7;8;9] = [1;2;3;4;5;6;7;8;9]

module List : sig ... end

Options

module Option : sig ... end

Results

type ('a, 'b) result =
  1. | Ok of 'a
  2. | Error of 'b
module Result : sig ... end

Extra Utilities

There are some functions we've included for completeness, others because we silently need them for other things to work, and others just in case (Note. Again, this is a new system we're trying out, there may be some things we add or remove throughout the semester).

val ignore : 'a -> unit

Evaluates its argument and discards it, returning (). We will use this when we start building interpreters to trace information during evaluation in order to maintain that we're writing valid OCaml programs.

Exception Handling

Again, we won't do too much exception handling in this course.

val raise : exn -> 'a

Raise an exception

val failwith : string -> 'a

Raise a Failure exception with a given message

IO

type in_channel
type out_channel
val open_out : string -> out_channel
val flush : out_channel -> unit
val output_string : out_channel -> string -> unit
val output_byte : out_channel -> int -> unit
val close_out : out_channel -> unit
val open_in : string -> in_channel
val input_line : in_channel -> string
val input_byte : in_channel -> int
val close_in : in_channel -> unit
module Filename : sig ... end

Trigonometric Functions

module Float : sig ... end

A module containing a floating-point approximation of pi. It is in its own module because we want to be consistent with the OCaml Standard Library.

val cos : float -> float
val sin : float -> float
val tan : float -> float
val acos : float -> float
val asin : float -> float
val atan : float -> float
val atan2 : float -> float -> float
val hypot : float -> float -> float
val cosh : float -> float
val sinh : float -> float
val tanh : float -> float
val acosh : float -> float
val asinh : float -> float
val atanh : float -> float

Randomness

module Random : sig ... end

Other Modules

module Format : module type of Stdlib.Format
module Printf : module type of Stdlib.Printf
module Sys : module type of Stdlib.Sys
module Lexing : module type of Stdlib.Lexing
module Parsing : module type of Stdlib.Parsing