Basics overview part i: strings, paths and streams

Basics overview part I: Strings, Paths and Streams

We don’t give much explanations here. We just give a few examples to get you started. Haking a look at the class headers is then highly recommended, it’s the best way to have an overview of all the functionalities.

1. nglString

// declare a unicode string
nglString myStr(_T("hello"));

// application's log, using the macro NGL_OUT
NGL_OUT(_T("'%ls' is the message of %d characters\n"), myStr.GetChars(), myStr.GetLength());

// get standard strings
std::string s = myStr.GetStdString();
std::wstring sw = myStr.GetStdWString();
char* str = myStr.GetStdString().c_str(); // Be sure to delete str once you don't need it any more!
CFStringRef sr = myStr.ToCFString(); // for MacOSX specific code: convert to a CoreFoundation string

// export/import texts using a specific characters encoding
// check the class header for all versions of Export and Import 
char* pStr = myStr.Export(eUTF8);
myStr.Import("\xe2\x88\x9e", eUTF8);

// format and parse a string, with the current locale or with the ansi C locale
float f = 2.4567f;
myStr.Format(_T("I want %.2f billion dollars"), f);
myStr.CFormat(_T("I want %.2f billion dollars"), f); // the same using the ansi C locale
float f = myStr.GetFloat();
float f = myStr.GetCFloat();
myStr.SetCFloat(f);
// got the same for int, int64, double, etc... 
 
// append
myStr = nglString::Null; // clear
myStr.Append(_T("39556 Survivors"));
myStr = nglString::Null;
myStr.Add(39556).Add(_T(" Survivors"));
// => gives "39556 Survivors"

// compare
bool caseSensitive = false;
int32 res = myStr.Compare(_T("frack"), caseSensitive);
int32 score = myStr.GetLevenshteinDistance(_T("39555 Survivors")); // usefull to build search engines

// tokenize
std::vector<nglString> tokens;
myStr.Tokenize(tokens, _T(' '));
// => tokens {"39556", "Survivors"}

Please check nglString.h to get the complete list of functionalities.

2. nglPath

// declare paths
nglPath myPath(_T("/Users/Baltar/Documents"));
nglPath myPath(ePathUserDocuments); // other system dependant path in nglPath.h

// append
nglPath myPath(ePathUserDocuments); 
myPath += nglString(_T("MyApp")); // doesn't care if it's "MyApp" or "/MyApp"
// => gives "/Users/Baltar/Documents/MyApp"

// folders and files operations on disk
bool res = myPath.IsLeaf(); // file or folder?
if (myPath.IsAbsolute())
  myPath.MakeRelativeTo(nglPath(ePathUser));
myPath.Create(true/*recur.*/); 
myPath.Delete(false/*recur.*/);
// can also Copy, Move, ...

// path operations
nglString myStr = myPath.GetPathName();
nglString filename = myPath.GetNodeName();
nglPath parent = myPath.GetParent();
std::list<nglPath> children;
myPath.GetChildren(&children); 

// open streams to read/write
nglIOStream* pOStream = myPath.OpenWrite();
nglIStream* pIStream = myOtherPath.OpenRead();

// check the next session to know more on streams

3. Streams: files and memory buffers

nglIStream and nglOStream are virtual class to read and write data.
nglIFile and nglOFile inherit from the Streams to read/write from/to a file on disk.
nglIMemory and nglOMemory inherit from the Streams to read/write from/to a buffer in memory.

This way you can easily build generic methods for I/O operations, without being concerned by the nature of the source and destination.
You can also build your own I/O class, inheriting from the Streams.

Make sure to read about VirtualFileSystem to learn how to proprely access files with nui!

3.1) nglIStream

nglIMemory iMem(myBufferPtr, bufferSize);
nglFileSize size = iMem.Available(); // available size according to the current position
int64 nbRead = iMem.Read(myPtr, size, 1);
float myFloat;
iMem.ReadFloat(&myFloat);

// same idea for a nglIFile object

3.2) nglOStream

nglOFile oFile(myPath, eOFileCreate);
if (!oFile.IsOpen())
  return; // error opening the file
oFile.WriteUInt8(&myInt);
oFile.WriteText(myPtr);
oFile.Close();

// same idea for a nglOMemory object

3.3) sample code

A classic I/O procedure written with nui would go like this:

// read an hypothetic object's data from an input stream and store data using the given reference
bool MyClass::ReadMyObject(nglIStream& rInput, MyObject& rObj)
{
   if (!rInput.Read(&rObj.Tag, TAG_SIZE))
    return false;

  if (!rInput.ReadDouble(&rObj.Value))
   return false;

  return true;
}

// now, reading from a file or something else doesn't matter:
MyObject myObj;

nglIFile myFile(myFilePath);
if (!myFile.IsOpen())
  Error();

if (!ReadMyObject(myFile, myObj))
  Error();
myFile.Close();

nglIMemory myMem(myMemBuffer, BufferSize);
if (!ReadMyObject(myMem, myObj))
  Error();

Make sure to read about VirtualFileSystem to learn how to proprely access files with nui!