R devel - Apr 2024 - Is ALTREP "non-API"?

>
>
>
> > > ALTREP is part of the official R api, as illustrated by the
presence of
> > > src/include/R_ext/Altrep.h. Everything declared in the header
files in
> that
> > > directory is official API AFAIK (and I believe that is more
definitive
> than
> > > the manuals).
> > >
> >
> > That is not true at all - the presence of header does not constitute
> declaration of something as the R API. There are cases where internal
> functions are in the headers for historical or other reasons since the
> headers are used both for the internal implementation and packages.
That's
> why this is in R-exts under "The R API: entry points for C code":
> >
> > If I understand your point correctly, does this mean that
> Rf_allocVector() is not part of the "official" R API? It does not
appear to
> be documented in the "The R API: entry points for C code"
section.
> >
>
> It does, obviously:
> https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1

I'm just trying to understand the precise definition of the official API
here. So it's any function mentioned in R-exts, regardless of which section
it appears in?

Does this sentence imply that all functions starting with alloc* are part
of the official API?
> For many purposes it is sufficient to allocate R objects and manipulate
those. There are quite a
> few allocXxx functions defined in Rinternals.h?you may want to explore
them.

Generally, things in a file with "internal" in its name are internal.

Hadley

-- 
http://hadley.nz

	[[alternative HTML version deleted]]

> On Apr 24, 2024, at 12:52 AM, Hadley Wickham <h.wickham at gmail.com>
wrote:
> 
>> 
>> 
>> 
>>>> ALTREP is part of the official R api, as illustrated by the
presence of
>>>> src/include/R_ext/Altrep.h. Everything declared in the header
files in
>> that
>>>> directory is official API AFAIK (and I believe that is more
definitive
>> than
>>>> the manuals).
>>>> 
>>> 
>>> That is not true at all - the presence of header does not
constitute
>> declaration of something as the R API. There are cases where internal
>> functions are in the headers for historical or other reasons since the
>> headers are used both for the internal implementation and packages.
That's
>> why this is in R-exts under "The R API: entry points for C
code":
>>> 
>>> If I understand your point correctly, does this mean that
>> Rf_allocVector() is not part of the "official" R API? It does
not appear to
>> be documented in the "The R API: entry points for C code"
section.
>>> 
>> 
>> It does, obviously:
>> https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1
> 
> 
> I'm just trying to understand the precise definition of the official
API
> here. So it's any function mentioned in R-exts, regardless of which
section
> it appears in?
> 
> Does this sentence imply that all functions starting with alloc* are part
> of the official API?
> 
Again, I can only quote the R-exts (few lines below the previous "The R
API" quote):


We can classify the entry points as
API
Entry points which are documented in this manual and declared in an installed
header file. These can be used in distributed packages and will only be changed
after deprecation.


It says "in this manual" - I don't see anywhere restriction on a
particular section of the manual, so I really don't see why you would think
that allocation is not part on the API.

Cheers,
Simon



>> For many purposes it is sufficient to allocate R objects and manipulate
> those. There are quite a
>> few allocXxx functions defined in Rinternals.h?you may want to explore
> them.
> 
> Generally, things in a file with "internal" in its name are
internal.
> 
> Hadley
> 
> -- 
> http://hadley.nz
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>