keith-turner commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132464158
########## File path: README.md ########## @@ -0,0 +1,102 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is a simple library with the goal of providing an extremely +stable API for handling bytes, suitable for use in [Apache Fluo][fluo] and +other projects' APIs.** + +## Features and Goals + +This project aims to fill a void in Java, by providing convenient objects to +represent a sequence of bytes and associated utility classes for situations +when a raw byte array is not appropriate. + +Specifically, it provides a `ByteSequence` interface, analogous to Java's +`CharSequence`, an immutable `Bytes` implementation analogous to Java's +`String`, and a corresponding `BytesBuilder` analogous to Java's +`StringBuilder`. + +The provided classes have appropriate methods for serialization, and proper +equals and hashCode implementations, as well as a comparator for +`ByteSequence`, so they will be suitable for use in `Set`s and as keys in +`Map`s. + +An immutable bytes implementation makes it possible to pass data between APIs +without the need for performance-killing protective copies. This benefit is +compounded if this library is used by multiple projects, as the need to make +protective copies while passing data between a project and its dependency's API +is eliminated. + +This project aims to provide a fluent and intuitive API, with support for +conversions to/from other common types, such as `ByteBuffer`, `byte[]`, and +`CharSequence`/`String`. + +This project requires at least Java 8, and supports `Stream` and functional +APIs where appropriate. + +See this [blog post][blog] for some additional background. + +## Safe for APIs + +Using an external library in a project's API poses some risks to that project, +especially if it and its dependencies depend on different versions of that +library. This project attempts to mitigate those risks, so that it can be used +safely by other projects. + +This project is made safe for reuse in other projects' APIs by adopting the +following principles: + +* Using [Semantic Versioning 2.0.0][semver] to make strong declarations about + backwards-compatibility +* Strongly avoid breaking changes (avoid major version bumps), so that projects + can converge on the latest version required by their code and that of their Review comment: When I read `the latest version required` I found myself wondering if `the latest version of Fluo Bytes required` would be better. I like it because its more precise. I don't like that it adds words I think people could infer (but not completely sure because it all makes perfect sense to me). I am not advocating for this change, it was just a nagging thought I had when reading this. This document frequently uses `this project`. When thinking about the above I started mulling over whether replacing `this project` with `Fluo Bytes` would be a good thing. I have not come to any conclusion. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services