nim-wiki/Nimrod-for-C-programmers.md

(Work in progress)

This is a guide for people with experience in C or a similar language. The guide assumes knowledge of how stacks and heaps works. 

The general tutorials can be found here:  
http://nimrod-lang.org/tut1.html  
http://nimrod-lang.org/tut2.html

The manual provides a more or less complete overview of the language:
http://nimrod-lang.org/manual.html  

### At a glance

<table>
<tr><th>Feature</th><th>C</th><th>Nimrod</th></tr>
<tr><td>Memory Management</td><td>Manual (GC w/ libraries or obj-C)</td><td>Garbage-collected and manual</td></tr>
<tr><td>Types</td><td>Static</td><td>Static</td></tr>
<tr><td>Compilation</td><td>Machine code</td><td>Machine code via C <br>(other backends in progress/planned)</td></tr>
<tr><td>Meta-programming</td><td>C Preprocessor</td><td>Nimrod (const/when/template/macro)</td></tr>
<tr><td>Type inference</td><td>No (some w/ C++11)</td><td>Yes (extensive support)</td></tr>
<tr><td>Closures</td><td>No (Yes w/ obj-C or C++11)</td><td>Yes</td></tr>
<tr><td>Operator Overloading</td><td>No (Yes w/ C++)</td><td>Yes</td></tr>
<tr><td>Custom Operators</td><td>No</td><td>Yes</td></tr>
</table>

### Arrays

In C an array is more or less syntactic sugar for pointers. In Nimrod, arrays are much more strict and safe to use. They are pass-by-value (meaning they're copied at assignment). When passing an array to a proc in Nimrod, the argument is a read-only reference, meaning it can't be assigned to. Take the following example:

**C:**
```C
void foobar(int z[4]) {
	z[5] = 5;
	printf("%d\n",z[5]);
}
int main() {
	int x[4] = {1, 2, 3, 4};
	foobar(x);
	printf("%d\n", x[1]);
	return 0;
}
```

**Nimrod:**
```Nimrod
proc foobar(z: array[0..3, int]) = 
  z[5] = 5  # Error: Cannot assign to z
  echo z[5] # Error: Index out of bounds.

var x = [1, 2, 3, 4]

foobar(x)
```

The C-code will compile, it may or may not crash. The Nimrod code will not compile. If you mean to change the array that was passed to the procedure, you can change the the signature of the procedure to ```proc foobar(z: var array[0..3, int])```. Now you will only get index out of bounds error. If you change the index in both lines to 1, the code will compile. If the index is a variable, Nimrod will include run-time checks on the bounds of the array.

In C, you can pass an ``int[3]`` to the foobar function, and the compiler will not complain. In this case Nimrod would not compile. You can use an openarray to accept an array of any size, and you can use low(z) and high(z) to query the bounds of the array.

Nimrod arrays can also be indexed from any number. That is, ``z: array[1..4, int]`` is an array of int indexed from 1 to 4. Trying to access ``z[0]`` would throw an index out bounds error.

In C, there's nothing that keeps you from keeping a pointer to a stack-allocated array

### Structs - Tuples and Objects

Tuples and Objects in Nimrod are kind of like structs in C, but not really.

### Interfacing C and Nimrod

See [Foreign Function Interface](http://nimrod-lang.org/manual.html#foreign-function-interface)

### Converting C code to Nimrod

See [c2nim](http://nimrod-lang.org/c2nim.html)

### Cheat Sheet
Note: Code examples are not exactly one-to-one, there may be subtle differences in the semantics. See comments.
<table>
  <tr>
    <th>C</th><th>Nimrod</th><th>Comment</th>
  </tr>


  <tr>
<td>
```C
int x;
int y = 2;
```
</td>
<td>
```Nimrod
var x : int
var y1 : int = 2
var y2 = 2
let z = 2
```
</td>
<td><b>Define variable</b>. y2 uses type inference. z is single-assignment. In nimrod, uninitialized variables is initialized to 0/nil or similar defaults.</i>
</td>
  </tr>

  <tr>
<td>
```C
char* s = "Hello World.";
char s0 = s[0]; // 'H'
char *t = s; // Pointer to s
s[11] = '!';
// s and t are both "Hello World."
```
</td>
<td>
```Nimrod
var s: string = "Hello World."
var s0: char = s[0] # 'H'
var t = s # Copy of s
s[11] = '!'
# s is "Hello World!", t is "Hello World."
```
</td>
<td><b>Strings and char</b>. Strings are pass-by-value (copied on assignment) and strictly bounds-checked on access.</i>
</td>
  </tr>

  <tr>
<td>
```C
9 % 8  // 1
-9 % 8 // -1
(unsigned)(-9) % (unsigned)(8) // 7
```
</td>
<td>
```Nimrod
9 mod 8  # 1
-9 mod 8 # -1
-9 %% 8  # 7
```
</td>
<td><b>Modulo operator</b>. <i>%% treats its argument as unsigned numbers. <a href="http://nimrod-lang.org/manual.html#pre-defined-integer-types">See</a></i></i>
</td>
  </tr>


  <tr>
<td>
```C
int x = foobar() ? 42 : 0;
```
</td>
<td>
```Nimrod
var x = if foobar(): 42 else: 0
```
</td>
<td>
<i>If-statements return the value of the expression they evaluate to, so Nimrod doesn't need a </i><b>ternary operator</b>.</i>
</td>
  </tr>


  <tr>
<td>
```C
void foo() {
  printf("Hello World\n");
}
int bar() {
  return 2;
}
int baz(int x) {
  return x*2;
}
```
</td>
<td>
```Nimrod
proc foo() =
  echo "Hello World"

proc bar() : int =
  2

proc baz(x : int) =
  x*2
```
</td>
<td><b>Function/Procedure.</b>  </td>
  </tr>

  <tr>
<td>
```C
void foobar(person_t *a) {
  person_t b;
  b = *a;
  b.name = "Bob";
  *a = b;
}
```
</td>
<td>
```Nimrod
proc foobar(a: ref TPerson) =
  var b: TPerson
  b = a[]
  b.name = "Bob"
  a[] = b
```
</td>
<td><b>Dereference.</b> <i>In C, only the pointer to the strings in the struct is copied. In Nimrod, the string is also copied, but refs are not deep-copied.</i> </td>
  </tr>


</table>