Searching

Functions
int32	strFind (strref s, int32 start, strref find)
int32	strFindi (strref s, int32 start, strref find)
int32	strFindR (strref s, int32 end, strref find)
int32	strFindRi (strref s, int32 end, strref find)
int32	strFindChar (strref s, int32 start, char find)
int32	strFindChari (strref s, int32 start, char find)
int32	strFindCharR (strref s, int32 end, char find)
int32	strFindCharRi (strref s, int32 end, char find)
int32	strFindAny (strref s, int32 start, strref chars)
int32	strFindAnyi (strref s, int32 start, strref chars)
int32	strFindAnyR (strref s, int32 end, strref chars)
int32	strFindAnyRi (strref s, int32 end, strref chars)
int32	strFindNotAny (strref s, int32 start, strref chars)
int32	strFindNotAnyi (strref s, int32 start, strref chars)
int32	strFindNotAnyR (strref s, int32 end, strref chars)
int32	strFindNotAnyRi (strref s, int32 end, strref chars)

Detailed Description

Functions for finding substrings within strings.

Case-insensitive searches are ASCII-only and do not properly handle multi-byte UTF-8 characters.

Function Documentation

strFind()

int32 strFind	(	strref	s,
		int32	start,
		strref	find
	)

Finds the first occurrence of a substring (forward search)

Searches for the first occurrence of the substring 'find' in string 's', starting at the specified position. The search proceeds forward toward the end of the string.

Negative start positions are relative to the end of the string, allowing searches from a position near the end. If the substring is not found, -1 is returned.

Parameters

s	String to search within
start	Starting position for search (negative = from end)
find	Substring to search for

Returns

Byte offset of first occurrence, or -1 if not found

Example:

int32 pos = strFind(s, 0, _SL("hello"));
if (pos >= 0) {
    // Found at position pos
}
 
// Search starting from position 10
pos = strFind(s, 10, _SL("world"));
 
// Search from 5 characters before the end
pos = strFind(s, -5, _SL("end"));

strFindAny()

int32 strFindAny	(	strref	s,
		int32	start,
		strref	chars
	)

Finds the first byte that is a member of a set (forward search)

Searches for the first byte in 's' that appears anywhere in 'chars', starting at the specified position. This is the string-scanning equivalent of C's strpbrk().

An empty or NULL character set never matches, so -1 is returned.

Note

This operates on bytes, not UTF-8 code points. A multi-byte character in the set is treated as its individual bytes, any one of which may match.

Parameters

s	String to search within
start	Starting position for search (negative = from end)
chars	Set of bytes to search for

Returns

Byte offset of first matching byte, or -1 if none found

Example:

// find the first whitespace byte
int32 pos = strFindAny(line, 0, _SL(" \t\r\n"));

strFindAnyi()

int32 strFindAnyi	(	strref	s,
		int32	start,
		strref	chars
	)

Finds the first byte that is a member of a set, ignoring case (forward search)

Case-insensitive version of strFindAny().

Parameters

s	String to search within
start	Starting position for search (negative = from end)
chars	Set of bytes to search for

Returns

Byte offset of first matching byte, or -1 if none found

Example:

int32 pos = strFindAnyi(s, 0, _SL("aeiou"));   // also matches AEIOU

strFindAnyR()

int32 strFindAnyR	(	strref	s,
		int32	end,
		strref	chars
	)

Finds the last byte that is a member of a set (reverse search)

Searches backward from the specified end position for a byte that appears anywhere in 'chars'. The end position follows the same rules as strFindR().

An empty or NULL character set never matches, so -1 is returned.

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
chars	Set of bytes to search for

Returns

Byte offset of last matching byte before end, or -1 if none found

Example:

// last path separator, either flavor
int32 pos = strFindAnyR(path, strEnd, _SL("/\\"));

strFindAnyRi()

int32 strFindAnyRi	(	strref	s,
		int32	end,
		strref	chars
	)

Finds the last byte that is a member of a set, ignoring case (reverse search)

Case-insensitive version of strFindAnyR().

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
chars	Set of bytes to search for

Returns

Byte offset of last matching byte before end, or -1 if none found

Example:

int32 pos = strFindAnyRi(s, strEnd, _SL("xyz"));

strFindChar()

int32 strFindChar	(	strref	s,
		int32	start,
		char	find
	)

Finds the first occurrence of a byte (forward search)

Searches for the first occurrence of the byte 'find' in string 's', starting at the specified position.

Note

This operates on bytes, not UTF-8 code points. Searching for a byte >= 0x80 can match a continuation byte in the middle of a multi-byte sequence.

Parameters

s	String to search within
start	Starting position for search (negative = from end)
find	Byte to search for

Returns

Byte offset of first occurrence, or -1 if not found

Example:

int32 pos = strFindChar(path, 0, '/');

strFindChari()

int32 strFindChari	(	strref	s,
		int32	start,
		char	find
	)

Finds the first occurrence of a byte, ignoring case (forward search)

Case-insensitive version of strFindChar().

Parameters

s	String to search within
start	Starting position for search (negative = from end)
find	Byte to search for

Returns

Byte offset of first occurrence, or -1 if not found

Example:

int32 pos = strFindChari(s, 0, 'q');   // matches 'q' or 'Q'

