History

Basics overview part I: Strings, Paths and Streams¶

Basics overview part I: Strings, Paths and Streams
1. nglString
2. nglPath
3. Streams: files and memory buffers
3.1) nglIStream
3.2) nglOStream
3.3) sample code

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¶

 1 // declare a unicode string
 2 nglString myStr(_T("hello"));
 3 
 4 // application's log, using the macro NGL_OUT
 5 NGL_OUT(_T("'%ls' is the message of %d characters\n"), myStr.GetChars(), myStr.GetLength());
 6 
 7 // get standard strings
 8 std::string s = myStr.GetStdString();
 9 std::wstring sw = myStr.GetStdWString();
10 char* str = myStr.GetStdString().c_str(); // Be sure to delete str once you don't need it any more!
11 CFStringRef sr = myStr.ToCFString(); // for MacOSX specific code: convert to a CoreFoundation string
12 
13 // export/import texts using a specific characters encoding
14 // check the class header for all versions of Export and Import 
15 char* pStr = myStr.Export(eUTF8);
16 myStr.Import("\xe2\x88\x9e", eUTF8);
17 
18 // format and parse a string, with the current locale or with the ansi C locale
19 float f = 2.4567f;
20 myStr.Format(_T("I want %.2f billion dollars"), f);
21 myStr.CFormat(_T("I want %.2f billion dollars"), f); // the same using the ansi C locale
22 float f = myStr.GetFloat();
23 float f = myStr.GetCFloat();
24 myStr.SetCFloat(f);
25 // got the same for int, int64, double, etc... 
26 
27 // append
28 myStr = nglString::Null; // clear
29 myStr.Append(_T("39556 Survivors"));
30 myStr = nglString::Null;
31 myStr.Add(39556).Add(_T(" Survivors"));
32 // => gives "39556 Survivors" 
33 
34 // compare
35 bool caseSensitive = false;
36 int32 res = myStr.Compare(_T("frack"), caseSensitive);
37 int32 score = myStr.GetLevenshteinDistance(_T("39555 Survivors")); // usefull to build search engines
38 
39 // tokenize
40 std::vector<nglString> tokens;
41 myStr.Tokenize(tokens, _T(' '));
42 // => tokens {"39556", "Survivors"}

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

2. nglPath¶

 1 
 2 // declare paths
 3 nglPath myPath(_T("/Users/Baltar/Documents"));
 4 nglPath myPath(ePathUserDocuments); // other system dependant path in nglPath.h
 5 
 6 // append
 7 nglPath myPath(ePathUserDocuments); 
 8 myPath += nglString(_T("MyApp")); // doesn't care if it's "MyApp" or "/MyApp" 
 9 // => gives "/Users/Baltar/Documents/MyApp" 
10 
11 // folders and files operations on disk
12 bool res = myPath.IsLeaf(); // file or folder?
13 if (myPath.IsAbsolute())
14   myPath.MakeRelativeTo(nglPath(ePathUser));
15 myPath.Create(true/*recur.*/); 
16 myPath.Delete(false/*recur.*/);
17 // can also Copy, Move, ...
18 
19 // path operations
20 nglString myStr = myPath.GetPathName();
21 nglString filename = myPath.GetNodeName();
22 nglPath parent = myPath.GetParent();
23 std::list<nglPath> children;
24 myPath.GetChildren(&children); 
25 
26 // open streams to read/write
27 nglIOStream* pOStream = myPath.OpenWrite();
28 nglIStream* pIStream = myOtherPath.OpenRead();
29 
30 // 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 the virtual file system to learn how to proprely access files with nui!

3.1) nglIStream¶

1   nglIMemory iMem(myBufferPtr, bufferSize);
2   nglFileSize size = iMem.Available(); // available size according to the current position
3   int64 nbRead = iMem.Read(myPtr, size, 1);
4   float myFloat;
5   iMem.ReadFloat(&myFloat);
6 
7   // same idea for a nglIFile object

3.2) nglOStream¶

1   nglOFile oFile(myPath, eOFileCreate);
2   if (!oFile.IsOpen())
3     return; // error opening the file
4   oFile.WriteUInt8(&myInt);
5   oFile.WriteText(myPtr);
6   oFile.Close();
7 
8   // same idea for a nglOMemory object

3.3) sample code¶

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

 1 // read an hypothetic object's data from an input stream and store data using the given reference
 2 bool MyClass::ReadMyObject(nglIStream& rInput, MyObject& rObj)
 3 {
 4    if (!rInput.Read(&rObj.Tag, TAG_SIZE))
 5     return false;
 6 
 7   if (!rInput.ReadDouble(&rObj.Value))
 8    return false;
 9 
10   return true;
11 }
12 
13 // now, reading from a file or something else doesn't matter:
14 MyObject myObj;
15 
16 nglIFile myFile(myFilePath);
17 if (!myFile.IsOpen())
18   Error();
19 
20 if (!ReadMyObject(myFile, myObj))
21   Error();
22 myFile.Close();
23 
24 nglIMemory myMem(myMemBuffer, BufferSize);
25 if (!ReadMyObject(myMem, myObj))
26   Error();