% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/20-api-generics.R
\name{locate_by_predicate}
\alias{locate_by_predicate}
\title{Locate First Predicate Match}
\usage{
locate_by_predicate(
  t,
  predicate,
  monoid_name,
  accumulator = NULL,
  include_metadata = FALSE
)
}
\arguments{
\item{t}{A \code{flexseq} (or subclass).}

\item{predicate}{Function applied to accumulated monoid values.}

\item{monoid_name}{Name of the monoid used for scanning.}

\item{accumulator}{Optional starting accumulator value.}

\item{include_metadata}{Logical; include scan metadata.}
}
\value{
If \code{include_metadata = FALSE}, a list with:
\itemize{
\item \code{found}: logical flag.
\item \code{value}: matched element when found, otherwise \code{NULL}.
}

If \code{include_metadata = TRUE}, adds \code{metadata} with:
\itemize{
\item \code{left_measure}
\item \code{hit_measure}
\item \code{right_measure}
\item \code{index}
}
}
\description{
Scans accumulated monoid values and returns the first element where
\code{predicate} becomes \code{TRUE}, without rebuilding split trees.
}
\details{
This is the read-only analogue of \code{\link[=split_around_by_predicate]{split_around_by_predicate()}}.

As with split helpers, a common setup is a custom monoid created with
\code{\link[=measure_monoid]{measure_monoid()}} and attached via \code{\link[=add_monoids]{add_monoids()}}.

\code{value} is the matched leaf entry for the input structure:
\itemize{
\item \code{flexseq}: stored user element.
\item \code{ordered_sequence}: \code{list(value, key)}.
\item \code{priority_queue}: \code{list(value, priority)}.
\item \code{interval_index}: \code{list(value, start, end)}.
}
}
\examples{
x <- flexseq("a", "b", "c", "d")
size_monoid <- measure_monoid(`+`, 0L, function(e) 1L)
x2 <- add_monoids(x, list(size = size_monoid))

locate_by_predicate(x2, function(v) v >= 3L, "size")
locate_by_predicate(x2, function(v) v >= 3L, "size", include_metadata = TRUE)
}
