source: project/wiki/eggref/4/rope @ 36801

Last change on this file since 36801 was 36801, checked in by evhan, 13 months ago

wiki/eggref: update docs/formatting/urls and eggref/5/{r7rs,fancypants,chicken-belt}

File size: 4.7 KB
Line 
1[[tags: egg]]
2
3== rope
4
5[[toc:]]
6
7== Description
8
9Ropes, as described in "Ropes, An Alternative to Strings" (1995 - H. Boehm, R. Atkinson, M. Plass).
10
11The source for this extension is available
12[[https://git.foldling.org/rope.git|here]].
13
14== API
15
16<record>rope</record>
17<procedure>(rope? object) => boolean</procedure>
18<procedure>(rope-length rope) => integer</procedure>
19<procedure>(rope-depth rope) => integer</procedure>
20
21A rope is either a leaf containing a string or a binary tree consisting of such
22leaves.
23
24Length and depth are stored on each node, so {{rope-length}} and {{rope-depth}}
25are constant time queries.
26
27{{rope?}} simply tests if its argument is a rope.
28
29<procedure>(rope=? rope1 rope2 [ropeN ...]) => boolean</procedure>
30
31{{rope=?}} tests whether two ropes represent the same string. Fast paths are
32provided on {{eq?}}ity and {{rope-length}}; otherwise, this comparison is O(n).
33
34<parameter>(current-maximum-leaf-length [n])</parameter>
35
36{{current-maximum-leaf-length}} specifies the maximum string length for rope
37leaf nodes.
38
39The default value is 512, which should be suitable for most purposes. Setting
40this value too low will result in frequent rebalancing, adversely affecting
41performance.
42
43<procedure>(rope-null? rope) => boolean</procedure>
44
45Tests whether the given rope is empty. Equivalent to {{(= 0 (rope-length rope))}}.
46
47<procedure>(rope [string ...]) => rope</procedure>
48
49Constructs a rope from the given strings. The resulting rope, while not
50guaranteed to be balanced, should be fairly so.
51
52<procedure>(string->rope string) => rope</procedure>
53
54Constructs a rope from the given string. The resulting rope is guaranteed to
55be balanced.
56
57<procedure>(rope->string rope) => string</procedure>
58
59Returns the full contents of the given rope as a string.
60
61<procedure>(rope-ref rope i) => character</procedure>
62
63Returns the {{i}}th character of the rope, zero-indexed.
64
65<procedure>(subrope rope start [end]) => rope</procedure>
66
67Returns a subrope consisting of the range of characters starting at the
68zero-indexed character {{start}} and ending at character {{end}}, or the end of
69the rope if no {{end}} is given.
70
71<procedure>(rope-append [rope ...]) => rope</procedure>
72
73Appends the given ropes, trying to keep the resulting rope fairly
74well-balanced.
75
76<procedure>(rope-concatenate list) => rope</procedure>
77
78Constructs a new rope from the the given list of ropes, trying to keep the
79resulting rope fairly well-balanced.
80
81<procedure>(rope-reverse rope)</procedure>
82
83Constructs a new rope consisting of the characters in the given rope, reversed.
84This operation is expensive for large ropes (O(n) in the length of the rope,
85best-case).
86
87<procedure>(rope-balanced? rope) => boolean</procedure>
88
89Tests whether the given rope is balanced. A rope is balanced if its length is
90at least {{F(n+2)}}, where {{F(n)}} is the {{n}}th fibonacci number and {{n}}
91is the depth of the given rope.
92
93<procedure>(rope-balance rope) => rope</procedure>
94
95Explicitly rebalances a rope.
96
97The rebalancing strategy used is that described in Boehm, Atkinson & Plass'
981995 paper "Ropes, An Alternative to Strings".
99
100<procedure>(rope-fold f a rope1 [ropeN ...]) => object</procedure>
101<procedure>(rope-for-each f rope1 [ropeN ...]) => void</procedure>
102
103These procedures implement characterwise {{fold}} and {{for-each}} over the
104given ropes.
105
106<procedure>(read-rope [port [length]]) => rope</procedure>
107
108Reads a rope from the given port, or {{current-input-port}} if no port is specified.
109
110If a numerical length argument is given, at most that many characters are read.
111
112The resulting rope is guaranteed to be balanced.
113
114<procedure>(make-rope-iterator rope) => procedure</procedure>
115
116Returns a cursor procedure over the given rope's characters.
117
118The resulting procedure, when invoked, will return the current character in the
119rope and advance to the next character. When the characters of the rope are
120exhausted, the procedure will yield {{#!eof}}.
121
122<procedure>(open-input-rope rope) => port</procedure>
123
124Returns a port from which the contents of the rope can be read. When the end of
125the rope is reached, subsequent reads will return {{#!eof}}.
126
127<procedure>(open-output-rope) => port</procedure>
128<procedure>(get-output-rope [port]) => rope</procedure>
129
130{{open-output-rope}} returns a port to which output can be written and
131accumulated, until returned as a rope with {{get-output-rope}}.
132
133In reality, {{open-output-rope}} and {{open-output-string}} are the same.
134Construction of the rope returned by {{get-output-rope}} is delayed until that
135procedure is called, so {{get-output-rope}} may be used to return a rope from
136the accumulated output of ports created by either {{open-output-rope}} or
137{{open-output-string}}.
138
139== Author
140
141[[/users/evan-hanson|Evan Hanson]]
142
143== License
144
1453-Clause BSD
Note: See TracBrowser for help on using the repository browser.