The Standard ML Basis Library

The `StringCvt` structure

The StringCvt structure provides types and functions for handling the conversion between strings and values of various basic types.

Synopsis

signature STRING_CVT structure StringCvt : STRING_CVT

Interface

datatype radix = BIN | OCT | DEC | HEX datatype realfmt = SCI of int option | FIX of int option | GEN of int option type cs type ('a, 'b) reader = 'b -> ('a * 'b) option val padLeft : char -> int -> string -> string val padRight : char -> int -> string -> string val splitl : (char -> bool) -> (char, 'a) reader ->'a -> (string * 'a) val takel : (char -> bool) -> (char, 'a) reader ->'a -> string val dropl : (char -> bool) -> (char, 'a) reader ->'a -> 'a val skipWS : (char, 'a) reader -> 'a -> 'a val scanString : ((char, cs) reader -> ('a, cs) reader) -> string -> 'a option val scanList : ((char, char list) reader -> ('a, char list) reader) -> char list -> ('a * char list) option

Description

datatype radix

The values of type radix are used to specify the radix of a representation of an integer, corresponding to the bases 2, 8, 10 and 16, respectively.

datatype realfmt

Values of type realfmt are used to specify the format of a real or floating-point number. The first two correspond to scientific and fixed-point representations, respectively. The optional integer value specifies the number of decimal digits to appear after the decimal point, with 6 being the default. In particular, if 0 is specified, there should be no fractional part. The third constructor GEN allows a formatting function to use either the scientific or fixed-point notation, typically guided by the magnitude of the number. The optional integer value specifies the number of significant digits, with 12 being the default.

type cs

character stream used by scanString.

type ('a, 'b) reader

type representing a reader producing values of type 'a from a stream of type 'b. A return value of SOME(a,b) corresponds to a value a scanned from the stream, plus the remainder b of the stream. A return value of NONE indicates that no value of the correct type could be scanned from the stream.

padLeft c i s

padRight c i s

return s padded, on the left and right, respectively, with i - size s copies of the character c. If size s >= i, they just return the string s. In other words, these functions right- and left-justify s in a field i characters wide, never trimming off any part of s. Note that if i <= 0, s is returned. These functions raise Size if the size of the resulting string would be greater than String.maxSize.

splitl p f src

returns (pref, src') where pref is the longest prefix (left substring) of src, as produced from src by the character reader f, all of whose characters satisfy p, and src' is the remainder of src. Thus, the first character retrievable from src' is the leftmost character not satisfying p.

splitl can be used with scanning functions such as scanString by composing it with SOME; e.g., scanString (fn g => SOME o (splitl g)).

takel p f src

dropl p f src

These routines scan the source src for the first character not satisfying the predicate p. The function dropl drops the maximal prefix satisfying the predicate, returning the rest of the source, while takel returns the maximal prefix satisfying the predicate. These can be defined in terms of splitl:

          takel p f s = #1(splitl p f s)
          dropl p f s = #2(splitl p f s)

skipWS f s

strips whitespace characters from a stream s using the reader f. It returns the remaining stream. A whitespace character is one that satisfies the predicate Char.isSpace. Equivalent to dropl Char.isSpace.

scanString f s

The function scanString provides a general framework for converting a string into some value. The user supplies a scanning function f and a string s. scanString converts the string into a character source (type cs) and applies the scanning function. A scanning function converts a reader of characters into a reader of values of the desired type. Typical scanning functions are Bool.scan and Date.scan.

scanList f c

The function scanList provides the analogous role for character lists that scanString provides for strings.

Question:

Should this function return 'a option like scanString?

Discussion

The scanning functions skipWS and scanString are designed for stream IO. In particular, they consume lookahead characters, so if they were applied to an imperative stream, the lookahead character would be lost.