README in bindata-1.0.0 vs README in bindata-1.1.0

- old
+ new

@@ -46,10 +46,22 @@ Copyright &copy; 2007 - 2009 [Dion Mendel](mailto:dion@lostrealm.com) --------------------------------------------------------------------------- +# Installation + +You can install BinData via rubygems. + + gem install bindata + +Alternatively, visit the +[download](http://rubyforge.org/frs/?group_id=3252) page and download +BinData as a tar file. + +--------------------------------------------------------------------------- + # Overview BinData declarations are easy to read. Here's an example. class MyFancyFormat < BinData::Record @@ -246,12 +258,14 @@ : is the name of a supplied type (e.g. `uint32be`, `string`, `array`) or a user defined type. For user defined types, the class name is converted from `CamelCase` to lowercased `underscore_style`. `field_name` -: is the name by which you can access the data. Use either a - `String` or a `Symbol`. +: is the name by which you can access the field. Use either a + `String` or a `Symbol`. If name is nil or the empty string, then + this particular field is anonymous. An anonymous field is still + read and written, but will not appear in `#snapshot`. Each field may have optional *parameters* for how to process the data. The parameters are passed as a `Hash` with `Symbols` for keys. Parameters are designed to be lazily evaluated, possibly multiple times. This means that any parameter value must not have side effects. @@ -915,9 +929,37 @@ {:ruby} --------------------------------------------------------------------------- # Advanced Topics + +## Skipping over unused data + +Some binary structures contain data that is irrelevant to your purposes. + +Say you are interested in 50 bytes of data located 10 megabytes into the +stream. One way of accessing this useful data is: + + class MyData < BinData::Record + string :length => 10 * 1024 * 1024 + string :data, :length => 50 + end +{:ruby} + +The advantage of this method is that the irrelevant data is preserved +when writing the record. The disadvantage is that even if you don't care +about preserving this irrelevant data, it still occupies memory. + +If you don't need to preserve this data, an alternative is to use +`skip` instead of `string`. When reading it will seek over the irrelevant +data and won't consume space in memory. When writing it will write +`:length` number of zero bytes. + + class MyData < BinData::Record + skip :length => 10 * 1024 * 1024 + string :data, :length => 50 + end +{:ruby} ## Wrappers Sometimes you wish to create a new type that is simply an existing type with some predefined parameters. Examples could be an array with a