{{fbdoc item="title" value="ENCODING"}}----
Specifies character format of a text file

{{fbdoc item="syntax"}}##
	[[KeyPgOpen open]] //filename// for {Input|Output|Append} **Encoding** "//utf-8//"|"//utf-16//"|"//utf-32//"|"//ascii//" as [#]//filenum// 
##
{{fbdoc item="param"}}
	##//filename//## for {Input|Output|Append}
		file name to open for ##[[KeyPgInputfilemode Input]]##, ##[[KeyPgOutput Output]]##, or ##[[KeyPgAppend Append]]##
	##**Encoding** "//utf-8//"|"//utf-16//"|"//utf-32//"|"//ascii//"##
		indicates encoding type for the file
	##//filenum//##
		unused file number to associate with the open file

{{fbdoc item="desc"}}
	##**Encoding**## specifies the format for an Unicode text file, so ##[[KeyPgWinput Winput #]]## and ##[[KeyPgPrintPp Print #]]## use the correct encoding.  If omitted from an ##[[KeyPgOpen Open]]## statement, "ascii" encoding is the default.

	Only little endian character encodings are supported at the moment. 
		-"utf8", 
		-"utf16" 
		-"utf32" 
		-"ascii" (the default)

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/fileio/encoding.bas"}}%%(freebasic)
'' This example will:
'' 1) Write a string to a text file with utf-16 encoding
'' 2) Display the byte contents of the file
'' 3) Read the text back from the file
''
'' WSTRING's will work as well but STRING has been
'' used in this example since not all consoles support
'' printing WSTRING's.

'' The name of the file to use in this example
dim f as string
f = "sample.txt"

''
scope
  dim s as string
  s = "FreeBASIC"

  print "Text to write to " + f + ":"
  print s
  print

  '' open a file for output using utf-16 encoding
  '' and print a short message
  open f for output encoding "utf-16" as #1

  '' The ascii string is converted to utf-16
  print #1, s
  close #1
end scope

''
scope
  dim s as string, n as integer

  '' open the same file for binary and read all the bytes
  open f for binary as #1
  n = lof(1)
  s = space( n )
  get #1,,s
  close #1
  
  print "Binary contents of " + f + ":"
  for i as integer = 1 to n
	print hex( asc( mid( s, i, 1 )), 2); " ";
  next
  print
  print

end scope

''
scope
  dim s as string
  
  '' open a file for input using utf-16 encoding
  '' and read back the message
  open f for input encoding "utf-16" as #1

  '' The ascii string is converted from utf-16
  line input #1, s
  close #1

  '' Display the text
  print "Text read from " + f + ":"
  print s
  print
end scope
%%
Output:
%%
Text to write to sample.txt:
FreeBASIC

Binary contents of sample.txt:
FF FE 46 00 72 00 65 00 65 00 42 00 41 00 53 00 49 00 43 00 0D 00 0A 00 

Text read from sample.txt:
FreeBASIC
%%

{{fbdoc item="target"}}
	- Unicode (w)strings are not supported in the DOS port of FreeBASIC

{{fbdoc item="lang"}}
	- Not available in the //[[CompilerOptlang -lang qb]]// dialect unless referenced with the alias ##**""__Encoding""**##.

{{fbdoc item="diff"}}
	- QB had no support for Unicode

{{fbdoc item="see"}}
	- ##[[KeyPgOpen Open]]##

{{fbdoc item="back" value="CatPgFile|File I/O Functions"}}