التابع IO.readpartial في روبي
يقرأ التابع readpartial من مجرى د/خ maxlen (انظر فقرة البنية العامة) بايتًا على الأكثر .
لن يقوم التابع readpartial بالتعطيل (block) إلا في حال لم يكن في مجرى د/خ أي بيانات متوفرة آنيًا. أي أنه لن يُعطِّل في حالة توفر بعض البيانات.
في حال إعطاء الوسيط الاختياري outbuf (انظر فقرة البنية العامة)، فينبغي أن يشير إلى سلسلة نصية، والتي ستتلقى البيانات. لن يحتوي الوسيط outbuf إلا البيانات المستلمة بعد استدعاء التابع، حتى لو لم يكن فارغاً في البداية.
يُطلق التابع readpartial الاستثناء EOFError عند نهاية الملف.
صُمِّم التابع readpartial لأجل المجاري (streams) من مِثل الأنابيب (pipes)، والمقابس (sockets)، والطرفية tty، إلخ. ولن يقوم بالتعطيل إلا عند عدم توفر أية بيانات فوريا. هذا يعني أنه سيُعطّل فقط عند تحقق جميع الشروط التالية.
- ذاكرة التخزين المؤقت للبايت (byte buffer) في مجرى د/خ فارغة.
- محتوى المجرى فارغ.
- المجرى لم يبلغ محرف نهاية الملف (EOF).
عندما يقوم التابع readpartial بالتعطيل، فإنه ينتظر البيانات أو محرف نهاية الملف EOF من المجرى. فإذا حصل التابع readpartial على بيانات، فسيعيدها. أما إذا وصل إلى محرف نهاية الملف، فسيُطلق الاستثناء EOFError.
عندما لا يقوم التابع readpartial بالتعطيل، فسيقوم بالعودة، أو يطلق استثناء على الفور. وإذا لم يكن المخزن المؤقت للبايت فارغًا، فسيُعيد البيانات الموجودة في المخزن المؤقت. وإلا إن كان في المجرى بعض المحتويات، فسيعيدها. خلا ذلك، إذا وصل المجرى إلى محرف نهاية الملف، فسيطلق الاستثناء EOFError.
لاحظ أن التابع readpartial يتصرف بشكل مشابه للتابع sysread. لكن مع الاختلافات التالية:
- إذا لم يكن المخزن المؤقت للبايت فارغاً، فسيُقرء من المخزن المؤقت للبايت بدلاً من القراءة من المخزن المؤقت لمجرى د/خ كما يفعل
sysread. - لا يتسبب في الخطأين
Errno::EWOULDBLOCKوErrno::EINTR. عندما يصادف التابعreadpartialالخطأينEWOULDBLOCKوEINTRالناتجين عن استدعاء النظامread، سيحاول إعادة استدعاء النظام.
هذا الأخير يعني أن التابع readpartial غير حساس لقيمة الراية nonblocking. سيقوم بالتعطيل في الحالات التي يقوم فيها التابع sysread بإطلاق الخطأ Errno::EWOULDBLOCK، كما لو كان fd (واصف الملف) في وضع التعطيل (blocking mode).
البنية العامة
readpartial(maxlen) → string
readpartial(maxlen, outbuf)→ outbuf
المعاملات
maxlen
عدد صحيح يمثل الحد الأقصى
outbuf
سلسلة نصية تتلقى البيانات
القيمة المُعادة
يعيد التابع readpartial السلسلة النصية المقروءة.
أمثلة
مثال على استخدام التابع readpartial:
r, w = IO.pipe # buffer pipe content
w << "abc" # "" "abc".
r.readpartial(4096) #=> "abc" "" ""
r.readpartial(4096) # blocks because buffer and pipe is empty.
r, w = IO.pipe # buffer pipe content
w << "abc" # "" "abc"
w.close # "" "abc" EOF
r.readpartial(4096) #=> "abc" "" EOF
r.readpartial(4096) # raises EOFError
r, w = IO.pipe # buffer pipe content
w << "abc\ndef\n" # "" "abc\ndef\n"
r.gets #=> "abc\n" "def\n" ""
w << "ghi\n" # "def\n" "ghi\n"
r.readpartial(4096) #=> "def\n" "" "ghi\n"
r.readpartial(4096) #=> "ghi\n" "" ""