On this page:
converter?
convert-forward
convert-backward
make-converter
converter/  c
1.9.1 Predefined Converters
number<->string
string<->symbol
string<->keyword
symbol<->keyword
identity-converter
1.9.2 Converter Utilities
converter-flip
converter-pipe
8.3

1.9 Converters

 (require rebellion/base/converter) package: rebellion

A converter is an object that can convert back and forth between two kinds of values: the converter’s conversion domain and conversion range. Converters need not be exact one-to-one mappings, more commonly a converter is lossy and may lose some information by normalizing converted values. However, repeatedly converting a value back and forth is not expected to lose more information than converting it back and forth a single time. Converters are typically named in the pattern domain<->range.

Examples:

procedure

(converter? v)  boolean?

  v : any/c
A predicate for converters.

procedure

(convert-forward converter input)  any/c

  converter : converter?
  input : any/c
Converts input from the domain of converter to its range.

Examples:

procedure

(convert-backward converter input)  any/c

  converter : converter?
  input : any/c
Converts input from the range of converter to its domain.

Examples:

procedure

(make-converter forward-function    
  backward-function    
  [#:name name])  converter?
  forward-function : (-> any/c any/c)
  backward-function : (-> any/c any/c)
  name : (or/c interned-symbol? #false) = #false
Constructs a converter named name that uses forward-function and backward-function to convert values. The two functions are expected to be inverses of each other, however they are allowed to lose some information by normalizing their outputs. More formally, (forward-function x) should have the same result as (forward-function (backward-function (forward-function x))) and (backward-function y) should have the same result as (backward-function (forward-function (backward-function y))).

Examples:
(define lowercase<->uppercase
  (make-converter string-upcase string-downcase))

 

> (convert-forward lowercase<->uppercase "foo")

"FOO"

> (convert-backward lowercase<->uppercase "FOO")

"foo"

> (convert-forward lowercase<->uppercase "Foo")

"FOO"

procedure

(converter/c domain-contract    
  range-contract)  contract?
  domain-contract : contract?
  range-contract : contract?
A contract combinator for converters. Constructs a contract that recognizes converters which convert from values satisfying domain-contract to values satisfying range-contract.

1.9.1 Predefined Converters

A converter between numbers and strings. Numbers are turned into strings using number->string, and strings are parsed into numbers using string->number. The converter accepts both mutable and immutable strings as input, but it only outputs immutable strings.

Examples:

A converter between strings and symbols. The converter accepts mutable strings, immutable strings, interned symbols, unreadable symbols, and uninterned symbols as inputs, but it only outputs immutable strings and interned symbols.

Examples:
> (convert-forward string<->symbol "grape")

'grape

> (convert-backward string<->symbol 'pineapple)

"pineapple"

> (convert-backward string<->symbol (gensym))

"g777605"

A converter between strings and keywords. The converter accepts both mutable and immutable strings as inputs, but it only outputs immutable strings.

Examples:
> (convert-forward string<->keyword "jazz")

'#:jazz

> (convert-backward string<->keyword '#:blues)

"blues"

A converter between symbols and keywords. The converter accepts interned symbols, unreadable symbols, and uninterned symbols as inputs, but it only outputs interned symbols.

Examples:

The identity converter, which does nothing at all to its inputs.

Examples:

1.9.2 Converter Utilities

procedure

(converter-flip converter)  converter?

  converter : converter?
Flips converter, returning a new converter with a swapped notion of forward and backward. Converting forward with the flipped converter is equivalent to converting backward with converter and vice versa.

Examples:
(define string<->number (converter-flip number<->string))

 

> (convert-forward string<->number "42")

42

> (convert-backward string<->number 79)

"79"

procedure

(converter-pipe converter ...)  converter?

  converter : converter?
Pipes each converter to the next, one after the other, and returns a single composite converter. When converting forwards with the returned converter, the input is converted with each converter in left to right order. When converting backwards, it’s converted in right to left order. If no converters are given, then the returned converter is equivalent to identity-converter.

Examples:
(define number<->keyword (converter-pipe number<->string string<->keyword))

 

> (convert-forward number<->keyword 42)

'#:42

> (convert-backward number<->keyword '#:375)

375