239: Destructuring Lists

by Marc Nieper-Wißkirchen

Status

This SRFI is currently in final status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-239@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.

Received: 2022-11-04
Draft #1 published: 2022-11-04
Finalized: 2023-01-23

Abstract

This SRFI provides the list-case, the syntactic fundamental list destructor.

Rationale

The list data type is the initial algebra with constructors (cons obj list) and (). Destructing a list step-wise thus means testing whether the list is a pair or (), and retrieving the car and cdr of the pair in the first case. In practise, this often leads to Scheme code of the following form (even the sample implementation of this SRFI contains such code):

(let ([ls ⟨list-expression⟩])
  (cond
    [(pair? ls)
     (let ([head (car ls)] [(tail (cdr ls))])
       ...)]
    [(null? ls)
     ...]
    [else
     (assert #f)]))

This SRFI defines syntax that abstracts over this (and also generalizes destructuring to improper lists):

(list-case ⟨list-expression⟩
  [(head . tail)
   ...]
  [()
   ...]
  [_
   (assert #f)])

Specification

The following syntax is exported in R⁶RS systems by the libraries (srfi :239) and (srfi :239 list-case) and in R⁷RS systems by the library (srfi 239).

(list-case ⟨expression⟩ ⟨list-case clause⟩ …)

_

Syntax: ⟨expr⟩ is an expression. Each ⟨list-case clause⟩ is of one of the following forms:

[(⟨variable⟩ . ⟨variable⟩) ⟨body⟩]

[() ⟨body⟩]

[⟨variable⟩ ⟨body⟩]

It is a syntax violation if more than one clause of the same form is present.

_ is auxiliary syntax identical to _ exported by the standard libraries

Semantics: A list-case expression is evaluated as follows: The ⟨expression⟩ is evaluated. The further evaluation then depends on the type of the result:

If the result is a pair and a clause of the form [(⟨variable₁⟩ . ⟨variable₂⟩) ⟨body⟩] is present, the ⟨variables⟩ are bound to locations holding the car and the cdr of the pair, the ⟨body⟩ is evaluated and its results returned.

If the result is () and clause of the form [() ⟨body⟩] is present, the ⟨body⟩ is evaluated and its results returned.

If the result is neither a pair nor () and a clause of the form [⟨variable⟩ ⟨body⟩] is present, the ⟨variable⟩ is bound to a location holding the result, the ⟨body⟩ is evaluated and its results returned.

If no corresponding clause is present, an exception of type &assertion-violation is raised.

The region of the bindings consists of the corresponding ⟨body⟩. If _ appears in place of a ⟨variable⟩, the corresponding location is not bound to any variable.

If the list-case expression is in tail context, the ⟨bodies⟩ are in tail context as well.

Note: The order of the clauses does not matter.

Examples

(define type-of
  (lambda (obj)
    (list-case obj
      [(_ . _) 'pair]
      [() 'null]
      [_ 'atom])))

(define fold
  (lambda (proc seed ls)
    (let f ([acc seed] [ls ls])
      (list-case ls
        [(h . t) (f (proc h acc) t)]
        [() acc]
        [_ (assertion-violation 'fold "not a list" ls)]))))

Implementation

The sample implementation is written in portable R⁶RS. A portable R⁷RS Small-implementation is possible as well. (Volunteers to contribute one are more than welcome.)

Source for the sample implementation.

Acknowledgements

Thanks to the participants on this SRFI's mailing list.

Copyright

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Editor: Arthur A. Gleckler