perlapi: Document SvPV_shrink_to_cur

1 files changed, 13 insertions, 0 deletions

diff --git a/sv.h b/sv.h
index 46769c5ad3..442d555a16 100644
--- a/sv.h
+++ b/sv.h
@@ -1490,6 +1490,19 @@ why not just use C<SvGROW> if you're not sure about the provenance?
                                 (char*)saferealloc((Malloc_t)SvPVX(sv), \
                                                    (MEM_SIZE)((n)))));  \
                  } STMT_END
+/*
+=for apidoc Am|void|SvPV_shrink_to_cur|SV* sv
+
+Trim any trailing unused memory in the PV of C<sv>, which needs to have a real
+C<PV> that is unencombered by things like COW.  Think first before using this
+functionality.  Is the space saving really worth giving up COW?  Will the
+needed size of C<sv> stay the same?
+
+If the answers are both yes, then use C<SV_CHECK_THINKFIRST> or
+C<SV_CHECK_THINKFIRST_COW_DROP> before calling this.
+
+=cut
+*/
 
 #define SvPV_shrink_to_cur(sv) STMT_START { \
                    const STRLEN _lEnGtH = SvCUR(sv) + 1; \