2.5 Singleton Types

8.16.0.1

2.5 Singleton Types🔗ℹ

A singleton type is a simple kind of data type made up of only one value. Singleton types are useful for representing named constants, such as the end-of-file marker value eof. Symbols can also be used for this purpose, but a singleton type is often preferable because misspelling the name of the constant causes a compile error rather than a silent bug at runtime.

Examples:

(define-singleton-type undefined)

(define/contract (divide x y)
  (-> real? real? (or/c real? undefined?))
  (if (zero? y)
      undefined
      (/ x y)))

> (divide 6 3)
2
> (divide 6 0)
#<undefined>

syntax
(define-singleton-type id singleton-option ...)

singleton-option = #:omit-root-binding
| #:descriptor-name descriptor-id
| #:predicate-name predicate-id
| #:instance-name instance-id
| #:property-maker prop-maker-expr
| #:inspector inspector-expr

   prop-maker-expr :
(-> uninitialized-singleton-descriptor?
    (listof (cons/c struct-type-property? any/c)))
   inspector-expr : inspector?

Creates a singleton type and binds the following identifiers:

instance-id, which defaults to instance:id — the unique instance of the created type.
predicate-id, which defaults to id? — a predicate that returns #t when given the singleton instance and false for all other values.
descriptor-id, which defaults to descriptor:id — the type descriptor for the created type.

Additionally, unless #:omit-root-binding is specified, the original id is bound to a singleton type binding for the created type. The binding behaves like instance-id when used as an expression.

The prop-maker-expr is used to add structure type properties to the created type, and inspector-expr is used to determine the inspector that will control the created type. See make-singleton-implementation for more information about these parameters.

Examples:

(define-singleton-type infinity)

> infinity
#<infinity>
> (infinity? infinity)
#t

provide transformer
(singleton-out singleton)

Provides singleton, which must be a singleton-id, along with its predicate.

2.5.1 Singleton Type Information🔗ℹ

procedure
(singleton-type? v) → boolean?
v : any/c

A predicate for singleton types.

