Clarify that the input strings must out-live the ICU objects in ucoleiter.h and usearch.h

Description

In the file: icu4c/source/i18n/unicode/ucoleitr.h

The example in the API docs "CollationElementIterator_Example" has a minor typo.

The variable str that is passed to the API ucol_openElements isn't actually defined; it should be the variable "s" instead.

Activity

Show:
Jeff Genovy
September 14, 2020, 6:15 PM
Jeff Genovy
July 22, 2020, 6:53 PM

From discussion in the ICU-TC call on 2020-07-22:

  • I’ll take this to fix the typo, and also modify the two headers to clarify the string needs to out-live the object. (Will re-title the ticket).

  • Feedback from Markus was to look for existing documentation (ex: breakiter) to use the same language in the comments for consistency with other APIs.

  • We may want another future ticket to look at other APIs and clarify when things are copied or if the input string is expected to persist for the lifetime of the ICU object.

Jeff Genovy
July 22, 2020, 5:21 PM

w.r.t. APIs that keep a reference to the original input string (or make a copy).

The comment/feedback from Markus on icu-core was that it depends on the API. For some it makes sense to make a copy, for others with long input strings, they may only keep a reference/pointer.
“Where an API keeps a reference, it should say so.“

I wonder if I could also use this ticket to add comments to usearch_* and ucol_* that they keep a reference to the input string (which might be quite large).

Fixed

Assignee

Jeff Genovy

Reporter

Jeff Genovy

Components

Reviewer

Markus Scherer

Priority

minor

Fix versions