MiniRobotLanguage (MRL)
STR.Count
Counts Occurrences of a Substring or Characters in a String
Intention
This command is used to count the number of non-overlapping occurrences of a specified substring or set of characters (P2) within a source string (P1). The search is case-sensitive, so "Abc" will not match "abc".
It scans the source string from left to right using INSTR, advancing the start position by the length of P2 after each match to avoid overlaps. The result is a numeric count pushed to the Top of Stack (TOS) if no result variable is specified, or stored in an optional variable (P3).
If the match string is not present in the source string, or if it's empty, zero is returned. This is useful for tasks like frequency analysis, validating string patterns, or processing text data in automation scripts.
Schematic (Non-Overlapping Count)
Source: "abcabcabc"
Match: "abc"
Search: --> |a|b|c|a|b|c|a|b|c|
^ ^ ^ (Matches at 1,4,7 --> Count: 3)
For "aa" in "aaa": Matches at 1, then skips to 3 (no match) --> Count: 1 (non-overlapping)
Syntax
STR.Count|P1|P2[|P3]
Parameter Explanation
•P1 - (Source String) The main string in which to count occurrences. Can be a variable (e.g., $$SRC) or literal.
•P2 - (Match String) The substring or characters to count (case-sensitive, non-overlapping).
•P3 - (Optional Result Variable) Variable to store the count. If omitted, result is pushed to TOS.
Examples
' Basic substring count (from original sample)
$$SRC=abcabcabc
$$MAT=abc
STR.Count|$$SRC|$$MAT|$$CNT
MBX.$$CNT = 3 (non-overlapping matches)
' Count single character
$$SRC=Mississippi
STR.Count|$$SRC|i
POP.$$TOS
MBX.$$TOS = 4 (counts 'i' occurrences)
' Case sensitivity: No match due to case
$$SRC=ABCABCABC
$$MAT=abc
STR.Count|$$SRC|$$MAT|$$CNT
MBX.$$CNT = 0 (case mismatch)
' Non-overlapping with potential overlap
$$SRC=aaaa
$$MAT=aa
STR.Count|$$SRC|$$MAT|$$CNT
MBX.$$CNT = 2 (matches at 1-2 and 3-4, non-overlapping)
ENR.
'--------------------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.Count (Case-Sensitive Substring Count)
' Purpose: Verify all features using IVV. for automated checks
' and a final summary report. Tests basic counts, case-sens, non-overlap,
' no match, edge cases (empty, long match, single char, result to TOS/var).
' =================================================================
' --- Initialize Pass/Fail counters ---
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. BASIC SUBSTRING COUNT TEST
PRT. ===================================================
$$SRC=abcabcabc
$$MAT=abc
PRT. Test 1.1: Basic count (to var)...
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=3
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. Test 1.2: Basic count (to TOS)...
STR.Count|$$SRC|$$MAT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=3
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 2. CASE SENSITIVITY TEST
PRT. ===================================================
$$SRC=ABCABCABC
$$MAT=abc
PRT. Test 2.1: Case mismatch (no match)...
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=0
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
$$MAT=ABC
PRT. Test 2.2: Exact case match...
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=3
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 3. NON-OVERLAPPING TEST
PRT. ===================================================
$$SRC=aaaa
$$MAT=aa
PRT. Test 3.1: Non-overlapping count...
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=2
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 4. SINGLE CHARACTER COUNT TEST
PRT. ===================================================
$$SRC=Mississippi
$$MAT=i
PRT. Test 4.1: Count single char...
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=4
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 5. NO MATCH TEST
PRT. ===================================================
$$SRC=Hello World
$$MAT=Zebra
PRT. Test 5.1: No match...
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=0
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 6. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 6.1: Empty source string...
$$SRC=
$$MAT=hello
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=0
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 6.2: Empty match string...
$$SRC=Hello World
$$MAT=
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=0
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 6.3: Match longer than source...
$$SRC=Hi
$$MAT=ThisIsLong
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=0
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 6.4: Source with special chars...
$$SRC=Hello, World!
$$MAT=,
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=1
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 6.5: Multiple identical occurrences...
$$SRC=aaa
$$MAT=a
STR.Count|$$SRC|$$MAT|$$CNT
$$EXP=3
IVV.$$CNT=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. TEST SUMMARY
PRT. ===================================================
CAL.$$TOT=$$PAS+$$FAI
$$MSG=Total Tests: $$TOT
PRT.$$MSG
$$MSG=Passed: $$PAS
PRT.$$MSG
$$MSG=Failed: $$FAI
PRT.$$MSG
' --- Display final result message box ---
IVV.$$FAI=0
MBX.SUCCESS: All tests passed!|Test Result|64
ELS.
$$MSG=FAILURE: $$FAI of $$TOT tests failed.
MBX.$$MSG|Test Result|16
EIF.
ENR.
Remarks
-The count is case-sensitive and non-overlapping (search resumes after each match's end).
-If P2 is empty, returns 0 (no valid match).
-If P2 longer than P1, returns 0.
-Result is numeric (long integer type); use GVT. to check type if needed.
-For case-insensitive counting, use VTU. or VTL. on strings before calling, or a custom macro.
-Overlaps are not counted; for overlapping counts, use a loop with STR.Find.
Limitations
-Case-sensitive only; no built-in insensitive flag.
-Non-overlapping counts; does not handle overlapping substrings (e.g., "aa" in "aaa" counts 1).
-Limited to single substring; for multiple different substrings, chain calls or use macros.
See also: