Commentary: Stream "index" Operators

General: The stream index operators are strictly informational. They can be used to find postions of data in streams without moving to those positions. Indexes are measured from the ends of the stream or from the current cursor position by counting bytes starting with 1. The cursor position is not affected.





Take for first line (s) ( `<- and `<- n): This operator is intended to give you the number of bytes you will need for a subsequent take operation. In the monadic form it returns the number of bytes to take the first line of the stream (delimited by CR/LF; LF/CR; CR; or LF). The count includes the terminating delimiter. In the dyadic form, the right argument is the number of lines you will want to take.




Take for last line(s) ( `-> and `-> n): This operator is intended to give you the number of bytes you will need for a subsequent take operation. In the monadic form it returns the number of bytes to take the last line of the stream (delimited by CR/LF; LF/CR; CR; or LF). The count includes the terminating delimiter. In the dyadic form, the right argument is the number of lines you will want to take.




Take For First To Any Delimiter Listed ( `<-| ): Returns the number of bytes you would take from the beginning of the stream to reach any of the listed delimiters (including the delimiter). If the delimiter is not found, the length of the stream is returned. This operator is intended for use with a subsequent take operation.




Take For Last To Any Delimiter Listed ( `->| ): Returns the number of bytes you would need to take from the end of the stream to reach and include any of the delimiting characters listed. If the delimiter is not found, the length of the stream is returned. This operator is intended for use with a subsequent take operation.




Take for First to All Matching ( `->& ): Returns the number of bytes to take from the beginning of a stream up to but not including a string of characters. Normally a Glee match is performed on the string and stream. However, preceeding with the @== forces exact match rules. If no match is found, the number of bytes in the stream is returned.




Take for Last to All Matching ( `<-& ): Returns the number of bytes to take from the end of the stream back to but not including a string of characters. Normally a Glee match is performed on the string and stream. However, preceeding with the @== forces exact match rules. If no match is found, the number of bytes in the stream is returned.




Bytes to next or previous line ( `->> or `<<- ):: Returns the number of bytes to stream to get to the next (or previous) line and include the delimiter. Line delimiters may be CR/LF, LF/CR, LF, or CR. This example illustrates streaming by lines. There is no read line operator because there is no special glyph for line. In this index context there is no need for an index next bytes operator so I use the next glyph for the implicit next line operator.




Bytes to next or previous lines ( `->> n or `<<- n ): Returns the number of bytes to stream to get to the next (or previous) number of lines and include the delimiter. Line delimiters may be CR/LF, LF/CR, LF, or CR. This example illustrates streaming by lines. There is no read line operator because there is no special glyph for line. In this index context there is no need for an index next bytes operator so I use the next glyph for the implicit next line operator.




Index to next or previous any ( `->>| 'delim' or `<<-| 'delim' ): Index of the next (or previous) occurrence of any of the delimiters given in the string. If none are found the index is 0 for previous and streamlength + 1 for next. To read to the next delimiter use " ->>|".




Index to next or previous all ( `->>& 'str' or `<<-& 'str'' ): Index of the next (or previous) occurrence matching the string. By default, a Glee match is performed. This ignores case, converts non-alphanumerics to blanks, and then ignores extraneous whitespace. To obtain exact matches, use the " @== " qualifier as shown in the example. If none are found the index is 0 for previous and streamlength + 1 for next. To read to the next all match use " ->>&".




:




:




:




: