Added numElements() method and added examples

Author: wizard97

README.md

@@ -1,16 +1,18 @@
 # ArduinoRingBuffer
 
-This is a simple ring buffer library for the Arduino. It is written in vanilla C, and can easily be modified to work with other platforms simply be removing the `#include "Arduino.h" `.  
-
-
-I have heard about object orinted progrming in pure C, and I decided to give it a shot with this library. Using C structs and function pointers, one creates a RingBuf object that is complete with its own methods and attributes.
+This is a simple ring buffer library for the Arduino. It is written in vanilla C, and can easily be modified to work with other platforms simply be removing the `#include "Arduino.h" `.  It can buffer any fixed size object (ints, floats, structs, etc...).
 
 
+I have heard about object oriented programing in pure C, and I decided to give it a shot with this library. Using C structs and function pointers, the library creates RingBuf objects that are complete with their own methods and attributes. Note that every method (except constructor), takes a `RingBuf *self` pointer. This is the equivalent of the `this` pointer in C++, but the C++ compiler automatically passes it behind the scenes. For this library, you must manually pass this as the first argument.
 
 ## Use Cases
 
 A ring buffer is used when passing asynchronous io between two threads. In the case of the Arduino, it is very useful for buffering data in an interrupt routine that is later processed in your `void loop()`.
 
+## Examples
+
+Look at the examples folder for several examples.
+
 ## API
 
 
@@ -20,7 +22,7 @@ A ring buffer is used when passing asynchronous io between two threads. In the c
 RingBuf *RingBuf_new(int size, int len);
 ```
 
-Creates a new RingBuf object of len elements that are size bytes each. A poetinter to the new RingBuf object is returned on success. On failure (lack of memory), a null pointer is returned.
+Creates a new RingBuf object of len elements that are size bytes each. A pointer to the new RingBuf object is returned on success. On failure (lack of memory), a null pointer is returned.
 This would be the equivalent of `new RingBuf(int size, int len)` in C++.
 
 ### Deconstructor
@@ -58,6 +60,12 @@ void *pull(RingBuf *self, void *object);
 
 Pull the first element out of the buffer. The first element is copied into the location pointed to by object. Returns a NULL pointer if the buffer is empty, otherwise returns object.
 
+### numElements()
+```
+unsigned int numElements(RingBuf *self);
+```
+
+Returns number of elements in buffer.
 
 ### isFull()
 ```

RingBuf.c

@@ -1,6 +1,7 @@
 /*
-  RingBuf.c - Library for implementing a simple Ring Buffer on Arduino boards. 
-  Created by D. Aaron Wisner, December 10, 2015.
+  RingBuf.c - Library for implementing a simple Ring Buffer on Arduino boards.
+  Created by D. Aaron Wisner (daw268@cornell.edu)
+  January 17, 2015.
   Released into the public domain.
 */
 #include "RingBuf.h"
@@ -38,6 +39,7 @@ int RingBuf_init(RingBuf *self, int size, int len)
   self->isFull = &RingBufIsFull;
   self->isEmpty = &RingBufIsEmpty;
   self->add = &RingBufAdd;
+  self->numElements = &RingBufNumElements;
   self->peek = &RingBufPeek;
   self->pull = &RingBufPull;
   return 0;
@@ -117,6 +119,12 @@ void *RingBufPull(RingBuf *self, void *object)
   return object;
 }
 
+// Returns number of elemnts in buffer
+unsigned int RingBufNumElements(RingBuf *self)
+{
+  return self->elements;
+}
+
 // Returns true if buffer is full
 bool RingBufIsFull(RingBuf *self)
 {

RingBuf.h

@@ -1,6 +1,7 @@
 /*
-  RingBuf.h - Library for implementing a simple Ring Buffer on Arduino boards. 
-  Created by D. Aaron Wisner, December 10, 2015.
+  RingBuf.h - Library for implementing a simple Ring Buffer on Arduino boards.
+  Created by D. Aaron Wisner (daw268@cornell.edu)
+  January 17, 2015.
   Released into the public domain.
 */
 #ifndef RingBuf_h
@@ -27,6 +28,8 @@ typedef struct RingBuf
   bool (*isFull) (RingBuf*);
   // Returns true if empty
   bool (*isEmpty) (RingBuf*);
+  // Returns number of elemnts in buffer
+  unsigned int (*numElements)(RingBuf*);
   // Add Event, Returns index where added in buffer, -1 on full buffer
   int (*add) (RingBuf*, void*);
   // Returns pointer to nth element, NULL when nth element is empty
@@ -53,6 +56,7 @@ void *RingBufPeek(RingBuf *self, unsigned int num);
 void *RingBufPull(RingBuf *self, void *object);
 bool RingBufIsFull(RingBuf *self);
 bool RingBufIsEmpty(RingBuf *self);
+unsigned int RingBufNumElements(RingBuf *self);
 
 #ifdef __cplusplus
 }

examples/RingBufExample/RingBufExample.ino

