15.3.298  src/lib/core/init/substring.api

## substring.api


stipulate
    include package   base_types;                                                       # base_types            is from   src/lib/core/init/built-in.pkg
    include package   proto_pervasive;                                          # proto_pervasive       is from   src/lib/core/init/proto-pervasive.pkg
herein

    api Substring {
        #
        eqtype Char;
        eqtype String;

        Substring;


        get:              (Substring, Int) -> Char;
        size:              Substring -> Int;
        burst_substring: Substring -> (String, Int, Int);               # A substring is in fact a slice of a string.
        extract:          (String, Int, Null_Or(Int)) -> Substring;
        make_substring:   (String, Int, Int) -> Substring;
        from_string:       String -> Substring;
        to_string:         Substring -> String;

        is_empty:  Substring -> Bool;

        getc:   Substring -> Null_Or ((Char, Substring));
        first:  Substring -> Null_Or( Char );

        # Drop first or last N chars from substring:
        #
        drop_first:  Int -> Substring -> Substring;
        drop_last:   Int -> Substring -> Substring;

        make_slice:    (Substring, Int, Null_Or(Int)) -> Substring;
        cat:     List( Substring ) -> String;
        join:         String -> List( Substring ) -> String;
        join':        String -> String -> String -> List( Substring ) -> String;
        explode:  Substring -> List( Char );

        is_prefix:     String -> Substring -> Bool;
        is_substring:  String -> Substring -> Bool;
        is_suffix:     String -> Substring -> Bool;

        compare:   (Substring, Substring) -> Order;
        compare_sequences:   ((Char, Char) -> Order) -> (Substring, Substring) -> Order;

        # Return the longest prefix/suffix
        # whose chars each satisfy given predicate:
        #
        get_prefix:   (Char -> Bool) -> Substring -> Substring;
        get_suffix:   (Char -> Bool) -> Substring -> Substring;

        # Opposite of above:  Return all of substring
        # except the longest prefix/suffix whose chars
        # chars each satisfy given predicate:
        #
        drop_prefix:   (Char -> Bool) -> Substring -> Substring;
        drop_suffix:   (Char -> Bool) -> Substring -> Substring;

        # Split substring into two substrings:
        # First is the longest prefix whose chars
        # all satisfy given predicate, second is the rest:
        #
        split_off_prefix:   (Char -> Bool) -> Substring -> (Substring, Substring);

        # Converse of above:  Split substring into
        # two substrings, second of which is the
        # longest suffix whose chars all satisfy
        # given predicate, first of which is the rest:
        #
        split_off_suffix:   (Char -> Bool) -> Substring -> (Substring, Substring);

        split_at:  ((Substring, Int)) -> (Substring, Substring);

        position:  String -> Substring -> (Substring, Substring);

        span:  ((Substring, Substring)) -> Substring;

        translate:  (Char -> String) -> Substring -> String;

        tokens:  (Char -> Bool) -> Substring -> List( Substring );
        fields:  (Char -> Bool) -> Substring -> List( Substring );

        apply:    (Char -> Void) -> Substring -> Void;
        fold_forward:  (((Char, X)) -> X) -> X -> Substring -> X;
        fold_backward:  (((Char, X)) -> X) -> X -> Substring -> X;

    };
end;


## COPYRIGHT (c) 1995 AT&T Bell Laboratories.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.