% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/30-api-flexseq-get-measure.R
\name{get_measure}
\alias{get_measure}
\title{Read a Cached Subtree Measure}
\usage{
get_measure(x, monoid_name)
}
\arguments{
\item{x}{A flexseq (or any immutables subclass).}

\item{monoid_name}{Name of an attached monoid (e.g. \code{.size}, a custom
name from \code{\link[=add_monoids]{add_monoids()}}, or a built-in like \code{.pq_min} /
\code{.oms_max_key}).}
}
\value{
The cached monoid value at the root of \code{x}. Shape depends on
the monoid — typically atomic (e.g. a numeric sum) but may be a list
for built-ins that carry auxiliary state.
}
\description{
Returns the monoid's accumulated measure across the whole (sub)tree at
the root of \code{x}. This is the cached value that internal operations use
for O(log n) locate and split.
}
\details{
On the full tree \code{x}, this is the aggregate over every element. After a
split — e.g. \code{s <- split_by_predicate(x, p, "sum")} — call
\code{get_measure(s$left, "sum")} to read the aggregate of just the left
side in O(1).

For per-element measures, see \code{\link[=get_measures]{get_measures()}}.
}
\examples{
sum_m <- measure_monoid(`+`, 0, function(el) el)
x <- add_monoids(as_flexseq(c(3, 1, 4, 1, 5, 9, 2, 6)),
                 list(sum = sum_m))
get_measure(x, "sum")         # total across the whole tree
get_measure(x, ".size")       # built-in: element count

q <- priority_queue("a", "b", "c", priorities = c(5, 1, 3))
get_measure(q, ".pq_min")     # built-in, list-valued
}
\seealso{
\code{\link[=get_measures]{get_measures()}}, \code{\link[=measure_monoid]{measure_monoid()}}, \code{\link[=add_monoids]{add_monoids()}}
}
