From c39435aea0586112bbbc0e7fc01e6c88ecce24f1 Mon Sep 17 00:00:00 2001 From: t-kalinowski Date: Thu, 22 Aug 2024 17:27:34 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20rstudio/?= =?UTF-8?q?reticulate@588ff0910ef4164fca0d02e9bc5e173df77357ba=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- dev/news/index.html | 2 + dev/pkgdown.yml | 2 +- .../as.character.python.builtin.bytes.html | 42 +++++++++++++++++-- .../as.raw.python.builtin.bytes.html | 8 ++++ dev/reference/index.html | 4 +- dev/reference/py_str.html | 4 ++ 6 files changed, 55 insertions(+), 7 deletions(-) create mode 100644 dev/reference/as.raw.python.builtin.bytes.html diff --git a/dev/news/index.html b/dev/news/index.html index 57b4e47e..15ffeb2f 100644 --- a/dev/news/index.html +++ b/dev/news/index.html @@ -88,6 +88,8 @@

#1628)

  • conda_run2() is now exported (#1637, contributed by @dramanica)

  • Fixes for CRAN check failures (#1645)

    • +

  • New as.raw() method for python.builtin.bytes (#1649, #1652)

    • +

  • as.character() method for python.builtin.bytes gains a nul argument, allowing for convenient handling of embedded NULs in the string. (#1652)

    • reticulate 1.38.02024-06-19

    diff --git a/dev/pkgdown.yml b/dev/pkgdown.yml index f20ad1cf..cc6c772f 100644 --- a/dev/pkgdown.yml +++ b/dev/pkgdown.yml @@ -11,7 +11,7 @@ articles: r_markdown: r_markdown.html rstudio_ide: rstudio_ide.html versions: versions.html -last_built: 2024-08-22T15:24Z +last_built: 2024-08-22T17:26Z urls: reference: https://rstudio.github.io/reticulate/reference article: https://rstudio.github.io/reticulate/articles diff --git a/dev/reference/as.character.python.builtin.bytes.html b/dev/reference/as.character.python.builtin.bytes.html index 9e4f65fe..33b07508 100644 --- a/dev/reference/as.character.python.builtin.bytes.html +++ b/dev/reference/as.character.python.builtin.bytes.html @@ -1,5 +1,5 @@ -Convert Python bytes to an R character vector — as.character.python.builtin.bytes • reticulateConvert Python bytes to an R character or raw vector — as.character.python.builtin.bytes • reticulate @@ -77,18 +77,27 @@
    -

    Convert Python bytes to an R character vector

    +

    Convert Python bytes to an R character or raw vector

    Source: R/python.R
    -

    Convert Python bytes to an R character vector

    +

    Convert Python bytes to an R character or raw vector

    # S3 method for class 'python.builtin.bytes'
-as.character(x, encoding = "utf-8", errors = "strict", ...)
    +as.character( + x, + encoding = "utf-8", + errors = "strict", + nul = stop("Embedded NUL in string."), + ... +) + +# S3 method for class 'python.builtin.bytes' +as.raw(x)
    @@ -108,11 +117,36 @@

    Arguments

    which raises an error. Other possible values are 'ignore' and 'replace'.

    +
    nul
    +

    Action to take if the bytes contain an embedded NUL (\x00). +Python allows embedded NULs in strings, while R does not. There are four +options for handling embedded NULs:

    1. Error: This is the default

      2. +

    2. Replace: Supply a replacement string: nul = "<NUL>"

      3. +

    3. Remove: Supply an empty string: nul = ""

      4. +

    4. Split: Supply an R NULL to indicate that string should be split at embedded NUL bytes: nul = NULL

      5. +
    + +
    ...

    further arguments passed to or from other methods.

    +
    +

    Examples

    + 
    if (FALSE) { # reticulate::py_available()
+# A bytes object with embedded NULLs
+b <- import_builtins(convert = FALSE)$bytes(
+  as.raw(c(0x61, 0x20, 0x62, 0x00, 0x63, 0x20, 0x64)) # "a b<NUL>c d"
+)
+
+try(as.character(b))            # Error : Embedded NUL in string.
+as.character(b, nul = "<NUL>")  # Replace: "a b<NUL>c d"
+as.character(b, nul = "")       # Remove: "a bc d"
+as.character(b, nul = NULL)     # Split: "a b" "c d"
+}
+
    +
    +
    +

    See also

    +

    as.character.python.builtin.bytes() For discussion on dealing with embedded NULs in Python strings.

    +