github.com/influx6/npkg@v0.8.8/nbytes/Readme.md (about)

     1  ByteStream
     2  ---------
     3  Bytes provides a delimited stream reader and writer which will encoded a sequence of giving byte set 
     4  with a giving character set as ending, a delimiter sort of to indicate to it's reader that this is the end 
     5  of this set. It escapes the delimiter if it appears within the byte sequence to ensure preservation. 
     6  
     7  It is useful when multiplexing multiple streams of bytes over a connection where we wish to send 
     8  multiple messages without the use of size headers where we prefix the size of giving stream before sequence 
     9  of bytes, this becomes useful when you have memory restrictions and can't know total size of incoming bytes 
    10  unless fully read out which is not efficient has you may get to use up memory just trying to read up all available
    11  data which maybe more larger than available memory.
    12  
    13  By using sequenced based delimiting we can solve this and still adequately convey the ending and beginning 
    14  of a new message stream, which becomes powerful when handling larger and never-ending incoming data.
    15  
    16  
    17  ## Install
    18  
    19  ```bash
    20  go get -u github.com/influx6/npkg/nbytes
    21  ```
    22  
    23  
    24  ## Example
    25  
    26  
    27  - Multiplexed Streaming
    28  
    29  ```go
    30  var dest bytes.Buffer
    31  writer := &mb.DelimitedStreamWriter{
    32  	Dest:      &dest,
    33  	Escape:    []byte(":/"),
    34  	Delimiter: []byte("//"),
    35  }
    36  
    37  sentences := []string{
    38  	"I went into park stream all alone before the isle lands.",
    39  	"Isle lands of YOR, before the dream verse began we found the diskin.",
    40  	"Break fast in bed, love and eternality for ever",
    41  	"Awaiting the ending seen of waiting for you?",
    42  	"Done be such a waste!",
    43  	"{\"log\":\"token\", \"centry\":\"20\"}",
    44  }
    45  
    46  for _, sentence := range sentences {
    47  	written, err := writer.Write([]byte(sentence))
    48  	streamWritten, err := writer.End()
    49  }
    50  
    51  reader := &mb.DelimitedStreamReader{
    52  	Src:       bytes.NewReader(dest.Bytes()),
    53  	Escape:    []byte(":/"),
    54  	Delimiter: []byte("//"),
    55  }
    56  
    57  for index, sentence := range sentences {
    58  	res := make([]byte, len(sentence))
    59  	read, err := reader.Read(res)
    60  	
    61  	// if we are end of stream segment, continue
    62  	if err != nil && err == ErrEOS {
    63  		continue
    64  	}
    65  }
    66  
    67  ```
    68  
    69  - DelimitedStreamWriter
    70  
    71  ```go
    72  var dest bytes.Buffer
    73  writer := &mb.DelimitedStreamWriter{
    74  	Dest:      &dest,
    75  	Escape:    []byte(":/"),
    76  	Delimiter: []byte("//"),
    77  }
    78  
    79  written, err := writer.Write([]byte("Wondering out the clouds"))
    80  written, err := writer.Write([]byte("of endless streams beyond the shore"))
    81  totalWritten, err := writer.End()
    82  ```
    83  
    84  
    85  - DelimitedStreamWriter
    86  
    87  ```go
    88  var dest bytes.Buffer
    89  writer := &mb.DelimitedStreamWriter{
    90  	Dest:      &dest,
    91  	Escape:    []byte(":/"),
    92  	Delimiter: []byte("//"),
    93  }
    94  
    95  written, err := writer.Write([]byte("Wondering out the clouds"))
    96  written, err := writer.Write([]byte("of endless streams beyond the shore"))
    97  totalWritten, err := writer.End()
    98  ```
    99  
   100  -- DelimitedStreamReader 
   101  
   102  ```go
   103  reader := &mb.DelimitedStreamReader{
   104  	Src:       strings.NewReader("Wondering out the :/:///clouds of endless :///streams beyond the shore//"),
   105  	Escape:    []byte(":/"),
   106  	Delimiter: []byte("//"),
   107  }
   108  
   109  res := make([]byte, len(spec.In))
   110  read, err := reader.Read(res)
   111  ```