# match

Definition: | integer i = match(object needle, sequence haystack, integer start=1, bool case_sensitive=true) -- or -- integer i = rmatch(object needle, sequence haystack, integer start=length(haystack), bool case_sensitive=true)
Description: | Try to match needle against some slice of haystack. If successful, return the element number of haystack where the (first) matching slice begins, at start or later (if specified), else return 0.
pwa/p2js: | Supported.
Notes: | The rmatch() routine is similar but works from the end of haystack, less length(needle), down to 1. By default match is case sensitive, so "the" will not match "THE", however this can be changed by supplying false (0) in the fourth parameter. In order to supply the fourth (positional) parameter, you must also supply the third - unlike Euphoria, which allows ",,1" syntax, that I have no plans to ever add. So, obviously, to alter `match(x,s)` to become case in-sensitive, it must become `match(x,s,1,true)`, and replace ",,true" with ",1,true". Alternatively use named parameters: `match("the",s,case_insensitive:=true)` however that is not supported by Euphoria. Note that the fourth parameter was changed from case_insensitive with default false to the slightly saner case_sensitive default true in 0.8.3 (it was done for p2js, albeit in the end unnecessarily). I could only find three uses: Edix\src\find.e, demo\pGUI\simple_notepad.exw, and websockets.e - the latter is not (yet) widely distributed, and all three were trivial to update. If needle is an atom (unlike Euphoria, which crashes) then match() and rmatch() behave as find() and rfind() respectively. (Aside: As far as I know, that change only ever benefitted one dubious use of match(), long since lost, then again I have never seen any downside, so there is equally not much point undoing it.) The match_from() routine, which predated optional parameters, is now deprecated (and never had case insensitivity). Simply use match() with the optional third parameter instead. Update: match_from() has now been permanently removed.
Auxillary Functions | bool res = begins(object sub_text, sequence full_text) While sub_text can be a string or character, as per examples below, and it may be easier to think of it in that way, there is nothing wrong with say `begins({{2,2}},factor_set)` where factor_set could be something like `{{2},{2,2},{2,2,1},{3,2}}`.
Example 1: |
    integer location = match("hi", "Phix") -- location is set to 2
    location = match("the", "the cat sat on the mat", 4)
    -- location is set to 16, not 1, because a start index of 4 was specified
    location = rmatch("the", "the dog ate the steak from the table.")
    -- location is set to 28 (3rd ’the’)
    location = rmatch("the", "the dog ate the steak from the table.", -11)
    -- location is set to 13 (2nd ’the’)
    ?begins("abc", "abcdef") -- 1 (true)
    ?begins("bcd", "abcdef") -- 0 (false)
    ?begins(’c’, "cat")      -- 1 (true)
Example 2: |
    line = line[1..match("--",line)-1]  -- remove comment
    -- A nifty clever clogs trick: if match returns 0 then line is unaltered,
    -- (ie line:=line[1..-1]), otherwise only the text before "--" is kept.
Example 3: | The following illustrates the correct use of the start parameter for match() and rmatch():
    string mm = "tatatatatat"
    integer tt = 1
    sequence mr = {"fwd"}
    while 1 do
        tt = match("tat",mm,tt)
        mr = append(mr,tt)
        if tt=0 then exit end if
    --  tt += 1
        tt += 3
    end while
    mr = append(mr,"rev")
    tt = length(mm)
    while 1 do
        tt = rmatch("tat",mm,tt)
        mr = append(mr,tt)
        if tt=0 then exit end if
    --  tt -= 1
        tt = max(tt-3,0)
    end while
    ?mr -- output:
        -- +/-1: {"fwd",1,3,5,7,9,0,"rev",9,7,5,3,1,0}
        -- +/-3: {"fwd",1,5,9,0,"rev",9,5,1,0}
Adjusting tt by +/-1 will find overlapping matches, +/-3 [ie length("tat")] non-overlapping ones.
Implementation: | See builtins\match.e (an autoinclude) for details of the actual implementation.
See Also: | find, compare, wildcard_match, match_replace