@@ -0,0 +1,64 @@
+/*
+  RingBufExample.ino - A basic demo of adding a struct, then removing one
+  Created by D. Aaron Wisner (daw268@cornell.edu)
+  January 17, 2015.
+  Released into the public domain.
+*/
+
+#include <RingBuf.h>
+
+struct mystruct
+{
+  int index;
+  char randomstring[10];
+  unsigned int mycrap;
+  unsigned long long timestamp;
+};
+
+// Create a RinBuf object designed to hold a 20 of mystructs
+RingBuf *my_buf = RingBuf_new(sizeof(struct mystruct), 20);
+
+
+void setup() {
+  Serial.begin(9600);
+  // Check if null pointer
+  if (!my_buf)
+  {
+    Serial.println("Not enough memory");
+    while (1);
+  }
+
+  // Create element I want to add
+  struct mystruct bar, foo;
+
+  // Zero both of them out
+  memset(&bar, 0, sizeof(struct mystruct));
+  memset(&foo, 0, sizeof(struct mystruct));
+
+  bar.index = 1;
+  bar.timestamp = millis();
+
+  // Copy bar into the ring_buf
+  my_buf->add(my_buf, &bar);
+
+  // Pull first element out of buffer (should be same as bar) into foo
+  my_buf->pull(my_buf, &foo);
+
+  // Prove that foo is the same as bar
+  if (!memcmp(&bar, &foo, sizeof(struct mystruct)))
+  {
+    Serial.println("As expected, foo is a copy of bar");
+  }
+
+  // Delete RingBuf object
+  RingBuf_delete(my_buf);
+  my_buf = NULL;
+
+}
+
+
+
+void loop() {
+  // put your main code here, to run repeatedly:
+
+}

examples/RingBufInterruptsExample/RingBufInterruptsExample.ino

@@ -0,0 +1,118 @@
+/*
+  RingBufInterruptsExample.ino - Interrupt example, to demonstrate the power of a ring buffer with asynchronous io
+  Created by D. Aaron Wisner (daw268@cornell.edu)
+  January 17, 2015.
+  Released into the public domain.
+
+  Trigger an interrupt by toggling EVENT_PIN, this will push an Event struct into the buffer
+  Print the contents of the buffer by sending anything over Serial Monitor
+*/
+#include <RingBuf.h>
+
+// MUST BE AN INTTERUPT COMPATIBLE PIN
+#define EVENT_PIN 3
+
+struct Event
+{
+  int index;
+  unsigned char pinState;
+  unsigned long timestamp;
+};
+
+// Declare as volatile, since modofied in ISR
+volatile unsigned int index = 0;
+
+// Create a RinBuf object designed to hold a 20 Event structs
+RingBuf *buf = RingBuf_new(sizeof(struct Event), 20);
+
+
+void setup() {
+  Serial.begin(9600);
+
+  // Check if null pointer
+  if (!buf)
+  {
+    Serial.println("Not enough memory");
+    while (1);
+  }
+
+  // Attach the interrupt service routine
+  attachInterrupt(digitalPinToInterrupt(EVENT_PIN), isr_event, CHANGE);
+
+
+  Serial.println("Toggle the pin state of pin EVENT_PIN, to fire an interrupt");
+  Serial.println("Send anything over serial to dump the contents of the buffer");
+  Serial.println();
+}
+
+void loop() {
+  // Print the number of elements
+  Serial.print("There are: ");
+  Serial.print(buf->numElements(buf));
+  Serial.println(" elements in the ring buffer");
+
+  // Check if empty
+  if (buf->isEmpty(buf))
+  {
+    Serial.println("The ring buffer is currently empty");
+  }
+  else if (buf->isFull(buf))
+  {
+    Serial.println("The ring buffer is currently full");
+  }
+
+  // If any message sent through serial monitor, dump buffer
+  if (Serial.available() > 0)
+  {
+    // Print contents of buffer
+    print_buf_contents();
+
+    //empty serial buffer
+    while (Serial.read() > 0);
+  }
+
+  Serial.println();
+
+  delay(2000);
+}
+
+
+// This interrupt serve routine function is called whenever an interrupt fires on EVENT_PIN
+// An Event Struct will be appened to the buffer
+void isr_event()
+{
+  struct Event e;
+  e.index = index++;
+  e.pinState = digitalRead(EVENT_PIN);
+  e.timestamp = millis();
+  // Add it to the buffer
+  buf->add(buf, &e);
+}
+
+// Print the buffer's contents then empty it
+void print_buf_contents()
+{
+  struct Event e;
+
+  Serial.println("\n______Dumping contents of ring buffer_______");
+
+  // Keep looping until pull() returns NULL
+  while (buf->pull(buf, &e))
+  {
+    //
+    Serial.print("Event index: ");
+    Serial.println(e.index);
+
+    Serial.print("Pin state: ");
+    Serial.println(e.pinState);
+
+    Serial.print("Timestamp (ms): ");
+    Serial.println(e.timestamp);
+
+    Serial.println();
+  }
+
+  Serial.println("______Done dumping contents_______");
+
+}
+