add scm_c_nvalues with docs; also, docs for scm_c_values

* libguile/values.h:
* libguile/values.c (scm_c_nvalues): New function.

* doc/ref/api-control.texi (Multiple Values): Add docs for scm_c_values
  and scm_c_nvalues.

Fixes http://bugs.gnu.org/11764.

3 files changed, 30 insertions, 5 deletions

diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index ca7ad4af6..95c4925a9 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -838,12 +838,27 @@ the current implementation that object shares structure with
 @var{args}, so @var{args} should not be modified subsequently.
 @end deffn
 
-@deffn {C Function} scm_c_value_ref (values, idx)
+@deftypefn {C Function} SCM scm_c_values (SCM *base, size_t n)
+@code{scm_c_values} is an alternative to @code{scm_values}.  It creates
+a new values object, and copies into it the @var{n} values starting from
+@var{base}.
+
+Currently this creates a list and passes it to @code{scm_values}, but we
+expect that in the future we will be able to use more a efficient
+representation.
+@end deftypefn
+
+@deftypefn {C Function} size_t scm_c_nvalues (SCM obj)
+If @var{obj} is a multiple-values object, returns the number of values
+it contains.  Otherwise returns 1.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_c_value_ref (SCM obj, size_t idx)
 Returns the value at the position specified by @var{idx} in
-@var{values}.  Note that @var{values} will ordinarily be a
+@var{obj}.  Note that @var{obj} will ordinarily be a
 multiple-values object, but it need not be.  Any other object
 represents a single value (itself), and is handled appropriately.
-@end deffn
+@end deftypefn
 
 @rnindex call-with-values
 @deffn {Scheme Procedure} call-with-values producer consumer
diff --git a/libguile/values.c b/libguile/values.c
index ff56230fb..98a9df1c3 100644
--- a/libguile/values.c
+++ b/libguile/values.c
@@ -67,6 +67,15 @@ print_values (SCM obj, SCM pwps)
   return SCM_UNSPECIFIED;
 }
 
+size_t
+scm_c_nvalues (SCM obj)
+{
+  if (SCM_LIKELY (SCM_VALUESP (obj)))
+    return scm_ilength (scm_struct_ref (obj, SCM_INUM0));
+  else
+    return 1;
+}
+
 SCM
 scm_c_value_ref (SCM obj, size_t idx)
 {
diff --git a/libguile/values.h b/libguile/values.h
index f11c9d9de..3dbd0b742 100644
--- a/libguile/values.h
+++ b/libguile/values.h
@@ -33,8 +33,9 @@ SCM_API SCM scm_values_vtable;
 SCM_INTERNAL void scm_i_extract_values_2 (SCM obj, SCM *p1, SCM *p2);
 
 SCM_API SCM scm_values (SCM args);
-SCM_API SCM scm_c_values (SCM *base, size_t nvalues);
-SCM_API SCM scm_c_value_ref (SCM values, size_t idx);
+SCM_API SCM scm_c_values (SCM *base, size_t n);
+SCM_API size_t scm_c_nvalues (SCM obj);
+SCM_API SCM scm_c_value_ref (SCM obj, size_t idx);
 SCM_INTERNAL void scm_init_values (void);
 
 #endif  /* SCM_VALUES_H */