#lang scribble/doc @(require "base.ss") @title[#:tag "string"]{String utilities} @(define-eval string-eval (planet untyped/unlib/string)) @defmodule[(planet untyped/unlib/string)]{ Useful string utilities. Compatible with PLT 4 languages. @defproc[(string+false? [item any]) boolean?]{ Returns @scheme[#t] if @scheme[item] is a string and @scheme[#f] otherwise.} @defproc[(ensure-string [item any]) any]{ Converts @scheme[bytes] arguments to @scheme[string]@schemeidfont{s}: passes all other arguments straight through.} @defproc*[([(string-length/c [max natural]) flat-contract?] [(string-length/c [min natural] [max natural]) flat-contract?])]{ Creates a contract that recognises strings with a length within the specified inclusive bounds.} @defproc[(string-delimit [items (listof string?)] [delimiter string?] [#:prefix prefix (U string? #f) #f] [#:suffix suffix (U string? #f) #f]) string?]{ Similar to @scheme[string-join] from SRFI 13, except that the optional @scheme[#:prefix] and @scheme[#:suffix] arguments can be provided to add a prefix or suffix string. @examples[ #:eval string-eval (string-delimit '("1" "2" "3") ",") (string-delimit '("1" "2" "3") "," #:prefix "[") (string-delimit '("1" "2" "3") "," #:suffix "]") (string-delimit '("1" "2" "3") "," #:prefix "[" #:suffix "]") (string-delimit '("1" "2" "3") "," #:prefix #f #:suffix #f)]} @defproc[(string-ellipsify [str string?] [max-length natural? 20] [ellipsis string? "..."]) string?]{ Returns a shortened version of @scheme[str] that is never longer than @scheme[max-length]. If necessary, @scheme[str] is truncated and @scheme[ellipsis] is appended. @examples[ #:eval string-eval (string-ellipsify "The quick brown fox jumped over the lazy dog.") (string-ellipsify "The quick brown fox.")]} @defproc[(string-sentencecase [str string?]) string?]{ Returns a copy of @scheme[str] with the first character upcased. @examples[ #:eval string-eval (string-sentencecase "lowercase to capitalised") (string-sentencecase "Capitalised stays capitalised") (string-sentencecase "ALLCAPS stays ALLCAPSED")]} @defproc[(string-titlecase* [str string?]) string?]{ Like @scheme[string-titlecase], in that the first character of each word is upcased, except that any upcase characters are left upcased. @examples[ #:eval string-eval (string-titlecase* "lowercase to titlecase") (string-titlecase* "InterCapsed stays interCapsed") (string-titlecase* "ALLCAPS stays ALLCAPSED")]} @defproc[(number+false->string+false [num (U number? #f)]) (U string? #f)]{ A version of @scheme[number->string] that accepts and passes through @scheme[#f].} @defproc[(string+false->number+false [str (U string? #f)]) (U number? #f)]{ A version of @scheme[string->number] that accepts and passes through @scheme[#f].} @defproc[(string+false->symbol+false [str (U string? #f)]) (U symbol? #f)]{ A version of @scheme[string->symbol] that accepts and passes through @scheme[#f].} @defproc[(symbol+false->string+false [sym (U symbol? #f)]) (U string? #f)]{ A version of @scheme[symbol->string] that accepts and passes through @scheme[#f].} @defproc[(natural->hex-string [num natural?] [#:uppercase? uppercase? boolean? #f] [#:digits digits natural? 1] [#:prefix? prefix? boolean? #f]) natural?]{ Converts a natural number to a hexadecimal string. Arguments: @itemize{ @item{@scheme[uppercase?] - generate uppercase strings (the default is lowercase);} @item{@scheme[digits] - pad the string to a certain number of hexadecimal digits (only pads the string - does not trim it);} @item{@scheme[prefix?] - generate strings with a @scheme["0x"] prefix (the default is unprefixed).}}} @defproc[(hex-string->natural [str string?] [#:prefix? prefix? boolean? #f]) natural?]{ Converts a hexadecimal string like @scheme["ff"] to a natural number. Case insensitive. Set @scheme[prefix?] to @scheme[#t] to accept strings with a @scheme["0x"] prefix.} } @;{end defmodule}