diff --git a/doc/Container.html b/doc/Container.html index 3c6c06e..cf3e70c 100644 --- a/doc/Container.html +++ b/doc/Container.html @@ -1,2 +1,2 @@ -3 Container
▼Sugar:   readability & convenience library
On this page:
get
in?
6.0.1.13
    ← prev  up  next → 

3 Container

 (require sugar/container) package: sugar

Type-neutral functions for getting elements out of a container, or testing membership.

procedure

(get container which [end_which]) → any/c

  container : (or/c list? vector? sequence? dict? string? symbol? path?)
  which : any/c
  end_which : (or/c (and/c integer? positive?) #f) = #f
For a container that’s a dict?, retrieve the element associated with the key which. Raise an error if the key doesn’t exist.

Examples:

> (get (make-hash '((a . 1) (b . 2) (c  . 3))) 'b)

2

> (get (make-hash '((a . 1) (b . 2) (c  . 3))) 'z)

get: couldn’t retrieve item z from #hash((a . 1) (c . 3) (b

. 2))

For other container types — which are all sequence-like — retrieve the element located at which. Or if the optional end_which argument is provided, retrieve the elements from which to (sub1 end_which), inclusive (i.e., make a slice). Raise an error if which or end_which is out of bounds.

Examples:

> (get '(0 1 2 3 4 5) 2)

2

> (get '(0 1 2 3 4 5) 2 4)

'(2 3)

> (get '(0 1 2 3 4 5) 100)

get: couldn’t retrieve item 100 from (0 1 2 3 4 5)

> (get '(0 1 2 3 4 5) 2 100)

get: couldn’t retrieve items 2 through 100 from (0 1 2 3 4

5)

> (get (list->vector '(0 1 2 3 4 5)) 2)

2

> (get (list->vector '(0 1 2 3 4 5)) 2 4)

'#(2 3)

> (get "purple" 2)

"r"

> (get "purple" 2 4)

"rp"

> (get 'purple 2)

'r

> (get 'purple 2 4)

'rp

When container is a path, it’s treated as a list of path elements (created by explode-path), not as a stringlike value.

Examples:

> (get (string->path "/root/foo/bar/file.txt") 1)

#<path:root>

> (get (string->path "/root/foo/bar/file.txt") 0 3)

'(#<path:/> #<path:root> #<path:foo>)

To slice to the end of container, use (len container) as the value of end_which.

Examples:

> (define xs '(0 1 2 3 4 5))
> (get xs 2 (len xs))

'(2 3 4 5)

> (get (list->vector xs) 2 (len (list->vector xs)))

'#(2 3 4 5)

> (define color "purple")
> (get color 2 (len color))

"rple"

procedure

(in? item container) → boolean?

  item : any/c
  container : (or/c list? vector? sequence? set? dict? string? symbol? path?)
Return #t if item is in container, or #f otherwise.

Examples:

> (in? 2 '(0 1 2 3 4 5))

#t

> (in? 'a '(0 1 2 3 4 5))

#f

> (in? 2 (list->vector '(0 1 2 3 4 5)))

#t

> (in? "pu" "purple")

#t

> (in? "zig" "purple")

#f

> (in? 'b (make-hash '((a . 1) (b . 2) (c  . 3))))

#t

> (in? 'z (make-hash '((a . 1) (b . 2) (c  . 3))))

#f

As with get, when container is a path, it’s treated as a list of exploded path elements, not as a stringlike value.

Examples:

> (in? "foo" (string->path "/root/foo/bar/file.txt"))

#t

> (in? "zam" (string->path "/root/foo/bar/file.txt"))

#f

    ← prev  up  next → 
 
\ No newline at end of file +3 Container
▼Sugar:   readability & convenience library
On this page:
get
in?
6.0.1.13
    ← prev  up  next → 

3 Container

 (require sugar/container) package: sugar

Type-neutral functions for getting elements out of a container, or testing membership.

procedure

(get container which [end_which]) → any/c

  container : (or/c list? vector? sequence? dict? string? symbol? path?)
  which : any/c
  end_which : (or/c (and/c integer? positive?) #f) = #f
For a container that’s a dict?, retrieve the element associated with the key which. Raise an error if the key doesn’t exist.

Examples:

> (get (make-hash '((a . 1) (b . 2) (c  . 3))) 'b)

len: can’t calculate length of 2

> (get (make-hash '((a . 1) (b . 2) (c  . 3))) 'z)

get: couldn’t retrieve item z from #hash((a . 1) (c . 3) (b

. 2))

For other container types — which are all sequence-like — retrieve the element located at which. Or if the optional end_which argument is provided, retrieve the elements from which to (sub1 end_which), inclusive (i.e., make a slice). Raise an error if which or end_which is out of bounds.

Examples:

> (get '(0 1 2 3 4 5) 2)

2

> (get '(0 1 2 3 4 5) 2 4)

'(2 3)

> (get '(0 1 2 3 4 5) 100)

get: couldn’t retrieve item 100 from (0 1 2 3 4 5)

> (get '(0 1 2 3 4 5) 2 100)

get: couldn’t retrieve items 2 through 100 from (0 1 2 3 4

5)

> (get (list->vector '(0 1 2 3 4 5)) 2)

2

> (get (list->vector '(0 1 2 3 4 5)) 2 4)

'#(2 3)

> (get "purple" 2)

"r"

> (get "purple" 2 4)

"rp"

> (get 'purple 2)

'r

> (get 'purple 2 4)

'rp

When container is a path, it’s treated as a list of path elements (created by explode-path), not as a stringlike value.

Examples:

> (get (string->path "/root/foo/bar/file.txt") 1)

#<path:root>

> (get (string->path "/root/foo/bar/file.txt") 0 3)

'(#<path:/> #<path:root> #<path:foo>)

To slice to the end of container, use (len container) as the value of end_which.

Examples:

> (define xs '(0 1 2 3 4 5))
> (get xs 2 (len xs))

'(2 3 4 5)

> (get (list->vector xs) 2 (len (list->vector xs)))

'#(2 3 4 5)

> (define color "purple")
> (get color 2 (len color))

"rple"

procedure

(in? item container) → boolean?

  item : any/c
  container : (or/c list? vector? sequence? set? dict? string? symbol? path?)
Return #t if item is in container, or #f otherwise.

Examples:

> (in? 2 '(0 1 2 3 4 5))

#t

> (in? 'a '(0 1 2 3 4 5))

#f

> (in? 2 (list->vector '(0 1 2 3 4 5)))

#t

> (in? "pu" "purple")

#t

> (in? "zig" "purple")

#f

> (in? 'b (make-hash '((a . 1) (b . 2) (c  . 3))))

#t

> (in? 'z (make-hash '((a . 1) (b . 2) (c  . 3))))

#f

As with get, when container is a path, it’s treated as a list of exploded path elements, not as a stringlike value.

Examples:

> (in? "foo" (string->path "/root/foo/bar/file.txt"))

#t

> (in? "zam" (string->path "/root/foo/bar/file.txt"))

#f

    ← prev  up  next → 
 
\ No newline at end of file diff --git a/doc/Len.html b/doc/Len.html index 8b1e30a..bcf5ebc 100644 --- a/doc/Len.html +++ b/doc/Len.html @@ -1,2 +1,2 @@ -6 Len
▼Sugar:   readability & convenience library
On this page:
len
6.0.1.13
    ← prev  up  next → 

6 Len

 (require sugar/len) package: sugar

procedure

(len x) → integer?

  x : (or/c list? string? symbol? vector? hash? integer? set?)
Convert x to a length in the least surprising way possible, or raise an error if it can’t be done.

    ← prev  up  next → 
 
\ No newline at end of file +6 Len
▼Sugar:   readability & convenience library
On this page:
len
6.0.1.13
    ← prev  up  next → 

6 Len

 (require sugar/len) package: sugar

procedure

(len x) → integer?

  x : (or/c list? vector? set? string? symbol? path? hash?)
Calculate the length of x in the least surprising way possible, or if it can’t be done, raise an error. Named in honor of the original discover of the length-reticulation algorithm, Prof. Leonard Spottiswoode.

Examples:

> (len '(a b c))

3

> (len (list->vector '(a b c)))

3

> (len 'abc)

3

> (len "abc")

3

> (len (string->path "abc"))

3

> (len (make-hash `((a . 1)(b . 2)(c . 3))))

3

Perhaps ironically, positive integers do not have a length.

Example:

> (len 3)

len: can’t calculate length of 3

    ← prev  up  next → 
 
\ No newline at end of file diff --git a/installation.scrbl b/installation.scrbl deleted file mode 100644 index 50ab25b..0000000 --- a/installation.scrbl +++ /dev/null @@ -1,10 +0,0 @@ -#lang scribble/manual - - -@title{Installation & updates} - -At the command line: -@verbatim{raco pkg install sugar} - -After that, you can update the package from the command line: -@verbatim{raco pkg update sugar} \ No newline at end of file diff --git a/len.rkt b/len.rkt index b869f0f..e898057 100644 --- a/len.rkt +++ b/len.rkt @@ -1,9 +1,9 @@ #lang racket/base -(require racket/set) +(require racket/set racket/sequence) +(require "define.rkt") -(provide len) - -(define (len x) +(define+provide/contract (len x) + ((or/c list? vector? set? sequence? string? symbol? path? hash?) . -> . integer?) (cond [(list? x) (length x)] [(string? x) (string-length x)] @@ -11,6 +11,6 @@ [(path? x) (len (path->string x))] [(vector? x) (vector-length x)] [(hash? x) (len (hash-keys x))] - [(integer? x) (len (number->string x))] [(set? x) (len (set->list x))] + [(and (sequence? x) (not (integer? x))) (len (sequence->list x))] [else (error "len: can’t calculate length of" x)])) \ No newline at end of file diff --git a/scribblings/len.scrbl b/scribblings/len.scrbl index 28411da..b67be0f 100644 --- a/scribblings/len.scrbl +++ b/scribblings/len.scrbl @@ -10,6 +10,20 @@ @defproc[ (len -[x (or/c list? string? symbol? vector? hash? integer? set?)]) +[x (or/c list? vector? set? string? symbol? path? hash?)]) integer?] -Convert @racket[_x] to a length in the least surprising way possible, or raise an error if it can't be done. \ No newline at end of file +Calculate the length of @racket[_x] in the least surprising way possible, or if it can't be done, raise an error. Named in honor of the original discover of the length-reticulation algorithm, Prof. Leonard Spottiswoode. + +@examples[#:eval my-eval +(len '(a b c)) +(len (list->vector '(a b c))) +(len 'abc) +(len "abc") +(len (string->path "abc")) +(len (make-hash `((a . 1)(b . 2)(c . 3)))) +] + +Perhaps ironically, positive integers do not have a length. + +@examples[#:eval my-eval +(len 3)] \ No newline at end of file