<html><head><metahttp-equiv="content-type"content="text/html; charset=utf-8"/><title>Sugar: readability & convenience library</title><linkrel="stylesheet"type="text/css"href="scribble.css"title="default"/><linkrel="stylesheet"type="text/css"href="racket.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-style.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-racket.css"title="default"/><scripttype="text/javascript"src="scribble-common.js"></script><scripttype="text/javascript"src="manual-racket.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><bodyid="scribble-racket-lang-org"><divclass="tocset"><divclass="tocview"><divclass="tocviewlist tocviewlisttopspace"><divclass="tocviewtitle"><tablecellspacing="0"cellpadding="0"><tr><tdstyle="width: 1em;"><ahref="javascript:void(0);"title="Expand/Collapse"class="tocviewtoggle"onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><ahref="index.html"class="tocviewselflink"data-pltdoc="x">Sugar:<spanclass="mywbr"> </span> readability & convenience library</a></td></tr></table></div><divclass="tocviewsublistonly"style="display: none;"id="tocview_0"><tablecellspacing="0"cellpadding="0"><tr><tdalign="right">1 </td><td><ahref="index.html#%28part._.Installation___updates%29"class="tocviewlink"data-pltdoc="x">Installation & updates</a></td></tr><tr><tdalign="right">2 </td><td><ahref="index.html#%28part._.Coercion%29"class="tocviewlink"data-pltdoc="x">Coercion</a></td></tr><tr><tdalign="right">3 </td><td><ahref="index.html#%28part._.Container%29"class="tocviewlink"data-pltdoc="x">Container</a></td></tr><tr><tdalign="right">4 </td><td><ahref="index.html#%28part._.Debug%29"class="tocviewlink"data-pltdoc="x">Debug</a></td></tr><tr><tdalign="right">5 </td><td><ahref="index.html#%28part._.File%29"class="tocviewlink"data-pltdoc="x">File</a></td></tr><tr><tdalign="right">6 </td><td><ahref="index.html#%28part._.Len%29"class="tocviewlink"data-pltdoc="x">Len</a></td></tr><tr><tdalign="right">7 </td><td><ahref="index.html#%28part._.List%29"class="tocviewlink"data-pltdoc="x">List</a></td></tr><tr><tdalign="right">8 </td><td><ahref="index.html#%28part._.String%29"class="tocviewlink"data-pltdoc="x">String</a></td></tr><tr><tdalign="right">9 </td><td><ahref="index.html#%28part._.License___source_code%29"class="tocviewlink"data-pltdoc="x">License & source code</a></td></tr></table></div></div></div><divclass="tocsub"><tableclass="tocsublist"cellspacing="0"><tr><td><spanclass="tocsublinknumber"></span><ahref="#%28part._.Sugar__readability___convenience_library%29"class="tocsubseclink"data-pltdoc="x">Sugar:<spanclass="mywbr"> </span> readability & convenience library</a></td></tr><tr><td><spanclass="tocsublinknumber">1<tt> </tt></span><ahref="#%28part._.Installation___updates%29"class="tocsubseclink"data-pltdoc="x">Installation & updates</a></td></tr><tr><td><spanclass="tocsublinknumber">2<tt> </tt></span><ahref="#%28part._.Coercion%29"class="tocsubseclink"data-pltdoc="x">Coercion</a></td></tr><tr><td><spanclass="tocsublinknumber">2.1<tt> </tt></span><ahref="#%28part._.Values%29"class="tocsubseclink"data-pltdoc="x">Values</a></td></tr><tr><td><ahref="#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3eint%29%29"class="tocsubnonseclink"data-pltdoc="x"><spanclass="RktSym"><spanclass="RktValLink"><spanclass="nobreak">-<wbr></wbr>></span>int</span></span></a></td></tr><tr><td><ahref="#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3estring%29%29"class="tocsubnonseclink"data-pltdoc="x"><spanclass="RktSym"><spanclass="RktValLink"><spanclass="nobreak">-<wbr></wbr>></span>string</span></span></a></td></tr><tr><td><ahref="#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3esymbol%29%29"class="tocsubnonseclink"data-pltdoc="x"><spanclass="RktSym"><spanclass="RktValLink"><spanclass="nobrea
</div><divclass="SIntrapara"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">raco pkg install sugar</span></p></td></tr></table></div></p><p><divclass="SIntrapara">After that, you can update the package from the command line:
</div><divclass="SIntrapara"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">raco pkg update sugar</span></p></td></tr></table></div></p><h3>2<tt> </tt><aname="(part._.Coercion)"></a><aname="(mod-path._sugar/coerce)"></a>Coercion</h3><p><tablecellspacing="0"cellpadding="0"class="defmodule"><tr><tdalign="left"><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29"class="RktStxLink"data-pltdoc="x">require</a></span><spanclass="stt"></span><ahref="index.html#%28mod-path._sugar%2Fcoerce%29"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">sugar/coerce</span></a><spanclass="RktPn">)</span></td><tdalign="right"><spanclass="RpackageSpec"><spanclass="Smaller"> package:</span><spanclass="stt">sugar</span></span></td></tr></table></p><p>Functions that coerce the datatype of a value to another type. Racket already has type-specific conversion functions. But if you’re handling values of indeterminate type — as sometimes happens in an untyped language — then handling the possible cases individually gets to be a drag.</p><h4>2.1<tt> </tt><aname="(part._.Values)"></a>Values</h4><p><divclass="SIntrapara"><blockquoteclass="SVInsetFlow"><tablecellspacing="0"cellpadding="0"class="boxed RBoxed"><tr><td><blockquoteclass="SubFlow"><divclass="RBackgroundLabel SIEHidden"><divclass="RBackgroundLabelInner"><p>procedure</p></div></div><pclass="RForeground"><spanclass="RktPn">(</span><aname="(def._((lib._sugar/coerce..rkt)._-~3eint))"></a><spantitle="Provided from: sugar/coerce | Package: sugar"><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3eint%29%29"class="RktValDef RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>int</a></span></span><spanclass="hspace"> </span><spanclass="RktVar">v</span><spanclass="RktPn">)</span><spanclass="hspace"> </span>→<spanclass="hspace"> </span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/number-types.html#%28def._%28%28quote._~23~25kernel%29._integer~3f%29%29"class="RktValLink"data-pltdoc="x">integer?</a></span></p></blockquote></td></tr><tr><td><spanclass="hspace"> </span><spanclass="RktVar">v</span><spanclass="hspace"> </span>:<spanclass="hspace"> </span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29"class="RktValLink"data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><divclass="SIntrapara">Convert <spanclass="RktVar">v</span> to an integer in the least surprising way, or raise an error if no conversion is possible.</div></p><p>Numbers are rounded down to the nearest integer.</p><p><tablecellspacing="0"cellpadding="0"class="RktBlk"><tr><td><p>Examples:</p></td></tr><tr><td><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"class="RktBlk"><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3eint%29%29"class="RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>int</a></span><spanclass="hspace"> </span><spanclass="RktVal">3</span><spanclass="RktPn">)</span></td></tr><tr><td><p><spanclass="RktRes">3</span></p></td></tr><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3eint%29%29"class="RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>int</a></span><spanclass="hspace"> </span><spanclass="RktVal">3.5</span><spanclass="RktPn">)</span></td></tr><tr><td><p><spanclass="RktRes">3</span></p></td></tr><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt
</div><divclass="SIntrapara"><tablecellspacing="0"cellpadding="0"class="RktBlk"><tr><td><p>Example:</p></td></tr><tr><td><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"class="RktBlk"><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3eint%29%29"class="RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>int</a></span><spanclass="hspace"> </span><spanclass="RktVal">#t</span><spanclass="RktPn">)</span></td></tr><tr><td><p><spanclass="RktErr">Can’t convert #t to integer</span></p></td></tr></table></blockquote></td></tr></table></div></p><p><divclass="SIntrapara"><blockquoteclass="SVInsetFlow"><tablecellspacing="0"cellpadding="0"class="boxed RBoxed"><tr><td><blockquoteclass="SubFlow"><divclass="RBackgroundLabel SIEHidden"><divclass="RBackgroundLabelInner"><p>procedure</p></div></div><pclass="RForeground"><spanclass="RktPn">(</span><aname="(def._((lib._sugar/coerce..rkt)._-~3estring))"></a><spantitle="Provided from: sugar/coerce | Package: sugar"><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3estring%29%29"class="RktValDef RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>string</a></span></span><spanclass="hspace"> </span><spanclass="RktVar">v</span><spanclass="RktPn">)</span><spanclass="hspace"> </span>→<spanclass="hspace"> </span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29"class="RktValLink"data-pltdoc="x">string?</a></span></p></blockquote></td></tr><tr><td><spanclass="hspace"> </span><spanclass="RktVar">v</span><spanclass="hspace"> </span>:<spanclass="hspace"> </span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29"class="RktValLink"data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><divclass="SIntrapara">Return the most natural string representation of <spanclass="RktVar">v</span>, or raise an error if none exists.</div></p><p><tablecellspacing="0"cellpadding="0"class="RktBlk"><tr><td><p>Examples:</p></td></tr><tr><td><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"class="RktBlk"><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3estring%29%29"class="RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>string</a></span><spanclass="hspace"> </span><spanclass="RktVal">"string"</span><spanclass="RktPn">)</span></td></tr><tr><td><p><spanclass="RktRes">"string"</span></p></td></tr><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3estring%29%29"class="RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>string</a></span><spanclass="hspace"> </span><spanclass="RktVal">'</span><spanclass="RktVal">symbol</span><spanclass="RktPn">)</span></td></tr><tr><td><p><spanclass="RktRes">"symbol"</span></p></td></tr><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3estring%29%29"class="RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>string</a></span><spanclass="hspace"> </span><spanclass="RktVal">98.6</span><spanclass="RktPn">)</span></td></tr><tr><td><p><spanclass="RktRes">"98.6"</span></p></td></tr><tr><td><spanclass="stt">></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._-~3estring%29%29"class="RktValLink"data-pltdoc="x"><spanclass="nobreak">-></span>string</a></span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="http://docs
<br/>(first-condition? x) = #t</span></p><p>But don’t do this, because the result of the <spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29"class="RktStxLink"data-pltdoc="x">if</a></span> expression will be skipped in favor of the last expression, which will be the value of <spanclass="RktVar">x</span>:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"class="RktBlk"><tr><td><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29"class="RktStxLink"data-pltdoc="x">if</a></span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._and%29%29"class="RktStxLink"data-pltdoc="x">and</a></span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28form._%28%28lib._sugar%2Fdebug..rkt%29._report%29%29"class="RktStxLink"data-pltdoc="x">report</a></span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym">first-condition?</span><spanclass="hspace"> </span><spanclass="RktSym">x</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym">second-condition?</span><spanclass="hspace"> </span><spanclass="RktSym">x</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span></td></tr><tr><td><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym">one-thing</span><spanclass="RktPn">)</span></td></tr><tr><td><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym">other-thing</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span></td></tr><tr><td><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="index.html#%28form._%28%28lib._sugar%2Fdebug..rkt%29._report%29%29"class="RktStxLink"data-pltdoc="x">report</a></span><spanclass="hspace"> </span><spanclass="RktSym">x</span><spanclass="RktPn">)</span></td></tr></table></blockquote><h3>5<tt> </tt><aname="(part._.File)"></a><aname="(mod-path._sugar/file)"></a>File</h3><p><tablecellspacing="0"cellpadding="0"class="defmodule"><tr><tdalign="left"><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29"class="RktStxLink"data-pltdoc="x">require</a></span><spanclass="stt"></span><ahref="index.html#%28mod-path._sugar%2Ffile%29"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">sugar/file</span></a><spanclass="RktPn">)</span></td><tdalign="right"><spanclass="RpackageSpec"><spanclass="Smaller"> package:</span><spanclass="stt">sugar</span></span></td></tr></table></p><p>File utilities, mostly in the realm of file extensions. These functions don’t access the filesystem.</p><p>Arguments that are <spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Fcoerce..rkt%29._pathish~3f%29%29"class="RktValLink"data-pltdoc="x">pathish?</a></span> can take either a string or a path. For clarity below, I’ve used strings.</p><p><divclass="SIntrapara"><blockquoteclass="SVInsetFlow"><tablecellspacing="0"cellpadding="0"class="boxed RBoxed"><tr><td><blockquoteclass="SubFlow"><divclass="RBackgroundLabel SIEHidden"><divclass="RBackgroundLabelInner"><p>procedure</p></div></div><pclass="RForeground"><spanclass="RktPn">(</span><aname="(def._((lib._sugar/file..rkt)._get-ext))"></a><spantitle="Provided from: sugar/file | Package: sugar"><spanclass="RktSym"><ahref="index.html#%28def._%28%28lib._sugar%2Ffile..rkt%29._get-ext%29%29"class="RktValDef RktValLink"data-pltdoc="x">get-ext</a></span></span><spanclass="hspace"> </span><spanclass="RktVar">file-pat
