txt: ## dist_github-scovit-NativeHelpers-CBuffer.md
  [![Build Status](https://travis-ci.org/scovit/NativeHelpers-CBuffer.svg?branch=master)](https://travis-ci.org/scovit/NativeHelpers-CBuffer)
  
  # NAME
  
  NativeHelpers::CBuffer - A type for storing a caller allocated Buffer
  
  # SYNOPSIS
  
  ```
      use NativeHelpers::CBuffer;
  
     class CBuffer is repr('CPointer') is export
  
  ```
  
  The CBuffer object, is `repr("CPointer")`, as such, it can be directly used in
  `NativeCall` signatures in the place of a Pointer.
  
  # DESCRIPTION
  
  NativeHelpers::CBuffer is a convinent way to store buffers and C NULL terminated strings
  
  # EXAMPLE
  
  ```
      use NativeHelpers::CBuffer;
  
      my CBuffer $buf = CBuffer.new(100); # Allocates a buffer of 100 bytes
  
      sub strncpy(CBuffer, Str, size_t) is native { };
      strncpy($buf, "Uella!", 100);
  
      say $buf; # Uella!
  
  ```
  
  # METHODS
  
  ## multi new (Int)
  
  ```
      multi method new(Int $size, :$with, :$of-type where { $of-type ∈ $types } = uint8)
  
  ```
  
  Allocates a buffer of size `$size` elements, of type `$of-type` and with content a copy of `$with`.
  Where `$with` can be either a Str or a Blob, and `$of-type` can be any of:
  
  ```
      my $types = (uint8, int8, uint16, int16, uint32, int32, uint64, int64, size_t, long, ulong, longlong, ulonglong);
  
  ```
  
  ## multi new (Blob)
  
  ```
      multi method new(Blob $init)
  
  ```
  
  Allocates a buffer and store the content of the `$init` parameter.
  
  ## multi new (Str)
  
  ```
      multi method new(Str $init)
  
  ```
  
  Allocates a buffer and store the content of the `$init` parameter as a NULL-terminated ASCII string.
  
  ## elems
  
  ```
      method elems(--> Int:D)
  
  ```
  
  Return the number of elements stored
  
  ## bytes
  
  ```
      method bytes(--> Int:D)
  
  ```
  
  Return the number of bytes stored
  
  ## type
  
  ```
      method type()
  
  ```
  
  Return the type of the elements stored
  
  ## Blob
  
  ```
      method Blob(--> Blob:D)
  
  ```
  
  Return a copy of the content as a Blob
  
  ## Pointer
  
  ```
      method Pointer(--> Pointer)
  
  ```
  
  Return the pointer to the allocated buffer of type Pointer[self.type]
  
  ## Str
  
  ```
      method Str(--> Str:D)
  
  ```
  
  Return a Str with the content decoded as null-terminated ASCII
  
  ## gist
  
  same as `method Str`
  
  ## free
  
  ```
       method free()
  
  ```
  
  Calls `free` the allocated buffer
  
  # BUGS, TODOS and WARNINGS
  
  At the moment, the `CBuffer` is immutable on the `perl` side,
  once created and initialized, it's content can be modified only
  by `C` functions. At the moment, the CBuffer is not resizable.
  
  The `CBuffer` uses `NativeCall` to allocate memory, beware of not
  using `CBuffer` in modules to allocate runtime memory during compilation.
  In other words, do not use `CBuffer.new` in `BEGIN` blocks or `constant`
  declarations, any abuse will result in Segmentation faults and/or
  memory corruption!
  
  In order to declare `C`-stile `#define` constants in modules,
  use `perl` sub (or macro) instead:
  
  ```
     # the following, is equivalent to
       #define STRING_CONST     "The string"
  
     sub STRING_CONST is export { CBuffer.new("The string") };
  
  ```
  
  # AUTHOR
  
  Vittore F. Scolari [vittore.scolari@pasteur.fr](mailto:vittore.scolari@pasteur.fr)
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2017 Institut Pasteur
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  