strFindCharR()

int32 strFindCharR	(	strref	s,
		int32	end,
		char	find
	)

Finds the last occurrence of a byte (reverse search)

Searches backward from the specified end position for the byte 'find'. The end position can be strEnd (search the whole string), a positive byte offset, or a negative offset from the end.

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
find	Byte to search for

Returns

Byte offset of last occurrence before end, or -1 if not found

Example:

int32 pos = strFindCharR(filename, strEnd, '.');

strFindCharRi()

int32 strFindCharRi	(	strref	s,
		int32	end,
		char	find
	)

Finds the last occurrence of a byte, ignoring case (reverse search)

Case-insensitive version of strFindCharR().

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
find	Byte to search for

Returns

Byte offset of last occurrence before end, or -1 if not found

Example:

int32 pos = strFindCharRi(s, strEnd, 'x');   // matches 'x' or 'X'

strFindi()

int32 strFindi	(	strref	s,
		int32	start,
		strref	find
	)

Finds the first occurrence of a substring, ignoring case (forward search)

Case-insensitive version of strFind().

Parameters

s	String to search within
start	Starting position for search (negative = from end)
find	Substring to search for

Returns

Byte offset of first occurrence, or -1 if not found

Example:

// Matches "utf-8", "UTF-8", "UTF-8" anywhere in the value
if (strFindi((strref)getenv("LANG"), 0, _SL("utf-8")) >= 0) {
    // Locale is UTF-8
}

strFindNotAny()

int32 strFindNotAny	(	strref	s,
		int32	start,
		strref	chars
	)

Finds the first byte that is NOT a member of a set (forward search)

Searches for the first byte in 's' that does not appear in 'chars', starting at the specified position. This is the string-scanning equivalent of C's strspn(), and is the primitive the trim functions are built on.

An empty or NULL character set excludes nothing, so the search position itself is returned (or -1 if it is already at the end of the string).

Parameters

s	String to search within
start	Starting position for search (negative = from end)
chars	Set of bytes to skip over

Returns

Byte offset of first non-matching byte, or -1 if all bytes are in the set

Example:

// offset of the first byte that isn't leading whitespace
int32 pos = strFindNotAny(line, 0, _SL(" \t"));

strFindNotAnyi()

int32 strFindNotAnyi	(	strref	s,
		int32	start,
		strref	chars
	)

Finds the first byte that is NOT a member of a set, ignoring case (forward search)

Like strFindNotAny(), but a set entry excludes both cases of that letter.

Parameters

s	String to search within
start	Starting position for search (negative = from end)
chars	Set of bytes to skip over

Returns

Byte offset of first non-matching byte, or -1 if all bytes are in the set

Example:

int32 pos = strFindNotAnyi(s, 0, _SL("abc"));   // also skips A, B, C

strFindNotAnyR()

int32 strFindNotAnyR	(	strref	s,
		int32	end,
		strref	chars
	)

Finds the last byte that is NOT a member of a set (reverse search)

Searches backward from the specified end position for a byte that does not appear in 'chars'. The end position follows the same rules as strFindR().

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
chars	Set of bytes to skip over

Returns

Byte offset of last non-matching byte before end, or -1 if all are in the set

Example:

// offset of the last byte that isn't trailing whitespace
int32 pos = strFindNotAnyR(line, strEnd, _SL(" \t\r\n"));

strFindNotAnyRi()

int32 strFindNotAnyRi	(	strref	s,
		int32	end,
		strref	chars
	)

Finds the last byte that is NOT a member of a set, ignoring case (reverse search)

Like strFindNotAnyR(), but a set entry excludes both cases of that letter.

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
chars	Set of bytes to skip over

Returns

Byte offset of last non-matching byte before end, or -1 if all are in the set

Example:

int32 pos = strFindNotAnyRi(s, strEnd, _SL("xyz"));

strFindR()

int32 strFindR	(	strref	s,
		int32	end,
		strref	find
	)

Finds the last occurrence of a substring (reverse search)

Searches for the last occurrence of the substring 'find' in string 's', searching backward from the specified end position. This is useful for finding the rightmost match or searching within a specific range.

The end position can be:

• strEnd: Search from the end of the string
• Positive: Search up to this byte offset
• Negative: Offset from the end of the string

If the substring is not found, -1 is returned.

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
find	Substring to search for

Returns

Byte offset of last occurrence before end, or -1 if not found

Example:

// Find last occurrence in entire string
int32 pos = strFindR(s, strEnd, _SL("."));
if (pos >= 0) {
    // Found last period at position pos
}
 
// Find last occurrence before position 50
pos = strFindR(s, 50, _SL("item"));
 
// Find last occurrence in last 20 characters
pos = strFindR(s, -20, _SL("suffix"));

strFindRi()

int32 strFindRi	(	strref	s,
		int32	end,
		strref	find
	)

Finds the last occurrence of a substring, ignoring case (reverse search)

Case-insensitive version of strFindR().

Parameters

s	String to search within
end	Ending position for search (strEnd = string end, negative = from end)
find	Substring to search for

Returns

Byte offset of last occurrence before end, or -1 if not found

Example:

// Find the last extension separator regardless of case
int32 pos = strFindRi(filename, strEnd, _SL(".TAR"));