procedure
(singleton-type name
[ #:predicate-name predicate-name])
→ singleton-type?
name : interned-symbol?
predicate-name : (or/c interned-symbol? #f) = #f

Constructs a singleton type named name. The optional predicate-name argument controls the result of object-name on a predicate implementing the type. It defaults to name?. This function only constructs the information representing a singleton type; to implement the type, use make-singleton-implementation.

procedure
(singleton-type-name type) → interned-symbol?
type : singleton-type?

Returns the name of type.

procedure
(singleton-type-predicate-name type) → interned-symbol?
type : singleton-type?

Returns the name that should be used for predicates implementing type.

2.5.2 Singleton Type Descriptors🔗ℹ

Singleton types are implemented using fieldless structs, where only a single instance of the struct can be created. The type descriptor for a singleton type provides a predicate and, if the descriptor is initialized, can be used to retrieve the singleton instance.

procedure
(singleton-descriptor? v) → boolean?
v : any/c

A predicate for singleton type descriptors.

procedure
(initialized-singleton-descriptor? v) → boolean?
v : any/c

A predicate for initialized singleton type descriptors.

procedure
(uninitialized-singleton-descriptor? v) → boolean?
v : any/c

A predicate for uninitialized singleton type descriptors.

procedure
(make-singleton-implementation type
[ #:inspector inspector
#:property-maker prop-maker])
→ initialized-singleton-descriptor?
  type : singleton-type?
  inspector : inspector? = (current-inspector)
   prop-maker :
(-> uninitialized-singleton-descriptor?
    (listof (cons/c struct-type-property? any/c)))
= default-singleton-properties

Implements type and returns a type descriptor for the new implementation. The inspector argument behaves the same as in make-struct-type, although there are no transparent or prefab singleton types. The prop-maker argument is similar to the corresponding argument of make-struct-implementation. By default, singleton types are created with properties that make them print like other named Racket constants — see default-singleton-properties for details.

procedure
(singleton-descriptor-type descriptor) → singleton-type?
descriptor : singleton-descriptor?

Returns the singleton type that descriptor implements.

procedure
(singleton-descriptor-predicate descriptor) → predicate/c
descriptor : singleton-descriptor?

Returns a predicate that returns true when given the singleton instance created by descriptor. The predicate is specific to descriptor — it will not return true for singleton instances created by any other singleton descriptors, even if they’re different implementations of the same singleton type as descriptor. This is because singleton types are nominal types.

procedure
(singleton-descriptor-instance descriptor)
→ (singleton-descriptor-predicate descriptor)
descriptor : initialized-singleton-descriptor?

Returns the instance of the singleton type implemented by descriptor.

procedure
(default-singleton-properties descriptor)
→ (listof (cons/c struct-type-property? any/c))
descriptor : singleton-descriptor?

Returns implementations of prop:equal+hash, prop:custom-write, and prop:object-name suitable for most singleton types. The default implementation of prop:equal+hash always returns true, since it’s only called if two values are instances of the same type and singleton types only have one value.

This function is called by make-singleton-implementation when no prop-maker argument is supplied.

procedure
(default-singleton-custom-write descriptor)
→ custom-write-function/c
descriptor : singleton-descriptor?

Builds a custom write implementation that prints singleton instances created by descriptor in a manner similar to other named Racket constants such as eof. This function is used by default-singleton-properties to implement prop:custom-write.

procedure
(default-singleton-object-name descriptor)
→ (or/c natural? (-> any/c any/c))
descriptor : singleton-descriptor?

Builds a value suitable for use with prop:object-name that causes object-name to return the name of the instance when used on the singleton instance created by descriptor. This function is used by default-singleton-properties to implement prop:object-name.

2.5.3 Singleton Type Bindings🔗ℹ

(require rebellion/type/singleton/binding)
	package: rebellion

A singleton type binding is a type binding for a singleton type. Singleton type bindings contain compile-time information about the singleton type’s name, as well as runtime bindings for its predicate, type descriptor, and instance. To extract a singleton type binding bound by define-singleton-type, use the singleton-id syntax class.

procedure
(singleton-binding? v) → boolean?
v : any/c

A predicate for singleton type bindings.

syntax class
singleton-id

A syntax class for singleton type bindings bound by define-singleton-type. This class matches any identifier bound with define-syntax to a value satisfying the singleton-binding? predicate, similar to the static syntax class. Upon a successful match, the singleton-id class defines the following attributes:

type — an attribute bound to a compile-time singleton-type? value describing the type.
binding — an attribute bound to the compile-time singleton-binding? value extracted from the matched identifier.
name — a pattern variable bound to the singleton type’s name, as a quoted symbol.
descriptor — a pattern variable bound to the singleton type’s runtime type descriptor.
predicate — a pattern variable bound to the singleton type’s runtime type predicate.
instance — a pattern variable bound to the singleton type’s runtime singleton instance.

Examples:

(require (for-syntax rebellion/type/singleton/binding))

(define-simple-macro (singleton-predicate singleton:singleton-id)
singleton.predicate)

(define-singleton-type null)

> (singleton-predicate null)
#<procedure:null?>

procedure
(singleton-binding-type binding) → singleton-type?
binding : singleton-binding?

Returns the singleton type that binding is for. When a singleton type binding is bound with define-syntax, this can be used at compile-time to obtain information about the name of the singleton type.

procedure
(singleton-binding-descriptor binding) → identifier?
binding : singleton-binding?

Returns an identifier that is bound at runtime to the type descriptor for the singleton type bound by binding. When a singleton type binding is bound with define-syntax, this can be used in macro-generated code to work with singleton types dynamically.

procedure
(singleton-binding-predicate binding) → identifier?
binding : singleton-binding?

Returns an identifier that is bound at runtime to the predicate for the singleton type bound by binding.

procedure
(singleton-binding-instance binding) → identifier?
binding : singleton-binding?

Returns an identifier that is bound at runtime to the singleton instance for the singleton type bound by binding.

1	Base Libraries
2	Data Types
3	Streaming Computations
4	Collections
5	Concurrency
6	Binary Data
7	Module Utilities
8	Other Libraries

2.1	Interfaces Common to All Types
2.2	Tuple Types
2.3	Record Types
2.4	Enum Types
2.5	Singleton Types
2.6	Wrapper Types
2.7	Object Types
2.8	Struct Descriptors

2.5.1	Singleton Type Information
2.5.2	Singleton Type Descriptors
2.5.3	Singleton Type Bindings