This is the save-to-disk facility. A DataStream can store one or more objects in a persistent form.

To handle objects with sharing and cycles, you must use a
ReferenceStream instead of a DataStream. (Or SmartRefStream.) ReferenceStream is typically
faster and produces smaller files because it doesn't repeatedly write the same Symbols.

Here is the way to use DataStream and ReferenceStream:
rr _ ReferenceStream fileNamed: 'test.obj'.
rr nextPut: <your object>.
rr close.

To get it back:
rr _ ReferenceStream fileNamed: 'test.obj'.
<your object> _ rr next.
rr close.

Each object to be stored has two opportunities to control what gets stored. On the high level, objectToStoreOnDataStream allows you to substitute another object on the way out. The low level hook is storeDataOn:. The read-in counterparts to these messages are comeFullyUpOnReload and (class) readDataFrom:size:. See these methods, and the class DiskProxy, for more information about externalizing and internalizing.

NOTE: A DataStream should be treated as a write-stream for writing. It is a read-stream for reading. It is not a ReadWriteStream.

write and read

beginInstance:size: beginReference: getCurrentReference maybeBeginReference: next nextPut: nextPutAll: noteCurrentReference: objectAt: objectIfBlocked: outputReference: readArray readBitmap readBoolean readByteArray readClass readFalse readFloat readFloatString readInstance readInteger readMethod readNil readRectangle readReference readShortInst readShortRef readString readStringOld readSymbol readTrue readUser readWordArray readWordArrayForSegment readWordLike replace:with: setCurrentReference: tryToPutReference:typeID: typeIDFor: writeArray: writeBitmap: writeBoolean: writeByteArray: writeClass: writeFalse: writeFloat: writeFloatString: writeInstance: writeInteger: writeNil: writeRectangle: writeString: writeStringOld: writeSymbol: writeTrue: writeUser: writeWordLike:

	other	top
	atEnd Answer true if the stream is at the end.
	byteStream
	close Close the stream.
	errorWriteReference: PRIVATE -- Raise an error because this case of nextPut:Õs perform: shouldn't be called. -- 11/15/92 jhm
	flush Guarantee that any writes to me are actually recorded on disk. -- 11/17/92 jhm
	next: Answer an Array of the next anInteger objects in the stream.
	nextAndClose Speedy way to grab one object. Only use when we are inside an object binary file. Do not use for the start of a SmartRefStream mixed code-and-object file.
	project
	reset Reset the stream.
	rootObject Return the object at the root of the tree we are filing out.
	rootObject: Return the object at the root of the tree we are filing out.
	setStream: PRIVATE -- Initialization method.
	setStream:reading: PRIVATE -- Initialization method.
	size Answer the stream's size.
	vacantRef Answer the magic 32-bit constant we use ***ON DISK*** as a stream 'reference position' to identify a reference that's not yet filled in. This must be a value that won't be used as an ordinary reference. Cf. outputReference: and readReference. -- NOTE: We could use a different type ID for vacant-refs rather than writing object-references with a magic value. (The type ID and value are overwritten by ordinary object-references when weak refs are fullfilled.)

	write and read	top
	beginInstance:size: This is for use by storeDataOn: methods. Cf. Object>>storeDataOn:.
	beginReference: WeÕre starting to read anObject. Remember it and its reference position (if we care; ReferenceStream cares). Answer the reference position.
	getCurrentReference PRIVATE -- Return the currentReference posn. Overridden by ReferenceStream.
	maybeBeginReference: Do nothing. See ReferenceStream|maybeBeginReference:
	next Answer the next object in the stream.
	nextPut: Write anObject to the receiver stream. Answer anObject.
	nextPutAll: Write each of the objects in aCollection to the receiver stream. Answer aCollection.
	noteCurrentReference: PRIVATE -- If we support references for type typeID, remember the current byteStream position so we can add the next object to the ÔobjectsÕ dictionary, and return true. Else return false. This method is here to be overridden by ReferenceStream
	objectAt: PRIVATE -- Read & return the object at a given stream position. 08:18 tk anInteger is a relative file position.
	objectIfBlocked: We don't do any blocking
	outputReference: PRIVATE -- Output a reference to the object at integer stream position referencePosn (relative to basePos). To output a weak reference to an object not yet written, supply (self vacantRef) for referencePosn.
	readArray PRIVATE -- Read the contents of an Array. We must do beginReference: here after instantiating the Array but before reading its contents, in case the contents reference the Array. beginReference: will be sent again when we return to next, but that's ok as long as we save and restore the current reference position over recursive calls to next.
	readBitmap PRIVATE -- Read the contents of a Bitmap.
	readBoolean PRIVATE -- Read the contents of a Boolean. This is here only for compatibility with old data files.
	readByteArray PRIVATE -- Read the contents of a ByteArray.
	readClass Should never be executed because a DiskProxy, not a clas comes in.
	readFalse PRIVATE -- Read the contents of a False.
	readFloat PRIVATE -- Read the contents of a Float. This is the fast way to read a Float. We support 8-byte Floats here. Non-IEEE
	readFloatString PRIVATE -- Read the contents of a Float string. This is the slow way to read a Float--via its string repÕn. It's here for compatibility with old data files.
	readInstance PRIVATE -- Read the contents of an arbitrary instance. ASSUMES: readDataFrom:size: sends me beginReference: after it instantiates the new object but before reading nested objects. NOTE: We must restore the current reference position after recursive calls to next. Let the instance, not the class read the data.
	readInteger PRIVATE -- Read the contents of a SmallInteger.
	readMethod PRIVATE -- Read the contents of an arbitrary instance. ASSUMES: readDataFrom:size: sends me beginReference: after it instantiates the new object but before reading nested objects. NOTE: We must restore the current reference position after recursive calls to next. Let the instance, not the class read the data.
	readNil PRIVATE -- Read the contents of an UndefinedObject.
	readRectangle Read a compact Rectangle. Rectangles with values outside +/- 2047 were stored as normal objects (type=9). They will not come here. 17:22 tk
	readReference Read the contents of an object reference. (Cf. outputReference:) File is not now positioned at this object.
	readShortInst Read the contents of an arbitrary instance that has a short header. ASSUMES: readDataFrom:size: sends me beginReference: after it instantiates the new object but before reading nested objects. NOTE: We must restore the current reference position after recursive calls to next. Let the instance, not the class read the data.
	readShortRef Read an object reference from two bytes only. Original object must be in first 65536 bytes of the file. Relative to start of data. vacantRef not a possibility.
	readString
	readStringOld
	readSymbol PRIVATE -- Read the contents of a Symbol.
	readTrue PRIVATE -- Read the contents of a True.
	readUser Reconstruct both the private class and the instance. Still used??
	readWordArray PRIVATE -- Read the contents of a WordArray.
	readWordArrayForSegment Read the contents of a WordArray ignoring endianness.
	readWordLike Can be used by any class that is bits and not bytes (WordArray, Bitmap, SoundBuffer, etc).
	replace:with: We may wish to remember that in some field, the original object is being replaced by the proxy. For the hybred scheme that collects with a DummyStream and writes an ImageSegment, it needs to hold onto the originals so they will appear in outPointers, and be replaced.
	setCurrentReference: PRIVATE -- Set currentReference to refPosn. Noop here. Cf. ReferenceStream.
	tryToPutReference:typeID: PRIVATE -- If we support references for type typeID, and if anObject already appears in my output stream, then put a reference to the place where anObject already appears. If we support references for typeID but didnÕt already put anObject, then associate the current stream position with anObject in case one wants to nextPut: it again. Return true after putting a reference; false if the object still needs to be put. For DataStream this is trivial. ReferenceStream overrides this.
	typeIDFor: Return the typeID for anObject's class. This is where the tangle of objects is clipped to stop everything from going out. Classes can control their instance variables by defining objectToStoreOnDataStream. Any object in blockers is not written out. See ReferenceStream.objectIfBlocked: and DataStream nextPut:. Morphs do not write their owners. See Morph.storeDataOn: Each morph tells itself to 'prepareToBeSaved' before writing out.
	writeArray: PRIVATE -- Write the contents of an Array.
	writeBitmap: PRIVATE -- Write the contents of a Bitmap.
	writeBoolean: PRIVATE -- Write the contents of a Boolean. This method is now obsolete.
	writeByteArray: PRIVATE -- Write the contents of a ByteArray.
	writeClass: Write out a DiskProxy for the class. It will look up the class's name in Smalltalk in the new sustem. Never write classes or methodDictionaries as objects. For novel classes, front part of file is a fileIn of the new class.
	writeFalse: PRIVATE -- Write the contents of a False.
	writeFloat: PRIVATE -- Write the contents of a Float. We support 8-byte Floats here.
	writeFloatString: PRIVATE -- Write the contents of a Float string. This is the slow way to write a Float--via its string repÕn.
	writeInstance: PRIVATE -- Write the contents of an arbitrary instance.
	writeInteger: PRIVATE -- Write the contents of a SmallInteger.
	writeNil: PRIVATE -- Write the contents of an UndefinedObject.
	writeRectangle: Write the contents of a Rectangle. See if it can be a compact Rectangle (type=15). Rectangles with values outside +/- 2047 were stored as normal objects (type=9). 17:22 tk
	writeString: PRIVATE -- Write the contents of a String.
	writeStringOld: PRIVATE -- Write the contents of a String.
	writeSymbol: PRIVATE -- Write the contents of a Symbol.
	writeTrue: PRIVATE -- Write the contents of a True.
	writeUser: Write the contents of an arbitrary User instance (and its devoted class).
	writeWordLike: Note that we put the class name before the size.

	as yet unclassified	top
	example An example and test of DataStream/ReferenceStream. 11/19/92 jhm: Use self testWith:.
	exampleWithPictures DataStream exampleWithPictures
	fileNamed: Here is the way to use DataStream and ReferenceStream: rr _ ReferenceStream fileNamed: 'test.obj'. rr nextPut: <your object>. rr close.
	initialize TypeMap maps Smalltalk classes to type ID numbers which identify the data stream primitive formats. nextPut: writes these IDs to the data stream. NOTE: Changing these type ID numbers will invalidate all extant data stream files. Adding new ones is OK. Classes named here have special formats in the file. If such a class has a subclass, it will use type 9 and write correctly. It will just be slow. (Later write the class name in the special format, then subclasses can use the type also.) See nextPut:, next, typeIDFor:, & ReferenceStream>>isAReferenceType:
	new Answer a new instance of the receiver (which is a class) with no indexable variables. Fail if the class is indexable.
	newFileNamed: Here is the way to use DataStream and ReferenceStream: rr _ ReferenceStream fileNamed: 'test.obj'. rr nextPut: <your object>. rr close.
	oldFileNamed: Here is the way to use DataStream and ReferenceStream: rr _ ReferenceStream oldFileNamed: 'test.obj'. ^ rr nextAndClose.
	on: Open a new DataStream onto a low-level I/O stream.
	streamedRepresentationOf:
	testWith: As a test of DataStream/ReferenceStream, write out anObject and read it back. 11/19/92 jhm: Set the file type. More informative file name.
	unStream: