The class of imperative octet stream scanners. Use new scanner () to make a basic scanner object that can progressively decode values out of the working slice initialized with slice. Use inherit scanner () to derive a subclass that implements more refined behavior by overriding private methods to manipulate the working slice and the cursor position. Use the ~start parameter to initialize the starting position counter to a number other than zero. (See documentation below for the various private members.)
val mutable slice_ : string Cf_slice.tThe working slice.
val mutable start_ : positionPosition of slice start.
method private work : string Cf_slice.t -> unitUse self#work slice to set slice as the working slice and set cursor_ to the start of slice.
method private octets : string Cf_slice.tUse self#octets to make a slice comprising the octets after the cursor index in the working slice.
A successful scan calls self#advance n to signal that a value was decoded from the n octets in the working slice at the cursor. The basis implementation increments both cursor_ and start_ by n octets.
If scanning a value requires at least n more octets to validate than are currently available in the working slice after the cursor, the basis implementation of self#scan applies self#incomplete n as necessary to update the working slice and cursor position until the working slice is large enough to decode a valid result.
The basis implementation raises Incomplete. A derived class may extend the current working slice, and also shift already consumed octets from the head of the working slice, provided that it adjusts the start position accordingly.
When preparing the working slice to decode according to s, the base implementation of self#scan applies self#acquire sz ck to acquire enough octets in the working slice after the check cursor to use safely with the rd function in s.
To accomplish this, it progressively calls self#incomplete as necessary while there are not enough octets in the working slice.
First, while sz is more than the length of the working slice, or if Incomplete is raised by applying ck start_ self#octets indicating a decoded length more than the length of the working slice, then self#incomplete n is applied to give the subclass a method of extending the working slice with n more octets of input, then if no exception is raised, the above procedure is repeated. Otherwise, returns the analysis result of the ck function.
The internal signaling exceptions for incomplete structure and validation error must never be raised to callers of this method.
Raises Failure if applying ck returns an analysis result with a decoding length that falls outside the working slice provided.
method private invalid : 'a. position -> string -> 'aWhen a decoding scheme calls the invalid i m function (see above), the scanner catches the internal exception and invokes this method to locate and validate the stream position p corresponding to i and raise Invalid (p, m) accordingly. Raises Failure if i is not an index into the current working slice.
method scan : 'v. 'v scheme -> 'vUse sxr#scan s to decode according to s zero or more octets at the read cursor in the working slice.
To accomplish this, it first applies self#acquire s to acquire enough working octets to decode a value and either returns Analysis (n, x) or raises an exception left for the caller to catch. The rd function in the decoding scheme is applied to the string value in the working slice and the intermediate result x to obtain the validated result of the scan. If no exception is raised by the rd function, then applies self#advance n and returns the scan result.
No exception raised by the self#acquire or self#advance methods, or raised by the rd function in the decoding scheme, is caught. The Invalid exception is provided for decoding schemes to signal that no valid value can be decoded in the rd function.
method position : positionUse sxr#position to get the total number of valid octets ever scanned by sxr.