From f869c2f69cf183d4093883df968b6177e8e649a5 Mon Sep 17 00:00:00 2001 From: TEC Date: Mon, 29 Apr 2024 23:33:23 +0800 Subject: [PATCH] Document the semantics of annotation ordering It's important to specify the way that annotations relate to the characters of the underlying string and each other. --- base/strings/annotated.jl | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/base/strings/annotated.jl b/base/strings/annotated.jl index c8113cfa229ce..a44c0eb58e0cd 100644 --- a/base/strings/annotated.jl +++ b/base/strings/annotated.jl @@ -25,6 +25,17 @@ and a value (`Any`), paired together as a `Pair{Symbol, <:Any}`. Labels do not need to be unique, the same region can hold multiple annotations with the same label. +Code written for `AnnotatedString`s in general should conserve the following +properties: +- Which characters an annotation is applied to +- The order in which annotations are applied to each character + +Additional semantics may be introduced by specific uses of `AnnotatedString`s. + +A corollary of these rules is that adjacent, consecutively placed, annotations +with identical labels and values are equivalent to a single annotation spanning +the combined range. + See also [`AnnotatedChar`](@ref), [`annotatedstring`](@ref), [`annotations`](@ref), and [`annotate!`](@ref). @@ -301,6 +312,9 @@ end Annotate a `range` of `str` (or the entire string) with a labeled value (`label` => `value`). To remove existing `label` annotations, use a value of `nothing`. + +The order in which annotations are applied to `str` is semantically meaningful, +as described in [`AnnotatedString`](@ref). """ annotate!(s::AnnotatedString, range::UnitRange{Int}, @nospecialize(labelval::Pair{Symbol, <:Any})) = (_annotate!(s.annotations, range, labelval); s) @@ -333,6 +347,9 @@ annotations that overlap with `position` will be returned. Annotations are provided together with the regions they apply to, in the form of a vector of region–annotation tuples. +In accordance with the semantics documented in [`AnnotatedString`](@ref), the +order of annotations returned matches the order in which they were applied. + See also: `annotate!`. """ annotations(s::AnnotatedString) = s.annotations