From e54e2b1a98abfdb75232a9b3218714ce34c9a34f Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sun, 17 Nov 2024 22:39:41 -0800
Subject: More url work.  Undocument rawurl, and stop using it stats and logs.

Also expose nng_url_sprintf() for users who need it.

This avoids some need to do dynamic memory on some things.  Soon
the entirety of nng_url will be allocation free in the usual case.
---
 docs/ref/api/url.md | 21 +++++++++++++++++++--
 docs/ref/xref.md    |  1 +
 2 files changed, 20 insertions(+), 2 deletions(-)

(limited to 'docs/ref')

diff --git a/docs/ref/api/url.md b/docs/ref/api/url.md
index 0928180e..a7fb6f35 100644
--- a/docs/ref/api/url.md
+++ b/docs/ref/api/url.md
@@ -12,7 +12,6 @@ that are not part of the IETF standards.
 
 ```c
 typedef struct nng_url {
-    char       *u_rawurl;
     const char *u_scheme;
     char       *u_userinfo;
     char       *u_host;
@@ -32,7 +31,6 @@ alter them, as the underlying memory is managed by the library.
 
 The fields of an `nng_url` object are as follows:
 
-- `u_rawurl`: The unparsed URL string. This will never be `NULL`.
 - `u_scheme`: The URL scheme, such as "http" or "inproc". Always lower case. This will never be `NULL`.
 - `u_userinfo`: This username and password if supplied in the URL string. Will be `NULL` when not present.
 - `u_host`: The full host part of the URL, including the port if present (separated by a colon.)
@@ -46,6 +44,25 @@ The fields of an `nng_url` object are as follows:
 > [!NOTE]
 > Other fields may also be present, but only those documented here are safe for application use.
 
+## Format a URL
+
+```c
+int nng_url_sprintf(char *buf, size_t bufsz, const nng_url *url);
+```
+
+The {{i:`nng_url_sprintf`}} function formats the _url_ to the _buf_,
+which must have `bufsz` bytes of free space associated with it.
+
+This function returns the number of bytes formatted to _buf_, excludng
+the terminating zero byte, or if _bufsz_ is too small, then it returns
+the number of bytes that would have been formatted if there was sufficient
+space. The semantics are similar to the `snprintf` function from C99.
+
+> [!TIP]
+> If _bufsz_ is 0, then _buf_ can be `NULL`, and the return value
+> can be used to determine the amount of space to allocate for a dynamically
+> sized buffer.
+
 ## Parse a URL
 
 ```c
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index b9b4c503..728628a4 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -30,6 +30,7 @@
 [`nng_url`]: /api/url.md#url-structure
 [`nng_url_parse`]: /api/url.md#parse-a-url
 [`nng_url_free`]: /api/url.md#destroy-a-url
+[`nng_url_sprintf`]: /api/url.md#format-a-url
 [`nng_socket_pair`]: /api/misc.md#create-socket-pair
 [`nng_random`]: /api/misc.md#get-random-number
 [`nng_version`]: /api/misc.md#report-library-version
-- 
cgit v1.2.3-70-g09d2