Merge pull request #7 from nRo/develop

Develop

Author: nRo

README.md

@@ -52,16 +52,28 @@ To build the library from sources:
     <dependency>
         <groupId>de.unknownreality</groupId>
         <artifactId>dataframe</artifactId>
-        <version>0.7.2-SNAPSHOT</version>
+        <version>0.7.5-SNAPSHOT</version>
     </dependency>
 ...
 </dependencies>
 ```
+Version 0.7.5
+-----
+-  **direct value access for DataRow object.**
+
+   DataRows now directly access the respective values from the columns.  
+   This improves runtime and memory footprint for most DataFrame operations.
+   DataRow objects are invalidated once the source DataFrame is changed.  
+   Accessing an invalidated row results in an exception
+- Row collections are now return as DataRows object.  
+    DataRows can be converted to a new DataFrame
+- improved 'groupBy' method
+
 
 Version 0.7
 -----
 - The read and write functions have been rewritten from scratch for this version.
-Some existing methods have beed removed.
+Some existing methods have been removed.
 
 - Data grouping has been refactored and aggregation functions can now be applied to data groupings.
 In general, data groupings can now be used like normal DataFrames.
@@ -70,6 +82,67 @@ In general, data groupings can now be used like normal DataFrames.
 
 - Empty DataFrame instances are now created using DataFrame.create()
 
+Examples
+-----
+Select all users called Meier or Schmitt from Germany, group by age and add column that contains the number of users with the respective age.
+Then sort by age and print
+```java
+URL csvUrl = new URL("https://raw.githubusercontent.com/nRo/DataFrame/master/src/test/resources/users.csv");
+
+DataFrame users = DataFrame.load(csvUrl, FileFormat.CSV);
+
+users.select("(name == 'Schmitt' || name == 'Meier') && country == 'Germany'")
+        .groupBy("age").agg("count",Aggregate.count())
+        .sort("age")
+        .print();
+
+/*
+    age count
+    20   1
+    24   2
+    30   2
+ */
+
+```
+Load a csv file, set a unique column as primary key and add an index for two other columns.
+Select rows using the previously created index, change the values in their NAME column and join them with the original DataFrame.
+```java
+URL csvUrl = new URL("https://raw.githubusercontent.com/nRo/DataFrame/master/src/test/resources/data_index.csv");
+
+DataFrame dataFrame = DataFrame.load(csvUrl, FileFormat.CSV);
+
+dataFrame.setPrimaryKey("UID");
+dataFrame.addIndex("id_name_idx","ID","NAME");
+
+DataRow row = dataFrame.selectByPrimaryKey(1);
+System.out.println(row);
+//1;A;1
+
+DataFrame idxExample = dataFrame.selectByIndex("id_name_idx",3,"A");
+
+idxExample.print();
+/*
+    ID	NAME	UID
+    3	A	4
+    3	A	8
+ */
+idxExample.getStringColumn("NAME").map((value -> value + "_idx_example"));
+idxExample.print();
+/*
+    ID	NAME	UID
+    3	A_idx_example	4
+    3	A_idx_example	8
+ */
+
+dataFrame.joinInner(idxExample,"UID").print();
+/*
+    ID.A    NAME.A	UID	ID.B	NAME.B
+    3   A   4	3   A_idx_example
+    3   A   8	3   A_idx_example
+ */
+
+```
+
 Usage
 -----
 Load DataFrame from a CSV file.
@@ -123,20 +196,74 @@ File file = new File("dataFrame.csv");
 dataFrame.write(file);
 DataFrame loadedDataFrame = DataFrame.load(file);
 ```
+
+Values within a DataFrame are accessed using DataRow objects.
+If the source DataFrame changes after a DataRow object is created, the DataRow is invalidated and can no
+longer be accessed.
+
+```java
+
+for(DataRow row : dataFrame){
+    ... = row.getInteger("id");
+}
+
+
+DataRows rows = dataFrame.getRows();
+
+//returns the value within the id column in the first row
+rows.get(0).getInteger("id");
+
+dataFrame.sort("name");
+
+//The DataFrame was sorted after the DataRows were obtained.
+//The first row can now differ. 
+//To avoid these effects, a RuntimeException is thrown
+//if a row that was created before the DataFrame is altered is accessed
+
+rows.get(0).getInteger("id"); //throws exception
+
+rows = dataFrame.getRows();
+
+//rows is now valid again and rows can be accessed
+rows.get(0).getInteger("id");
+
+
+//DataRows can be converted to a new independent DataFrame.
+//changes to the original DataFrame have no effect on the new DataFrame.
+DataFrame dataFrame2 = rows.toDataFrame();
+
+dataFrame.sort("id");
+
+dataFrame.getRow(0).getInteger("id"); // no exception
+```
+
+DataRows can be used to change values within a DataFrame
+
+```java
+DataRows rows = dataFrame.getRows();
+
+//sets the value in the second row in the name column to 'A'
+rows.get(1).set("name","A");
+
+//sets the value in the second row in the first column to 'A'
+rows.get(1).set(0,"A");
+
+
+```
+
 Use indices for fast row access.
-Indices must always be unique.
 ```java
 
 //set the primary key of a data frame
 users.setPrimaryKey("person_id");
-DataRow firstUser = users.findByPrimaryKey(1)
+DataRow firstUser = users.selectByPrimaryKey(1)
 
 //add a multi-column index
 
 users.addIndex("name-address","last_name","address");
 
-//returns all users with the last name Smith in the Example-Street 15
-List<DataRow> user = users.findByIndex("name-address","Smith","Example-Street 15")
+//returns rows containing all users with the last name Smith in the Example-Street 15
+DataRows user = users.selectRowsByIndex("name-address","Smith","Example-Street 15")
 ```
 It is possible to define and use other index types.
 The following example shows interval indices.
@@ -157,17 +284,17 @@ IntervalIndex index = new IntervalIndex("idx",
     dataFrame.getNumberColumn("end"));
 dataFrame.addIndex(index);
 
-//returns rows where (start,end) overlaps with (1,3)
+//returns a new dataframe containing all rows where (start,end) overlaps with (1,3)
 // -> A, B
-dataFrame.findByIndex("idx",1,3);
+DataFrame df = dataFrame.selectByIndex("idx",1,3);
 
-//returns rows where (start,end) overlaps with (4,5)
+//rows where (start,end) overlaps with (4,5)
 // -> C
-dataFrame.findByIndex("idx",4,5);
+dataFrame.selectByIndex("idx",4,5);
 
-//returns rows where (start,end) contains 2.5
+//rows where (start,end) contains 2.5
 // -> A, B
-dataFrame.findByIndex("idx",2.5);
+dataFrame.selectByIndex("idx",2.5);
 ```
 
 Perform operations on columns.

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>de.unknownreality</groupId>
     <artifactId>dataframe</artifactId>
-    <version>0.7.2-SNAPSHOT</version>
+    <version>0.7.5-SNAPSHOT</version>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.source>1.8</maven.compiler.source>

src/main/java/de/unknownreality/dataframe/AutodetectConverter.java

@@ -27,6 +27,7 @@
 /**
  * Created by Alex on 13.03.2016.
  */
+@FunctionalInterface
 public interface ColumnAppender<T extends Comparable<T>> {
     /**
      * Creates the value for a new column in a row