Response to claude review

Author: hadley

vignettes/locale-sensitive.Rmd

@@ -16,55 +16,72 @@ knitr::opts_chunk$set(
 library(stringr)
 ```
 
-stringr provides a number of locale-sensitive functions, i.e. functions whose behaviour depends on your locale, of which your language is a very important part. stringr defaults to English, `locale = "en"`, but you can override by providing a different `locale` specified by a lower-case language abbreviation, optionally followed by an underscore (_) and an upper-case region identifier. For example, "en" is English, "en_GB" is British English, and "en_US" is American English. For a list of language codes see [Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) and to see which are supported in stringr, run `stringi::stri_locale_list()`.
+A locale is a set of parameters that define a user's language, region, and cultural preferences. It determines language-specific rules for text processing, including how to:
 
-There are three main types of function that vary based on locale:
+- Convert between uppercase and lowercase letters
+- Sort text alphabetically
+- Format dates, numbers, and currency
+- Handle character encoding and display
+
+In stringr, you can control the locale using the `locale` argument, which takes language codes like "en" (English), "tr" (Turkish), or "es_MX" (Mexican Spanish). In general, a locale is a lower-case language abbreviation, optionally followed by an underscore (_) and an upper-case region identifier. You can see which locales are supported in stringr by running run `stringi::stri_locale_list()`.
+
+This vignette describes locale-sensitive stringr functions, i.e. functions with a `locale` argument. These functions fall into two broad categories:
 
 1. Case conversion
 2. Sorting and ordering
-3. String comparison
 
 ## Case conversion
 
-Most languages that use the Latin alphabet (like English) have upper and lower case, but the rules for converting between the two aren't always the same. For example, Turkish has two forms of the letter "I", dotted and dotless:
+`str_to_lower()`, `str_to_upper()`, `str_to_title()`, and `str_to_sentence()` all change the case of their inputs. But while most languages that use the Latin alphabet (like English) have upper and lower case, the rules for converting between the two aren't always the same. For example, Turkish has two forms of the letter "I": as well as "i" and "I", Turkish also has "ı", the dotless lowercase i, and "İ" is the dotted uppercase I. This means the rules for coverting i to upper case and I to lower case are different from English:
 
 ```{r}
-str_to_upper(c("i", "ı"))
-str_to_upper(c("i", "ı"), locale = "tr")
+# English
+str_to_upper("i")
+str_to_lower("I")
 
-str_to_lower(c("İ", "I"), locale = "tr")
+# Turkish
+str_to_upper("i", locale = "tr")
+str_to_lower("I", locale = "tr")
 ```
 
-Another example is Dutch, where "ij" is a digraph treated as a single letter. This means that `string_to_title()` will incorrectly capitalize it unless you use a Dutch locale:
+Another example is Dutch, where "ij" is a digraph treated as a single letter. This means that `str_to_sentence()` will incorrectly capitalize "ij" at the start of a sentence unless you use a Dutch locale:
 
 ```{r}
 #| warning: false
-dutch_words <- c("ijsvrij yoghurt", "ijmuiden", "bij elkaar")
+dutch_sentence <- "ijsland is een prachtig land in Noord-Europa."
 
-str_to_title(dutch_words)
-str_to_title(dutch_words, locale = "nl")
+# Incorrect
+str_to_sentence(dutch_sentence)
+# Correct
+str_to_sentence(dutch_sentence, locale = "nl")
 ```
 
-(Note that `str_to_title()` handles character-level locale differences but it doesn't implement locale-specific rules about which words not to capitalize. Fortunately, title case appears to be concept that applies primarily to English.)
-
-Case-sensitive string comparison also comes up in `str_equal()`/`str_unique()` and in pattern matching functions. To take advantage of locale-specific case matching, supply `locale` to `str_equal()`/`str_unique()` and use `coll()` instead of `fixed()` in pattern matching functions.
+Case conversion also comes up in another situation: case-insensitive comparison. Case-insensitive comparison comes up in two places. Firstly, `str_equal()` and `str_unique()` can optionally ignore case, so it's important to also supply locale when working with non-English text. For example, imagine we're searching for a Turkish name, ignoring case:
 
 ```{r}
 turkish_names <- c("İpek", "Işık", "İbrahim")
 search_name <- "ipek"
 
 # incorrect
 str_equal(turkish_names, search_name, ignore_case = TRUE)
-str_detect(turkish_names, fixed(search_name, ignore_case = TRUE))
 
 # correct
 str_equal(turkish_names, search_name, ignore_case = TRUE, locale = "tr")
+```
+
+Case conversion also comes up in pattern matching functions like `str_detect()`. You might be accustomed to use `ignore_case = TRUE` with `regex()` or `fixed()`, but if you want to use locale-sensitive comparison you instead need to use `coll()`:
+
+```{r}
+# incorrect
+str_detect(turkish_names, fixed(search_name, ignore_case = TRUE))
+
+# correct
 str_detect(turkish_names, coll(search_name, ignore_case = TRUE, locale = "tr"))
 ```
 
 ## Sorting and ordering
 
-Alphabetical order can vary dramatically across languages. For example, Lithuanian places 'y' between 'i' and 'k' and Czech treats "ch" as a single compound letter that sorts after all other 'h' words. 
+`str_sort()`, `str_order()`, and `str_rank()` all rely on the alphabetical ordering of letters. But not every language uses the same ordering as English. For example, Lithuanian places 'y' between 'i' and 'k' and Czech treats "ch" as a single compound letter that sorts after all other 'h' words. That means that if you want to correctly sort words in these languages you must provide the correct locale:
 
 ```{r}
 czech_words <- c("had", "chata", "hrad", "chůze")
@@ -78,26 +95,3 @@ str_sort(lithuanian_words)
 str_sort(czech_words, locale = "cs")
 str_sort(lithuanian_words, locale = "lt")
 ```
-
-## String comparison
-
-Letters that appear the same can have different Unicode representations:
-
-```{r}
-name1 <- "José"       # precomposed é (single character)
-name2 <- "Jose\u0301" # e + combining acute accent (two characters)
-str_view(c(name1, name2))
-```
-
-They look identical but `==` says they are different:
-
-```{r}
-name1 == name2
-```
-
-Fortunately, stringr's comparison functions correctly handle these differences:
-
-```{r}
-str_equal(name1, name2)
-str_unique(c(name1, name2))
-```