From simon.urbanek at r-project.org  Tue Mar 27 18:35:42 2012
From: simon.urbanek at r-project.org (Simon Urbanek)
Date: Tue, 27 Mar 2012 12:35:42 -0400
Subject: [Rd] .Call ref card
In-Reply-To: <862ADA50-3FE4-4727-9FCD-E7001796138B@r-project.org>
References: <mailman.29.1332414009.26932.r-devel@r-project.org>
	<4F6B2CE9.2090600@mayo.edu>
	<2933F897-6D3D-4DC0-AD38-2C73C8F01A4E@r-project.org>
	<87obror7jf.wl%rdiaz02@gmail.com>
	<928F07E9-B0AE-4E8A-839C-59A20CDA23C1@gmail.com>
	<4F6B652A.6050209@mayo.edu> <87fwczr4em.wl%rdiaz02@gmail.com>
	<EA95C1C3-6C6D-4DEB-81EC-A3D7BFF3EA21@r-project.org>
	<4F71E4E5.5070406@mayo.edu>
	<862ADA50-3FE4-4727-9FCD-E7001796138B@r-project.org>
Message-ID: <14940263-F8AA-4F48-9CB8-A9AA176BB583@r-project.org>

FWIW: I have put the (slightly updated) sheet at

http://r.research.att.com/man/R-API-cheat-sheet.pdf

Note that it is certainly incomplete - but that is intentional to a) to fit the space constraints and b) to show only the most basic things since we are talking about starting with .Call -- advanced users may need a different sheet but then they just go straight to the headers anyway ...

Cheers,
Simon




On Mar 27, 2012, at 12:20 PM, Simon Urbanek wrote:

> 
> On Mar 27, 2012, at 12:03 PM, Terry Therneau wrote:
> 
>> On 03/23/2012 10:58 AM, Simon Urbanek wrote:
>>> This is my shot at a cheat sheet.
>>> comments are welcome.
>>> 
>>> Simon
>>> 
>>> 
>> I was looking through the cheat sheet.  It's nice.  There are a few things in it that I can't find in the documentation though.  Where would one find a description?  (I can guess, but that may be dangerous).
>> 
>> mkNamed
> 
> It is a shorthand for using allocVector and then setting names (which can be tedious). It's a simple way to create a result list/object (a very common thing to do):
> 
>    SEXP res = PROTECT(mkNamed(VECSXP, (const char*[]) { "foo", "bar", ""}));
>    // fill res with SET_VECTOR_ELT(res, ..) 
>    setAttrib(res, R_ClassSymbol, mkString("myClass"));
>    UNPROTECT(1);
>    return res;
> 
> Note that the sentinel is "" (not not NULL as commonly used in other APIs). Also you don't specify the length because it is determined from the names.
> 
> 
>> R_Naint   (I don't see quite how this differs from using NA_INTEGER to set a result)
> 
> It doesn't really -- NA_INTEGER is defined to be R_NaInt. In theory NA_INTEGER being a macro could be a constant instead -- maybe for efficiency -- but currently it's not.
> 
> 
>> R_PreserveObject, R_ReleaseObject   (Advantages/disadvantages wrt PRESERVE?)
>> 
> 
> I guess you mean wrt PROTECT? Preserve/Release is used for objects that you want to be globally preserved - i.e. they will survive exit from the function. In contrast, the protection stack is popped when you exit the function (both by error or success).
> 
> Cheers,
> Simon
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> 
> 



[Rd] .Call ref card
Simon Urbanek