txt: ## encoding.md
  encoding
  
  Combined from primary sources listed below.
  
  # [In IO::Handle](#___top "go to top of document")[§](#(IO::Handle)_method_encoding "direct link")
  
  See primary documentation
  [in context](/type/IO/Handle#method_encoding)
  for **method encoding**.
  
  ```raku
  multi method encoding(IO::Handle:D: --> Str:D)
  multi method encoding(IO::Handle:D: $enc --> Str:D)
  ```
  
  Returns a [`Str`](/type/Str) representing the encoding currently used by the handle, defaulting to `"utf8"`. [`Nil`](/type/Nil) indicates the filehandle is currently in binary mode. Specifying an optional positional `$enc` argument switches the encoding used by the handle; specify [`Nil`](/type/Nil) as encoding to put the handle into binary mode.
  
  The accepted values for encoding are case-insensitive. The available encodings vary by implementation and backend. On Rakudo MoarVM the following are supported:
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  utf8
  utf16
  utf16le
  utf16be
  utf8-c8
  iso-8859-1
  windows-1251
  windows-1252
  windows-932
  ascii
  
  
  ```
  
  
  ```
  
  The default encoding is utf8, which undergoes normalization into Unicode [`NFC`](/type/NFC) (normalization form canonical). In some cases you may want to ensure no normalization is done; for this you can use `utf8-c8`. Before using `utf8-c8` please read [Unicode: Filehandles and I/O](/language/unicode#Filehandles_and_I/O) for more information on `utf8-c8` and [`NFC`](/type/NFC).
  
  As of Rakudo 2018.04 [windows-932](https://en.wikipedia.org/wiki/Code_page_932_(Microsoft_Windows)) is also supported which is a variant of ShiftJIS.
  
  Implementation may choose to also provide support for aliases, e.g. Rakudo allows aliases `latin-1` for `iso-8859-1` encoding and dashed utf versions: `utf-8` and `utf-16`.
  
  # [In IO::CatHandle](#___top "go to top of document")[§](#(IO::CatHandle)_method_encoding "direct link")
  
  See primary documentation
  [in context](/type/IO/CatHandle#method_encoding)
  for **method encoding**.
  
  ```raku
  multi method encoding(IO::CatHandle:D:)
  multi method encoding(IO::CatHandle:D: $new-encoding)
  ```
  
  Sets the invocant's `$.encoding` attribute to the provided value. Valid values are the same as those accepted by [`IO::Handle.encoding`](/type/IO/Handle#method_encoding) (use value [`Nil`](/type/Nil) to switch to binary mode). All source handles, including the active one will use the provided `$.encoding` value.
  
  ```raku
  (my $f1 = 'foo'.IO).spurt: 'I ♥ Raku';
  (my $f2 = 'bar'.IO).spurt: 'meow';
  with IO::CatHandle.new: $f1, $f2 {
      # .encoding is 'utf8' by default:
      .readchars(5).say; # OUTPUT: «I ♥ R␤»
  
      .encoding: Nil; # switch to binary mode
      .slurp.say; # OUTPUT: «Buf[uint8]:0x<6B 75 6D 65 6F 77>␤»
  }
  
  ```
  